Deploy Qwik City with the Express adapter to a VPS

To deploy Qwik City to a VPS with ox, add the repo as a project and deploy it, with no Dockerfile and no ox.toml. ox reads adapters/express/vite.config.ts and package.json, runs npm install and npm run build, then starts npm run serve under systemd behind Caddy with HTTPS. Run ox check in your repo to see the same plan before the first deploy.

Plan verified, real-server test pending. The plan below is what ox check prints for a minimal Qwik City repo in ox's tests. A deploy on a real server is not recorded yet.

What ox detects in a Qwik City repo

This is the plan ox check prints for a minimal a Qwik City app with the Express adapter, with no ox.toml. Each row says where its value came from: a file in the repo, or ox's default.

The ox.toml for Qwik City

None is needed: the plan above comes from the repo alone. Write one to serve your own domain or to change what ox detected. This one passes ox check against the same repo: [app] keeps the detected start command and build.

domains = ["www.example.com"]

[app]

Check and deploy Qwik City

Add the repo as a project, then check and ship it from a terminal:

ox check                                # in the repo: the plan above, offline
ox new <owner/repo> --server <server>  # add the repo as a project
ox deploy <project> --wait              # stream the deploy, exit with its result
ox logs <project> --follow             # the app's own logs

Variables to set for Qwik City

None before the first deploy: ox check asks for no variable. Add your own on the dashboard's Variables tab or with ox vars set <project> KEY.

ox provides these to the app itself: PORT, HOST, OX_ENV, OX_PROJECT, OX_RELEASE, OX_DATA_DIR, PUBLIC_URL and PUBLIC_HOST.

If the Qwik City deploy fails

• Qwik City found, but no single Node adapter with its serve script (Qwik's start script runs the dev server); run npm run qwik add express, whose serve script ox then runs, or set [app] start: Add the Express adapter with npm run qwik add express, or set [app] start. More.
• build 1/1: npm run build: exit status 1: Your build failed. The lines above it are the build's own output; run the same command on your computer, fix it, and push. More.
• TCP connect to 127.0.0.1:8001 did not answer within 120s: dial tcp 127.0.0.1:8001: connect: connection refused: The app started but never answered on the port ox gave it. Listen on 127.0.0.1 at $PORT; the lines above the message are the app's own output. More.

Your visitors never see a failed deploy: the previous release keeps serving until the new one passes its health check.

Next steps

• The Node.js guide: start scripts, migrations, PostgreSQL and Redis.
• The [app] keys: start, health check, memory and the rest.
• Add a custom domain with one A record; Caddy gets the HTTPS certificate.
• Read the logs live, search them, or download them.
• Set variables and secrets on the dashboard or with ox vars.

Qwik City FAQ

Do I need a Dockerfile or an ox.toml to deploy Qwik City to a VPS?

No. ox does not use Docker, and ox check on a Qwik City repo with no ox.toml prints Ready to deploy. Write an ox.toml only to change what ox detected.

What does ox install on the server for Qwik City?

Only what the plan names: node 24 (ox's default). Your app's own dependencies are installed by the build into the release folder, not system-wide.

Why not npm start?

Qwik's own start script runs the Vite development server. ox runs the Express adapter's serve script instead, which serves the built app.

Related guides

• NestJSDeploy a NestJS API to your own VPS: ox installs from package-lock.json, runs nest build and start:prod under systemd, and sets up PostgreSQL for the app.
• FastifyDeploy a Fastify API to your own VPS: ox finds server.js, runs node server.js under systemd behind Caddy, and adds PostgreSQL with DATABASE_URL set.

Every stack ox deploys, and the ones it does not yet, is on the Stacks page.