Deployment

The application is deployed through a Heroku Pipeline with separate staging and production environments. Temporary Review Apps can also be created from GitHub pull requests when a change benefits from testing in an isolated deployed environment.

The deployment process is designed so that the same application code moves through each environment while configuration remains specific to that environment.

Deployment Workflow

Application changes normally move through the following workflow:

Development is completed locally in a Git branch.
The branch is pushed to GitHub and a pull request is created.
Automated tests verify the proposed change.
A temporary Heroku Review App can be created when deployed testing or review is useful.
After review, the pull request is merged into the main branch.
The updated application is deployed to the persistent staging environment.
Changes are tested in staging.
The staging release is manually promoted to production.

Review Apps are optional rather than a required deployment stage. Small or well-isolated changes may move directly from pull-request review to staging, while more substantial changes can be exercised in their own temporary environment before being merged.

Environments

The project uses several types of environment, each with a different purpose.

Local development

The local environment is used for implementation and routine testing. Development configuration favors local services where practical and does not require production credentials or production data.

Review Apps

Heroku Review Apps provide temporary deployed environments associated with individual pull requests.

They are useful when a change needs to be reviewed outside a developer’s local environment or when behavior depends on characteristics of the deployed platform.

Review Apps are disposable and are not used for persistent application data.

Staging

Staging is a persistent environment used for integration testing and final review before production deployment.

It runs the application in an environment that closely resembles production while maintaining separate configuration and data.

Production

Production is the public application environment.

Changes reach production by promotion through the Heroku Pipeline after they have been tested in staging. Application code is not edited directly in the production environment.

Configuration

Application configuration is kept separate from the deployed code.

Each Heroku environment provides its own configuration through Config Vars. This allows the same source code to run with environment-specific database connections, credentials, storage configuration, email settings, and other service configuration.

Secrets and environment-specific values are not committed to the Git repository.

Review Apps receive only the configuration required for them to operate. Access to external production services should not be assumed simply because an application has been deployed to a Review App.

Database Migrations

Database schema changes are managed through Django migrations and committed to source control with the code that requires them.

Migrations are tested before production deployment and are applied as part of the deployment process.

Schema changes should be designed with the deployment sequence in mind. Where a change cannot safely be introduced in a single deployment, the application and database changes should be separated into compatible steps rather than assuming that code and schema changes occur simultaneously.

This is particularly important when modifying or removing fields that are already used by deployed application code.

Static Files

Static application assets are collected during deployment and stored in Amazon S3.

CloudFront provides the public delivery layer for static files and uploaded media. The underlying S3 bucket remains private and grants CloudFront access through Origin Access Control.

Application code therefore references the configured storage backend rather than depending on files stored on the application’s local filesystem.

Heroku application instances are disposable, so persistent files should never depend on the instance filesystem.

Promotion to Production

Production deployment is an explicit action rather than an automatic consequence of merging a pull request.

After a change has been deployed and tested in staging, the staging release is promoted to production through the Heroku Pipeline.

This creates a deliberate checkpoint between testing and public release while ensuring that the release promoted to production is the same application build that was tested in staging.

After deployment, changes that affect important application behavior should be verified in the production environment rather than assuming that a successful deployment alone confirms correct operation.

Rollback

Application releases are maintained by the deployment platform, allowing a previous release to be restored if a newly deployed version introduces a serious problem.

Rollback is one part of recovery rather than a substitute for understanding the failure. A code rollback may restore an earlier application release, but it does not necessarily reverse database migrations, external service changes, or data modified while the affected release was running.

Changes involving persistent data or external systems therefore require additional consideration when planning both deployment and recovery.

Deployment Principles

The deployment process follows several practical rules:

The same application code moves between deployed environments.
Configuration belongs to the environment rather than the repository.
Production changes pass through staging before release.
Review Apps provide additional isolation when useful but are not mandatory.
Production deployment is deliberate rather than automatic.
Deployed application instances are disposable.
A successful deployment is followed by verification of the affected functionality.
Recovery considerations are part of planning changes that affect persistent data.

The objective is not to make deployment complicated. It is to provide predictable checkpoints between development and production so that changes can be tested, reviewed, released, and recovered in a controlled way.