> ## Documentation Index
> Fetch the complete documentation index at: https://developer.upsun.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Build and deploy
> See how applications get built and deployed with Upsun Cloud.
export const SettingsIcon = () => ;
export const ChevronIcon = () => ;
Each time you push a change to your app through Git or activate an [environment](/docs/environments),
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
The configuration is checked by validating the `.upsun/` directory and scanning the repository for any app configuration to validate.
Any container images that have been built before and that don't have any changes are pulled to be reused.
If you have specified additional global dependencies, they're downloaded during this step.
This is useful for commands you may need in the build hook.
For some languages (NodeJS, PHP), a series of standard commands are run based on the build flavor.
You can change the flavor or skip the commands by specifying it in your `.upsun/config.yaml` file.
The `build` hook comprises one or more shell commands that you write to finish creating your production code base: for example, compiling Sass files, running a bundler, rearranging files on disk, or compiling.
The committed build hook runs in the build container.
During this time, commands have write access to the file system, but there aren't connections to other containers (services and other apps).
For automated builds, you can use the [`CI` environment variable](/docs/development/variables/use-variables#use-provided-variables) in build scripts and tooling to modify build behavior (for example, to disable attempts to connect to other containers during the build phase, or to disable interactivity). These modifications can help to prevent build failures.
You can also manually [cancel deployments stuck on the build hook](/docs/environments/cancel-activity).
The file system is frozen and produces a read-only container image, which is the final build artifact.
## 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
Incoming [idempotent requests](https://www.iana.org/assignments/http-methods/http-methods.xhtml) (like `GET`, `PUT`, `DELETE` but **not** `POST`, `PATCH` etc.) are held.
Any previous containers are disconnected from their file system mounts.
The file system is connected to the new containers.
New branches have file systems cloned from their parent.
Networking connections are opened between any containers specified in your app and services configurations.
The [commands](/docs/configure-apps/image-properties/web#web-commands) necessary to start your app are run.
Often this stage will only include a start command, which is restarted if ever terminated going forward.
You may also, however, define a `pre_start` command, when you need to run *per-instance* actions.
In this case, as you might expect, the `pre_start` command is run, then the `start` command.
The `deploy` hook is any number of shell commands you can run to finish your deployment.
This can include clearing caches, running database migrations, and setting configuration that requires relationship information.
Incoming requests to your newly deployed application are allowed.
After the deploy process is over, any commands in your `post_deploy` hook are run.
## Deployment types
Upsun Cloud 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](#change-deployment-type), 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` |
To restart your application without applying staged changes, run `upsun redeploy` or click **Redeploy** in the Console.
### Change deployment type
You can adjust deployment behavior in your environment.
Use the following command in the CLI to view or change the deployment type:
```bash theme={null}
upsun environment:deploy:type
```
The output should look similar to the example below:
```bash theme={null}
Selected project: [my-project (ID)]
Selected environment: main (type: production)
Deployment type: manual
```
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:
Deploy staged changes to your chosen environment using the following command:
```bash theme={null}
upsun environment:deploy
```
The output should look similar to the example below:
```bash theme={null}
Deploying staged changes:
+---------------+---------------------------+-----------------------------------------------------------+---------+
| ID | Created | Description | Result |
+---------------+---------------------------+-----------------------------------------------------------+---------+
| 5uh3xwmkh5boq | 2026-01-01T14:01:10+00:00 | Patrick pushed to main | failure |
| fno2qiodq7e3c | 2026-01-01T13:06:18+00:00 | Arseni updated resource allocation on main | success |
| xzvcazrtoafeu | 2026-01-01T13:01:10+00:00 | Pilar added variable HELLO_WORLD to main | success |
| fq73u53ruwloq | 2026-01-01T12:06:17+00:00 | Pilar pushed to main | success |
+---------------+---------------------------+-----------------------------------------------------------+---------+
```
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:
```bash theme={null}
POST /projects/{projectId}/environments/{environmentId}/deploy
```
As soon as your deployment type is switched from manual to automatic, all currently staged changes are deployed immediately and the environment resumes its default automatic deployment behavior.
## Maintenance window
A maintenance window is a recurring time slot when Upsun Cloud applies patch updates to your services' container images, such as bug and security fixes, keeping them up to date on a predictable schedule.
Some of these updates can cause brief downtime. Instead of Upsun Cloud running them at any time, you choose when they happen (for example, at a time that works best for your application and users). You set how often the window repeats (every 2 or 4 weeks), the day, and the time.
You configure one maintenance window per project. Upsun Cloud may still apply urgent or critical fixes outside of the project's maintenance window.
### Maintenance windows and zero-downtime deployments
[Zero-downtime deployments](#zero-downtime-deployments) use a rolling strategy, which keeps your app running on a temporary copy while the original updates. Some platform updates can't be applied that way, such as a restart of a database service onto a new version. A maintenance window gives those updates a scheduled time to run, so your regular deployments can stay zero-downtime.
Without a maintenance window, rolling deployments aren't available: requesting one is rejected until a project admin sets a maintenance window. Deployments that don't request the rolling strategy are unaffected and continue to use the default stop-start strategy.
Rolling deployments also [aren't available for projects that use Varnish](#zero-downtime-deployments), regardless of whether a maintenance window is set.
Maintenance windows run only against active environments; [paused or inactive environments](/docs/environments/deactivate-environment) are skipped, even if the project has a maintenance window configured.
### What happens during a maintenance window
During your scheduled maintenance window, Upsun Cloud redeploys your environment to apply any pending patch updates to your services' container images, which can cause brief downtime.
Maintenance redeployments and your regular deployments stay separate: a maintenance redeployment skips your own staged or pending activities, and a regular deployment doesn't apply pending patch updates. A code push won't unexpectedly restart a service onto a new version, except for urgent or critical fixes, which Upsun Cloud may still apply outside of the maintenance window.
After the redeployment on your production environment succeeds, Upsun Cloud schedules the same redeployment on your non-production environments, staggered roughly 15 minutes apart so they don't all redeploy at once.
If no updates are pending, nothing runs.
### Configure a maintenance window
A project's maintenance window is not enabled by default.
Once enabled, a maintenance window can't be turned off from the Console or CLI. [Contact support](/docs/core-concepts/get-support) to turn one off.
To configure one:
1. In the [Console](https://console.upsun.com), open your project and click ****.
2. Click **Project Settings ** and then click **Maintenance window**.
3. Choose the recurrence (2 or 4 weeks), weekday, and time (in your project's [timezone](/docs/projects/change-project-timezone)). Click **Save**.
Based on your recurrence settings, Upsun Cloud calculates the next maintenance date. The Console displays the next scheduled event, and the run itself appears as pending in the [activity log](/docs/observability/logs/access-logs#activity-logs) about 5 days ahead of time.
You can change the recurrence at any time. The new schedule applies from the next maintenance cycle, so a run that's already scheduled keeps its date.
### Reschedule a maintenance window
You can postpone a scheduled maintenance event multiple times within a seven-day window. The new date must fall within the allowable range shown in the Console.
### Turn off a maintenance window
A maintenance window can't be turned off from the Console or CLI. [Contact support](/docs/core-concepts/get-support) to turn one off.
## Zero Downtime Deployments
Zero Downtime Deployments are not supported for projects that use [Varnish](/docs/add-services/varnish). Use the stop-start [deployment strategy](#deployment-strategies) instead if your project uses Varnish.
## What is Zero Downtime?
By default, deployments use a stop-start [deployment strategy](#deployment-strategies) (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.
Before using zero-downtime deployments, you must configure a [maintenance window](#maintenance-window). A rolling deployment updates your application, but some service updates, like restarting a database service onto a new version, can't happen during one, since your backing services must keep running the whole time to serve both the original app and its clone. A maintenance window gives Upsun Cloud a separate, scheduled time to apply those service updates instead.
## 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:
* Upsun Cloud starts a temporary container that runs a cloned version of your app.
* The clone handles all live traffic during this time.
* Services (for example, Redis) serve both the original app *and* the clone.
* The original app is updated with the new code and configuration.
* The deploy hook is run on the original app.
* When deployment of the original app is complete, the clone (the temporary container) is shut down and removed.
* All traffic and services are now applied to the original app only.
During a zero-downtime deployment, the original app and its clone run simultaneously short period (a few seconds to a couple of minutes).
**You are billed for extra resources while both app versions active.** If your app’s deployment phase takes longer and uses more resources, expect proportionally higher costs.
### 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 you can run zero-downtime deployments, a project admin needs to [set a maintenance window](#maintenance-window) for the project. We also recommend enabling [manual deployment](#manual-deployment) so you control when each deployment runs.
If you're not a project admin, ask one to set the maintenance window. In the Console, the deployment modal shows when a window hasn't been set yet.
**On code push**
```bash theme={null}
upsun push --deploy-strategy rolling
```
**With Manual Deployments**
```bash theme={null}
upsun environment:deploy --strategy rolling
```
In the Console, navigate to the environment settings and trigger a deployment from the deployment modal. Select Zero Downtime as a deployment strategy.
If the project doesn't have a maintenance window yet, you're asked to set one before you can select Zero Downtime.
```
POST /projects/{projectId}/environments/{environmentId}/deploy
{
"strategy": "rolling"
}
```
## 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](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#retry).
* WebSocket clients should implement reconnect logic.
## Zero Downtime Troubleshooting
This section covers two common scenarios and how to resolve them.
Rolling deployments require a maintenance window. If you get an error saying a maintenance window is required, [set one](#maintenance-window) in **Project settings → Maintenance window**, then deploy again.
### Application is slow to start
If your application takes longer to become responsive, traffic might be [switched back to your original application](#how-zero-downtime-works) before it’s fully ready. This can cause temporary errors immediately after deployment.
**Use a post\_start command**
You can use the `post_start` command to ensure your app is fully active before traffic is routed to it. This command can perform checks or wait until your application starts listening on the expected port.
For example, if your framework needs several seconds to initialize (e.g. building caches or database connections), `post_start` can help coordinate the handover so the app receives traffic only when it's ready.
This `post_start` command waits for your application to respond before serving traffic:
```yaml .upsun/config.yaml theme={null}
applications:
:
web:
commands:
post_start: |
date
curl -sS --retry 20 --retry-delay 1 --retry-connrefused localhost -o /dev/null
```
For more information about the `post_start` command, visit [web commands](/docs/configure-apps/image-properties/web#post_start-command).
### 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](#change-deployment-type) 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 the most recent deployment failed, you can only use the default stop-start strategy.
If you still experience issues, [contact support](/docs/core-concepts/get-support).
## Deployment philosophy
Upsun Cloud values consistency over availability, acknowledging that it's nearly impossible to have both.
During a deployment, the [deploy hook](/docs/configure-apps/hooks/hooks-comparison#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](/docs/configure-apps) for the entire process.
* Learn more about [using build and deploy hooks](/docs/configure-apps/hooks).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.
Based on your recurrence settings, Upsun Cloud calculates the next maintenance date. The Console displays the next scheduled event, and the run itself appears as pending in the [activity log](/docs/observability/logs/access-logs#activity-logs) about 5 days ahead of time.
You can change the recurrence at any time. The new schedule applies from the next maintenance cycle, so a run that's already scheduled keeps its date.
### Reschedule a maintenance window
You can postpone a scheduled maintenance event multiple times within a seven-day window. The new date must fall within the allowable range shown in the Console.
### Turn off a maintenance window
A maintenance window can't be turned off from the Console or CLI. [Contact support](/docs/core-concepts/get-support) to turn one off.
## Zero Downtime Deployments