--- title: "Deploy a Node.js app" description: "Deploy a Node.js or Express app to an exe.dev VM: git push to deploy, Node.js 26 LTS under systemd, SQLite on a persistent disk, HTTPS, backups." url: https://exe-staging.dev/deploy/nodejs category: "Frameworks" updated: 2026-10-31 --- # Deploy a Node.js app Your Express app on a server of its own. git push to deploy. - **Software:** Node.js (https://nodejs.org) - **Source:** https://github.com/nodejs/node - **License:** MIT - **Time:** 10 minutes - **Example VM name:** `my-nodejs` (yours will differ; on the VM, `hostname` prints it) - **Machine-readable:** https://exe-staging.dev/deploy/nodejs/manifest.json ## What you get - Node.js 26 and the app answering on port 8000 as app.service, enabled to come back after a reboot. - A ~/app.git repository whose pre-receive hook deploys each push to main into a new release and rejects the push if the deploy fails. - Settings and secrets in ~/app.env (mode 600), read by the deploy and by the server. - Data in ~/data, backed up nightly by app-backup.timer, with the newest backup opened and checked in a scratch directory. - With REPO=new, a fresh Express 5 app whose guestbook saves messages to SQLite. Running on the VM: - **Your Node.js app**: npm start, as app.service under systemd, port 8000, data in `~/app → the current release in ~/releases` - **Node.js 26 LTS**: NodeSource's apt package; npm, plus pnpm and Yarn through Corepack - **git push deploys**: A pre-receive hook in ~/app.git installs, builds, migrates, and switches - **SQLite**: Node's built-in node:sqlite in new apps; settings in ~/app.env, data in `~/data` - **Nightly backup**: app-backup.timer; data, settings, and the repository, data in `~/backups` How it is reached: - https://my-nodejs.exe.xyz/ (private): Your app, until you make it public - my-nodejs.exe.xyz:app.git (private): `git push exe main` deploys ## Deploy with Shelley Open https://exe-staging.dev/new?prompt=REPO%3D%3Cfill-this-in%3E%0A%0ASet%20up%20Node.js%20on%20this%20VM%20by%20following%20the%20exe.dev%20recipe%20at%20https%3A%2F%2Fexe-staging.dev%2Fdeploy%2Fnodejs.md%20from%20top%20to%20bottom.%0A%0AThe%20values%20at%20the%20top%20of%20this%20message%20are%20mine%3A%0A-%20REPO%3A%20the%20GitHub%20repository%20to%20deploy%2C%20as%20owner%2Fname%20or%20a%20URL%2C%20or%20%60new%60%20to%20start%20a%20fresh%20Express%20app%0AAsk%20me%20for%20any%20that%20still%20say%20%3Cfill-this-in%3E%20before%20you%20need%20them.%0A%0AThe%20recipe%27s%20example%20VM%20name%20is%20my-nodejs.%20This%20VM%27s%20name%20is%20the%20output%20of%20%60hostname%60%3A%20use%20it%20wherever%20the%20recipe%20writes%20my-nodejs.%20Skip%20the%20step%20that%20creates%20the%20VM%3B%20you%20are%20on%20it.%0A%0AYou%20are%20done%20when%20all%20of%20these%20are%20true.%20Check%20each%20one%20yourself%3A%0A-%20Node.js%2026%20and%20the%20app%20answering%20on%20port%208000%20as%20app.service%2C%20enabled%20to%20come%20back%20after%20a%20reboot.%0A-%20A%20~%2Fapp.git%20repository%20whose%20pre-receive%20hook%20deploys%20each%20push%20to%20main%20into%20a%20new%20release%20and%20rejects%20the%20push%20if%20the%20deploy%20fails.%0A-%20Settings%20and%20secrets%20in%20~%2Fapp.env%20%28mode%20600%29%2C%20read%20by%20the%20deploy%20and%20by%20the%20server.%0A-%20Data%20in%20~%2Fdata%2C%20backed%20up%20nightly%20by%20app-backup.timer%2C%20with%20the%20newest%20backup%20opened%20and%20checked%20in%20a%20scratch%20directory.%0A-%20With%20REPO%3Dnew%2C%20a%20fresh%20Express%205%20app%20whose%20guestbook%20saves%20messages%20to%20SQLite.%0A%0ARead%20the%20whole%20recipe%2C%20including%20the%20closed%20details.%20Follow%20%22Set%20up%20by%0Ahand%22%20from%20%22Install%20Node.js%22%20to%20the%20end%20of%20it%2C%20as%20exedev%3B%20the%20walkthrough%0Aabove%20it%20is%20for%20the%20owner%20afterwards.%20Do%20not%20run%20Restore%20or%20Update%2C%20and%0Ado%20not%20reboot.%20Leave%20public%20sharing%20off.%0AREPO%20picks%20one%20path%20in%20%22Get%20the%20code%22%3A%20%60new%60%20starts%20a%20fresh%20app%3B%0Aanything%20else%20is%20a%20GitHub%20repository%20%28turn%20URLs%20into%20owner%2Fname%29.%20Never%0Acommit%20to%20a%20repository%20you%20cloned%3A%20its%20settings%20go%20in%20~%2Fapp.env.%20If%20a%0Aclone%20fails%2C%20follow%20the%20private-repository%20steps%2C%20and%20if%20that%20fails%0Atoo%2C%20give%20the%20owner%20the%20integration%20command%20and%20wait%20for%20them.%0AFor%20a%20cloned%20app%2C%20fill%20~%2Fapp.env%20from%20its%20.env.example%20%28or%20README%29%3A%0Agenerate%20secrets%20with%20openssl%2C%20ask%20the%20owner%20for%20keys%20to%20outside%0Aservices%2C%20and%20never%20invent%20values.%20If%20it%20uses%20Bun%20or%20doesn%27t%20start%20with%0A%60npm%20start%60%2C%20follow%20%22Hono%2C%20Fastify%2C%20and%20Bun%22.%20If%20a%20deploy%20fails%2C%20read%0Aits%20output%2C%20fix%20what%20you%20can%20without%20editing%20the%20code%2C%20and%20redeploy%0Awith%20~%2Fapp.git%2Fhooks%2Fpre-receive%20HEAD.%20The%20recipe%27s%20checks%20are%20enough%3A%0Adon%27t%20push%20test%20commits%20to%20~%2Fapp.git%2C%20which%20becomes%20the%20owner%27s%20history.%0AFinish%20with%20the%20app%27s%20URL%20and%20the%20git%20commands%20the%20owner%20runs%20on%20their%0Aown%20computer%2C%20from%20%22Deploy%20with%20git%20push%22%3A%20%60git%20clone%20-o%20exe%60%20for%20a%20new%0Aapp%2C%20%60git%20remote%20add%20exe%60%20for%20a%20GitHub%20repository%2C%20then%0A%60git%20push%20exe%20main%60%20%28or%20their%20default%20branch%29.%0A%0AFinish%20with%20the%20URLs%20I%20should%20open.%0A to create a VM whose agent, Shelley, follows this recipe. From a terminal: ```sh curl -fsSL https://exe-staging.dev/deploy/nodejs/prompt.txt | ssh exe.dev new --prompt=/dev/stdin ``` Or follow the steps below by hand. A Node.js app wants a server that stays up. On an exe.dev VM your app runs all the time under systemd: no cold starts, no sleeping free tier, WebSockets that stay open, and a SQLite database on a real disk that's still there tomorrow. You deploy with `git push`, as on Heroku; exe.dev adds HTTPS, and the app stays private until you share it. Shelley, the agent on the VM, can read your logs and fix things when you ask. This works for the Express, Fastify, Hono, or plain `node:http` app you already have on GitHub, or a fresh Express 5 app with a small guestbook. Bun apps work too, with [two changes](#hono-fastify-and-bun). ## Open your app When setup finishes, open `https://my-nodejs.exe.xyz/` and sign in to exe.dev if asked. A new app shows a guestbook; sign it. Your message goes into SQLite in `~/data/app.db`, signed with your exe.dev name, and it's still there after a redeploy or a reboot. ## Deploy with git push Your VM holds a git repository, `~/app.git`, and deploys whatever you push to its `main` branch, like `git push heroku main` used to. Set it up once **on your computer**. If Shelley started a new app, clone it from the VM: ```bash git clone -o exe my-nodejs.exe.xyz:app.git my-nodejs cd my-nodejs ``` If you brought a GitHub repository, add the VM as a second remote in your usual checkout. GitHub stays your source of truth; `exe` is where you deploy: ```bash git remote add exe my-nodejs.exe.xyz:app.git ``` Then change something, commit, and push: ```bash git push exe main ``` Use your default branch's name if it isn't `main`. The deploy streams back into your terminal and ends with `==> Deployed abc1234: HTTP 200 on port 8000`. If `ssh` can't find the VM that way, use `vm+my-nodejs@vm.exe.xyz:app.git` as the remote's address ([why](/docs/faq/ssh-destination)). Each push builds a new release next to the running one: a clean copy of the commit, `npm ci` (or pnpm, Yarn, or Bun, matching your lockfile), your `build` script if you have one (TypeScript, say), and your `db:migrate` script if you have one. Only then does `~/app` switch to it and `app.service` restart, which takes a second. If anything fails, including a new version that doesn't answer on port 8000, the hook puts the old version back and git rejects the push: `! [remote rejected] main -> main (pre-receive hook declined)`. The VM's `main` stays at the commit that's running, as on Heroku. Migrations that already ran stay applied; there's a backup from just before them. To roll back, push an older commit: `git push -f exe :main`. To work locally, run `npm install`, then `npm run db:migrate` and `npm run dev` in a new app: it restarts on every change (`node --watch`) and reads a `.env` file if you make one. > [!TIP] > Want `git push` to deploy and update GitHub at once? Give `origin` two > push addresses: `git remote set-url --add --push origin > git@github.com:you/app.git` and then `git remote set-url --add --push > origin my-nodejs.exe.xyz:app.git`. ## Settings and secrets Environment variables live in one file on the VM, `~/app.env`, as `KEY=value` lines; `app.service` and the deploy hook both read it. Put values containing spaces or `$` in single quotes. On the VM: ```bash nano ~/app.env sudo systemctl restart app ``` If your `build` step reads a variable (a bundler inlining it into browser code, say), redeploy instead: `~/app.git/hooks/pre-receive HEAD`. The service sets `NODE_ENV=production` and `PORT=8000`; a line in `~/app.env` overrides either. Keep a copy of `~/app.env` somewhere safe; the nightly backup includes it. ## Express behind the proxy exe.dev's [HTTPS proxy](/docs/proxy) ends TLS and connects to your app from 127.0.0.1, with the visitor's details in `X-Forwarded-Proto`, `X-Forwarded-Host`, and `X-Forwarded-For`. The new app trusts those headers from there, and only from there: ```js app.set("trust proxy", "loopback"); ``` Without it, `req.protocol` says `http`, `req.ip` is the proxy's address for every visitor (so a rate limiter blocks everyone at once), and `express-session` won't send a `secure` cookie, so logins don't stick. Add the line to an app you brought. Don't use `true`: that trusts whatever a client puts in the header. The `Host` header is already the public name (`my-nodejs.exe.xyz`, or your own domain), so links built from `req.hostname` are right. ## Your database A new app uses SQLite through `node:sqlite`, which is built into Node.js: no native module to compile, no ORM. The database is `~/data/app.db` (`DATABASE_URL=file:/home/exedev/data/app.db` in `~/app.env`). SQLite on the VM's own disk is fast, needs no server, and is easy to back up. Migrations are numbered SQL files in `migrations/`. To change the schema, add the next one **on your computer** and push: ```bash echo 'ALTER TABLE messages ADD COLUMN mood TEXT;' > migrations/002-mood.sql git add migrations && git commit -m "Add a mood" && git push exe main ``` The deploy runs `npm run db:migrate` (here `node migrate.js`, which applies the files it hasn't yet and records the last one in SQLite's `user_version`) after a backup and before the switch. That's the hook's convention for any app: a `db:migrate` script that applies migrations without prompting. - **Prisma, Drizzle, Knex, Sequelize**: make `db:migrate` run their deploy command (`prisma migrate deploy`, `drizzle-kit migrate`, `knex migrate:latest`), or set `MIGRATE_COMMAND='npx prisma migrate deploy'` in `~/app.env` instead of adding a script. - **PostgreSQL**: set `DATABASE_URL=postgresql://...` in `~/app.env`, a hosted database's or your own. To run PostgreSQL on this VM, with backups, see [PostgreSQL](/deploy/postgres#run-it-next-to-your-app). Put uploads and any other files your app writes under `~/data` too, so the backup picks them up. Releases are replaced on every deploy. ## Make it public, add a domain The app is private: only people you've [shared it with](/docs/sharing) can open it, after signing in to exe.dev. When you're ready for the world, **on your computer**: ```bash ssh exe.dev share set-public my-nodejs ``` `ssh exe.dev share set-private my-nodejs` closes it again. To serve it on your own domain, point a CNAME at `my-nodejs.exe.xyz` and run `ssh exe.dev domain add my-nodejs app.example.com`; exe.dev issues the certificate ([custom domains](/docs/cnames)). Once the app is public, visitors aren't signed in unless they sign in on purpose; see the next section. ## Let exe.dev handle sign-in For an internal tool, you may not need your own login at all. For visitors signed in to exe.dev, the proxy adds `X-ExeDev-Email` and `X-ExeDev-UserID` headers to each request ([login with exe](/docs/login-with-exe)), and it removes any a visitor sends. On a private app, that's everyone who gets in. On a public one, visitors have no header until they sign in at `https://my-nodejs.exe.xyz/__exe.dev/login?redirect=/`. In Express: ```js const email = req.get("x-exedev-email"); // undefined if signed out ``` The new app's guestbook signs messages this way, as "a visitor" for anyone signed out. To require sign-in for some pages, send signed-out visitors to that login page: ```js // /admin is only for people signed in to exe.dev. app.use("/admin", (req, res, next) => { if (req.get("x-exedev-email")) return next(); res.redirect("/__exe.dev/login?redirect=" + encodeURIComponent(req.originalUrl)); }); ``` Who may use `/admin` is then up to you: compare the email with a list in `~/app.env`, say. ## Hono, Fastify, and Bun The service runs `npm start` with `PORT=8000`, like Heroku, so any Node.js server that listens on `process.env.PORT` deploys as it is. - **Fastify** listens on 127.0.0.1 by default, which is where exe.dev's proxy connects, so `fastify.listen({ port: Number(process.env.PORT) })` is enough. Trust the proxy with `Fastify({ trustProxy: "127.0.0.1" })`. - **Hono** on Node.js needs its adapter, `@hono/node-server`: `serve({ fetch: app.fetch, port: Number(process.env.PORT) })`. - **No `start` script?** npm runs `node server.js` if that file exists. Otherwise add one: `npm pkg set scripts.start="node dist/index.js"`. **Bun.** If your repository has a `bun.lock`, the hook installs with Bun, which you add once. On the VM: ```bash curl -fsSL https://bun.sh/install | bash -s "bun-v1.4.4" sudo ln -sf ~/.bun/bin/bun /usr/local/bin/bun sudo mkdir -p /etc/systemd/system/app.service.d printf '[Service]\nExecStart=\nExecStart=/usr/local/bin/bun run start\n' | sudo tee /etc/systemd/system/app.service.d/bun.conf sudo systemctl daemon-reload ~/app.git/hooks/pre-receive HEAD ``` The link puts `bun` where the hook and systemd find it, and the drop-in makes the service run your `start` script with Bun. Bun reads `PORT`, so a Hono app's `export default app` needs no change. `bun upgrade` updates it later. ## Cron jobs Run scheduled work with systemd timers, the same way the backup runs: a script in your app, run in the current release with your settings. For example, a new app's `scripts/prune.js` that deletes guestbook messages older than 90 days: ```js import { db } from "../db.js"; const { changes } = db .prepare("DELETE FROM messages WHERE created_at < datetime('now', '-90 days')") .run(); console.log(`Deleted ${changes} old messages`); ``` Push it, then add a timer **on the VM**: ```bash sudo tee /etc/systemd/system/app-prune.service >/dev/null <<'EOF' [Unit] Description=Delete old guestbook messages [Service] Type=oneshot User=exedev WorkingDirectory=/home/exedev/app EnvironmentFile=/home/exedev/app.env ExecStart=/usr/bin/node scripts/prune.js EOF sudo tee /etc/systemd/system/app-prune.timer >/dev/null <<'EOF' [Unit] Description=Delete old guestbook messages every night [Timer] OnCalendar=*-*-* 04:00:00 UTC Persistent=true [Install] WantedBy=timers.target EOF sudo systemctl daemon-reload sudo systemctl enable --now app-prune.timer sudo systemctl start app-prune.service && journalctl -u app-prune -n 3 --no-pager ``` The last line runs it once and shows its output. `OnCalendar` reads like cron: `*:0/15` is every 15 minutes, `Mon *-*-* 09:00` is Monday mornings. A queue worker (BullMQ, say) is a long-running process instead: copy `app.service` to `app-worker.service` with its own `ExecStart`, and add `sudo systemctl restart app-worker` to the hook after the app's restart. ## Keep your data Every night, `~/bin/app-backup` saves `~/data` (SQLite through its `.backup` command, so the copy is consistent), `~/app.env`, and the whole `~/app.git` repository into `~/backups/app-nightly-