How to migrate a web app from a VPS to xhostd
Move a web app from a VPS to xhostd: what moves, what xhostd takes over, and how to switch with a preview test and the old server kept as a fallback.
To move a web app from a VPS to xhostd, copy the app and its data to xhostd, test it, and then point your domain at it. The old server keeps serving visitors until that last step, so your site stays up during the move.
If you haven't decided whether to move, read VPS vs. managed hosting: xhostd compared first.
Who this guide is for
You have an app on a server that you rent, and you want to stop maintaining the server. For example:
- an online shop with orders in Postgres and product photos in a folder
- a Node.js or Python app that an AI coding agent built and that you deployed by hand
What gets moved
- Your code, with small changes that your agent makes.
- Your database. Postgres is Postgres, so a copy loads into xhostd.
- Your uploaded files, such as product photos.
- Your secrets and settings, such as API keys.
- Your domain, once the new copy works.
What xhostd takes over
After the move, you no longer run a server. xhostd keeps the app running, serves it over HTTPS, backs up the database, deploys each new version when you ask, and stores your files.
How the migration works
- Deploy the app. Deploying the code first proves that the app builds and starts.
- Copy the data. Copy the database, the uploaded files, and the settings from the old server.
- Test it safely in a preview channel. A channel is one running copy of your app, with its own address and database. A preview channel lets you rehearse the whole move without touching production.
- Point the domain. Pause writes on the old server for a short time, copy the latest data, and switch your domain to xhostd.
- Keep the old server as a fallback. Keep it for at least a week, and point the domain back to it if something goes wrong. Shut it down only after xhostd has a nightly snapshot and you have your own database copy.
What your agent does
Your agent, such as Claude Code, Cursor, or Codex, can do most of the move: the deploy, the data, the secrets, and the domain setup. You review its work, test the app in the preview channel, and make the DNS change at your domain registrar.
Before you start
Most apps need only small code changes, which your agent makes. Unusual requirements might need extra work: an uncommon database extension (xhostd supports PostGIS), a special network setup, or a dependency on the server itself.
Next step
When you're ready, connect your agent and give it the xhostd recipes, which cover each kind of app, its database, and its files. The custom domains guide lists the DNS records for the switch.
Technical notes
- Inventory. Before you change anything, record the language, the start command, and the port; every environment setting; the Postgres version and extensions; where uploads live; every scheduled job and background process; and the domain's DNS records.
- Scheduled jobs. xhostd has no separate scheduler. Move each scheduled job into a background worker that waits between runs.
- Database copy. Dump with
pg_dump --format=custom --file=app.dump "$OLD_DATABASE_URL", and restore withpg_restore --no-acl --no-owner -d "<connection URL>" app.dump. The two flags skip commands that name roles your channel doesn't have. Compare the row counts of the largest tables on both servers afterward. - Connection URL. In the console, open the project's Data & recovery section, find the External database access card on the Database tab, select Enable external access, and copy the URL. An agent can open external access only while agent access is on. The project owner turns agent access on in the console, on the project's Access page, or on the Account & billing page for every project that follows the account default.
- Server verification. If your database client supports it, change
sslmode=requirein the URL tosslmode=verify-full sslrootcert=system, so that the client also verifies the server. - Practice restore. For a large database, do a practice restore first. It shows roughly how long writes pause on moving day.
- Cutover order. A day ahead, lower the time to live (TTL) on your DNS
records, so that the switch takes effect sooner. Attach the domain to the
prodchannel and verify it. Then pause writes on the old server, run a final dump and restore, and switch DNS to xhostd.