Deployment without drama: the staged file-swap strategy
Slow internet, no CI/CD pipeline, and a live production server that can't afford interruptions. This is how a constraint turned into a deliberate deployment strategy — and why thinking through the data risk before writing a single script made the difference.
Slow internet, no CI/CD pipeline, and a live production server that can't afford interruptions. This is how a constraint turned into a deliberate deployment strategy — and why thinking through the data risk before writing a single script made the difference.
The problem with direct uploads
The server runs a .NET application published as a folder of files. Deployments meant uploading the new publish output directly over the existing folder — file by file, over a slow connection. The issues stacked up quickly.
Even with tools set to upload only changed files, a slow network meant the process took time. During that window, the server was in an inconsistent state: some files updated, some not. Any request hitting a code path that crossed the boundary between old and new could behave unpredictably.
The instinct was to upload everything to a separate location first, then swap — so the transition is instant rather than stretched over minutes. But that idea immediately ran into a real constraint.
The constraint: customer files live inside the app folder
The application stores vendor-uploaded files — product images, documents — inside the same folder structure as the application itself, under wwwroot. If we swapped the entire folder, we'd wipe every file vendors had ever uploaded.
A naive swap wasn't safe. So before building the deployment flow, we fixed the underlying structure.
The right fix wasn't to work around the problem — it was to eliminate it. Customer files shouldn't live inside the application directory at all.
Step 0: moving customer files outside the app
We refactored the file handling code to store and serve vendor uploads from a directory outside wwwroot — outside the application folder entirely. This involved updating every path reference in the codebase, configuring the .NET app to serve static files from an external path, and testing the change thoroughly before deploying it.
// Before — files inside wwwroot
builder.Services.AddStaticFiles(); // served from wwwroot by default
// After — external uploads directory
app.UseStaticFiles(new StaticFileOptions {
FileProvider = new PhysicalFileProvider(
Path.Combine(builder.Environment.ContentRootPath, "..", "uploads")
),
RequestPath = "/uploads"
});
Once deployed and verified, customer files were permanently decoupled from application deployments. Now a full folder swap was safe.
The deployment flow
With the file separation in place, the staged swap sequence on every deployment:
1. Upload to a temp directory
Upload the full publish output to /app-new on the server. The live application keeps running from /app — no interruption during the upload.
2. Rename the current folder as a backup
Rename /app → /app-old. This is instant — no data moved, just a name change. The server is still running from the same files on disk.
3. Rename the new folder into place
Rename /app-new → /app. Again, instant. Kestrel is still serving from the same open file handles — it doesn't notice the directory rename.
4. Restart the .NET service Only now does Kestrel pick up the new code. The restart is the only moment of actual downtime — typically a few seconds.
5. Keep /app-old until verified
If something goes wrong, rename back. Rollback takes seconds. Delete /app-old only after confirming the new release is stable.
What this solved — and what it didn't
✓ Upload time no longer causes inconsistency — the live app is untouched until the rename
✓ Rollback is instant — rename back to the old folder and restart
✓ Customer files are safe — completely decoupled from the application directory
⚠ Database migrations that affect live pages still cause a brief inconsistency window between schema change and service restart
⚠ Migrations tested on staging with dummy data don't always cover every production data edge case — a known tradeoff we manage by keeping the old folder until fully verified
Note: This strategy eliminates deployment downtime for pure code releases. For releases with database migrations, brief downtime is still possible — and honestly acknowledged rather than papered over.
Key takeaways
Fix the data risk before building the automation. The urge to script the swap came first — but the right first step was moving customer files out of the app directory. Automating an unsafe pattern just makes failures faster.
Rename operations are atomic and instant. On Linux, renaming a directory is a single syscall. There's no window where the path doesn't exist. That's what makes this safe as a swap mechanism.
Keep the old folder until you're sure. Disk space is cheap. The ability to rename back in 10 seconds if something breaks is worth keeping /app-old around for a few hours.
Know what your strategy doesn't cover. This approach handles file-level deployments cleanly. It doesn't solve database migration consistency. Being clear about that boundary is more useful than pretending the problem doesn't exist.