Every deployment carries risk. If a visitor hits your site while files are being overwritten, they could see broken pages, missing assets, or outright errors. For teams deploying multiple times a day, this isn't just an inconvenience — it's a reliability problem that erodes user trust. Zero downtime deployments eliminate this risk entirely. Instead of overwriting files in place, [DeployHQ](https://www.deployhq.com) uses an [atomic deployment](https://www.deployhq.com/blog/migrate-deployhq-project-to-use-atomic-deployments) strategy that switches your live site to a new release only after all files have been transferred successfully. ## Why zero downtime matters Traditional deployments upload changed files directly to your live directory. During the transfer window — which could last seconds or minutes depending on the number of changes — your application is in an inconsistent state. Some files are new, others are old, and any request that touches both can fail unpredictably. With atomic deployments, your site continues serving the previous release while the new one is being prepared in a separate directory. The switch happens instantly via a symlink change, which is an atomic operation at the filesystem level. If the deployment fails at any point, your live site is completely unaffected. This matters most when you're: - Deploying to production during business hours - Running an e-commerce site where every failed page load costs revenue - Operating services with SLAs that require high availability - Deploying frequently as part of a [CI/CD pipeline](https://www.deployhq.com/blog/ci-cd-pipelines-complete-guide) ## How atomic deployments work When you run your first atomic deployment, [DeployHQ](https://www.deployhq.com) creates three items within your deployment path: ``` your-deployment-path/ ├── releases/ # Each deployment gets its own timestamped directory │ ├── 20260325120000/ │ └── 20260325140000/ ├── shared/ # Files that persist across all releases │ ├── config/ │ └── uploads/ └── current -> releases/20260325140000 # Symlink to the active release ``` ``` sequenceDiagram participant D as DeployHQ participant S as Server participant U as Users Note over U,S: Users see Release A (current → releases/20260325120000) D->>S: Copy Release A to new directory (releases/20260325140000) D->>S: Upload changed files to new release Note over U,S: Users still see Release A D->>S: Switch symlink: current → releases/20260325140000 Note over U,S: Users now see Release B (instant switch) ``` Each deployment follows this process: 1. [DeployHQ](https://www.deployhq.com) copies the previous release to a new timestamped directory 2. Changed files are uploaded to the new directory 3. Shared files are symlinked into the new release 4. Once everything is ready, the `current` symlink switches to the new release Your web server should be configured to serve files from the `current` symlink. Because the symlink switch is atomic, there's no window where users could see a partially updated site. ## Setting up an atomic deployment ### Prerequisites Atomic deployments require an SSH/SFTP server with POSIX support for copying and symlinking. Most Linux servers meet this requirement out of the box. To verify your server supports the necessary operations, connect via SSH and run: ``` cp --help ln --help ``` If both commands output help documentation, you're ready to proceed. ### Adding an atomic server in DeployHQ Configure a new SSH/SFTP server in your [DeployHQ](https://www.deployhq.com) project and enable the **Perform zero-downtime deployments on this server** option: ![Zero downtime deployment option enabled in After adding the server, run a full deployment so [DeployHQ](https://www.deployhq.com) can create the directory structure and upload a complete copy of your site. All subsequent deployments will create a new release directory containing only the changed files, then switch the symlink once the transfer is complete. ### Configuring your web server Point your web server's document root to the `current` symlink within your deployment path. For example, in Nginx: ``` server { root /var/www/your-app/current/public; # ... rest of your configuration } ``` For Apache: ``` DocumentRoot /var/www/your-app/current/public ``` No web server restart is needed between deployments — the symlink switch is handled entirely by [DeployHQ](https://www.deployhq.com). ## Using the shared directory The `shared` directory stores files that need to persist across releases but aren't kept in your repository. Common examples include: - **Configuration files** : Database credentials, API keys, environment-specific settings - **User uploads** : Images, documents, and other media uploaded through your application - **Log files** : Application logs you want to preserve between deployments - **Cache directories** : Persistent caches that shouldn't be cleared on each deploy During each deployment, [DeployHQ](https://www.deployhq.com) automatically creates symlinks from the shared directory into the new release. The directory structure matches exactly: ``` # File in shared: /var/www/your-app/shared/config/database.yml # Automatically symlinked to the latest release: /var/www/your-app/releases/20260325140000/config/database.yml ``` Make sure files in `shared` don't also exist in your repository. If a conflict is found, [DeployHQ](https://www.deployhq.com) traverses deeper into the directory structure until it finds files that aren't in the repository. ## Combining with build pipelines If your project requires a build step — such as compiling assets with [Node.js and NPM](https://www.deployhq.com/blog/using-nodejs-and-npm-with-deployhq-build) or installing PHP dependencies with Composer — the [build pipeline](https://www.deployhq.com/blog/the-deployhq-build-pipeline) runs before the deployment begins. [DeployHQ](https://www.deployhq.com) compiles your assets in an isolated environment, then deploys the built output to the new release directory. This means your live site stays on the previous release while both the build and the file transfer complete. The switch only happens once everything is ready. ## Troubleshooting ### Deployment succeeds but site shows old content Check that your web server's document root points to the `current` symlink, not directly to a release directory. If you're using a caching layer (like Varnish or a CDN), you may need to purge the cache after deployment using an [SSH command](https://www.deployhq.com/support/ssh-commands). ### Permission errors during symlink switch Ensure the deployment user has write permissions to the deployment path directory. The user needs to be able to create directories, copy files, and create symlinks within that path. ### Shared files not appearing in new releases Verify the shared files exist in the `shared` directory on your server and that the same paths don't exist in your repository. If they do, [DeployHQ](https://www.deployhq.com) can't create the symlink because the file already exists. ### Running out of disk space [DeployHQ](https://www.deployhq.com) keeps 3 releases on your server by default (the current release and 2 previous ones) and automatically cleans up older releases. If your project is large, ensure your server has sufficient disk space for at least 3 full copies of your codebase. ## Rolling back a deployment One significant advantage of atomic deployments is the ability to roll back instantly. Since previous releases remain on the server, you can use DeployHQ's [rollback feature](https://www.deployhq.com/blog/seamless-recovery-how-deployhq-empowers-you-to-rollback-deployments) to switch back to a previous release. The rollback is just as fast as a deployment — it's another symlink switch. ## Key points to remember - Atomic deployments are supported on SSH/SFTP servers only - The deployment path must be empty when first setting up atomic deployments - [DeployHQ](https://www.deployhq.com) retains the current release plus 2 previous ones, cleaning up older releases automatically - Your web server must serve from the `current` symlink for the zero downtime mechanism to work - [Managing multiple environments](https://www.deployhq.com/blog/managing-multiple-environments-with-deployhq-dev-staging-and-production) (dev, staging, production) works seamlessly with atomic deployments * * * Ready to eliminate deployment downtime? [Sign up for DeployHQ](https://www.deployhq.com/signup) and set up zero downtime deployments in minutes. If you have questions about atomic deployments or any other aspect of [DeployHQ](https://www.deployhq.com), contact us at [support@deployhq.com](mailto:support@deployhq.com) or reach out on [X (Twitter)](https://x.com/deployhq).