Each time you push a change to your app through Git or activate an environment, your app goes through a process to be built and deployed. If your app is redeployed with no changes to its codebase, the output of the previous build and deploy process is reused. The build process looks through the configuration files in your repository and assembles the necessary containers. The deploy process makes those containers live, replacing any previous versions, with minimal interruption in service.
Hooks are points in the build and deploy process where you can inject a custom script.
The build
The outcome of the build process is designed to be repeatable and reusable. Each app in a project is built separately. Container configuration depends exclusively on your configuration files. So each container is tied to a specific Git commit. If there are no new changes for a given container, the existing container can be reused. This saves you the time the build step would take. This means the build is independent of the given environment and preview environments are perfect copies of production. If you use environment variables to set up different build configuration options for different environments, your build step isn’t reused and your preview environments may differ from production. You can’t connect to services (like databases) during the build step. Once the app has gone through all of the build steps, it can connect to services in the deploy process.
Build steps
1
2
3
4
5
6
The deploy
The deploy process connects each container from the build process and any services. The connections are defined in your app and services configuration. So unlike the build process, you can now access other containers, but the file system is read-only.
Deploy steps
1
2
3
4
5
6
7
After the deploy process is over, any commands in your post_deploy hook are run.
Deployment types
Upsun supports two deployment types - automatic and manual. These types help to provide control over when changes are applied to development, staging and production environments.
Automatic deployment (default)
This is the default behavior for all environments. With automatic deployment, changes like code pushes and variable updates are deployed immediately. This type of deployment is best suited for rapid iteration during development.
Manual deployment
You can deploy applications manually in any environment type (development/preview, staging, and production). When enabled, manual deployment lets you control when deployments happen: changes are staged but not deployed until you explicitly trigger a deployment. Manual deployment is ideal for teams that want to bundle multiple changes and deploy them together in a controlled manner. When manual deployment is enabled in an environment, the following actions are queued until deployment is triggered:
| Category | Staged Activities |
|---|---|
| Code | environment.push, environment.merge, environment.merge-pr |
| Variables | environment.variable.create, update, delete |
| Resources | environment.resources.update |
| Domains & Routes | environment.domain.*, environment.route.* |
| Subscription | environment.subscription.update |
| Environment Settings | environment.update.http_access, smtp, restrict_robots |
Change deployment type
You can adjust deployment behavior in your environment.
Using the CLI
Using the Console
Use the following command in the CLI to view or change the deployment type:
The output should look similar to the example below:
To switch to manual, navigate to the environment settings in the Console and select the manual deployments option.
Trigger deployment manually
Once manual deployment is enabled, eligible changes are staged. You can deploy them in the following ways:
Using the CLI
Using the Console
Using the API
Deploy staged changes to your chosen environment using the following command:
The output should look similar to the example below:
In the Console, a deploy button will be visible in the environment whenever changes are staged. Click this button to deploy your staged changes.
Trigger the deployment of staged changes with the following:
Zero Downtime Deployments
What is Zero Downtime?
By default, deployments use a stop-start deployment strategy (services stop, then restart with updates). Zero Downtime Deployments use a rolling deployment strategy, enabling you to deploy changes to your environment without taking your app offline and without interrupting live traffic.
How Zero Downtime works
Instead of stopping services before updating, a temporary copy of your application is created and prepared behind the scenes during the deployment process. Your services work with both the original application and the temporary copy during the whole deployment process, which means that any changes you make to your services during deployment will be applied to the original application. Here’s the step-by-step process:
1
2
3
Deployment strategies
Stop-start (default)
- Services stop first then restart with the new version
- Deployment is fast but may cause temporary downtime or freezing depending on the application
Rolling (ZDD)
- Creates a temporary copy of your services
- Routes traffic to the temporary copy while updating the original services
- Removes the temporary copy once the deployment is complete
- No downtime for users
- Deployment may take longer and use slightly more resources temporarily
Stop-start vs Rolling (ZDD)
| Feature | Stop-start (default) | Rolling (ZDD) |
|---|---|---|
| User impact | Services may be unavailable briefly | Users experience no downtime |
| Deployment speed | Fast | Slightly longer |
| Resource usage | Standard | Higher temporarily (due to parallel services) |
| Process | Stop services → deploy updates → start services | Deploy temporary services → switch traffic → update original services → remove temporary services |
| Best for | Small apps, quick updates | Apps requiring uninterrupted availability |
| Limitations | Causes downtime/freezetime | Longer deploy time, higher temporary resource use |
Use cases
| Use Case | Recommendation |
|---|---|
| Code pushes | Suitable |
| Config or environment variable changes | Suitable |
| Stateful service updates (databases, caches) | Not suitable |
| Database schema migrations | Not suitable (unless updates are both backward and forward compatible) |
How to use Zero Downtime Deployments
Before running zero-downtime deployments, it is recommended that you enable manual deployment.
Using the CLI
Using the Console
Using the API
On code push
With Manual Deployments
In the Console, navigate to the environment settings and trigger a deployment from the deployment modal. Select Zero Downtime as a deployment strategy.
Connection handling
During any deployment, long-lived connections like WebSockets or Server-Sent Events (SSE) are dropped. With ZDD, you can plan for smooth reconnection:
- SSE supports automatic retry logic.
- WebSocket clients should implement reconnect logic.
Zero Downtime Troubleshooting
This section covers two common scenarios and how to resolve them.
Application is slow to start
If your application takes longer to become responsive, traffic might be switched back to your original application before it’s fully ready. This can cause temporary errors immediately after deployment.
Deployment fails midway
If deployment fails partway through, one of the applications (either the original or the clone) may remain active in the background while the other continues to serve traffic. This can lead to an increase in resource usage and costs. To troubleshoot a failure, try one or both of the following:
- Enable manual deployments if not already enabled; then, try to manually redeploy the application.
- Deploy the environment using the stop-start strategy to ensure no clones remain active.
If you still experience issues, contact support.
Deployment philosophy
Upsun values consistency over availability, acknowledging that it’s nearly impossible to have both. During a deployment, the deploy hook may make database changes that are incompatible with the previous code version. Having both old and new code running in parallel on different servers could therefore result in data loss. Upsun believes that a minute of planned downtime for authenticated users is preferable to a risk of race conditions resulting in data corruption, especially with a CDN continuing to serve anonymous traffic uninterrupted. This brief downtime affects only the environment being updated. Deployments to a staging or development branch have no impact on the production environment and cause no downtime.
What’s next
- See how to configure your app for the entire process.
- Learn more about using build and deploy hooks.