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 uses an atomic deployment 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
How atomic deployments work
When you run your first atomic deployment, DeployHQ 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:
- DeployHQ copies the previous release to a new timestamped directory
- Changed files are uploaded to the new directory
- Shared files are symlinked into the new release
- Once everything is ready, the
currentsymlink 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 project and enable the Perform zero-downtime deployments on this server option:
DeployHQ server configuration' />
After adding the server, run a full deployment so DeployHQ 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.
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 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 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 or installing PHP dependencies with Composer — the build pipeline runs before the deployment begins. DeployHQ 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.
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 can't create the symlink because the file already exists.
Running out of disk space
DeployHQ 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 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 retains the current release plus 2 previous ones, cleaning up older releases automatically
- Your web server must serve from the
currentsymlink for the zero downtime mechanism to work - Managing multiple environments (dev, staging, production) works seamlessly with atomic deployments
Ready to eliminate deployment downtime? Sign up for DeployHQ and set up zero downtime deployments in minutes.
If you have questions about atomic deployments or any other aspect of DeployHQ, contact us at support@deployhq.com or reach out on X (Twitter).