Deploy a Node.js app

Create the VM#

On your computer (pick another name if my-nodejs is taken):

ssh exe.dev new --name=my-nodejs
ssh my-nodejs.exe.xyz

Everything else runs on the VM, as exedev.

Install Node.js#

The exeuntu image has no Node.js, or an old one. Install Node.js 26, the current LTS release, from NodeSource's apt repository. It lands in /usr/bin, where systemd, the git hook, and your shell all find the same node, and sudo apt upgrade brings its security fixes.

curl -fsSL https://deb.nodesource.com/setup_26.x | sudo -E bash -
sudo apt-get install -y nodejs sqlite3 rsync
sudo npm install -g corepack && sudo corepack enable
node --version

Expect v26. and a patch version. Node.js 25 and later no longer ship Corepack, which provides pnpm and yarn for repositories that use them, hence the npm install line. The backup uses sqlite3 and rsync. If your app's engines field or .nvmrc asks for another major version, use that number in the setup_ URL instead.

Settings, data, and the service#

Create the data and release directories and a private settings file. This leaves an existing ~/app.env alone:

mkdir -p ~/data ~/releases ~/backups
if [ ! -e ~/app.env ]; then
  install -m 600 /dev/null ~/app.env
  cat >> ~/app.env <<'EOF'
# Settings and secrets for the app: KEY=value, one per line. Quote values
# with spaces or $ in 'single quotes'. Read by app.service and the deploy.
# After changing it: sudo systemctl restart app
EOF
fi
stat -c '%a %n' ~/app.env

Expect 600 /home/exedev/app.env. Now the service. It runs npm start in ~/app, which will point at the current release, with PORT=8000, where exe.dev's proxy sends https://my-nodejs.exe.xyz/:

sudo tee /etc/systemd/system/app.service >/dev/null <<'EOF'
[Unit]
Description=Node.js app (npm start in ~/app)
After=network-online.target
Wants=network-online.target

[Service]
User=exedev
WorkingDirectory=/home/exedev/app
Environment=NODE_ENV=production PORT=8000
# Lines in app.env override the two above.
EnvironmentFile=/home/exedev/app.env
ExecStart=/usr/bin/npm start
Restart=always
RestartSec=3
TimeoutStopSec=30

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable app.service

It starts with the first deploy. On a restart, systemd sends SIGTERM to the app; the new app closes its server on that signal so requests in flight can finish.

Back up every night#

~/bin/app-backup saves everything that isn't in a release: ~/data (each SQLite database through .backup, which is safe while the app writes, and then checked), ~/app.env, and the repository in ~/app.git as a git bundle. A new app's only copy lives there until you clone it. It keeps the 14 newest backups of each kind: nightly, deploy (the hook takes one before running migrations), and manual.

mkdir -p ~/bin
cat > ~/bin/app-backup <<'EOF'
#!/usr/bin/env bash
# Back up ~/data, ~/app.env and ~/app.git to ~/backups/app-<kind>-<time>.tar.gz.
# SQLite databases are copied with .backup, safe while the app runs, and
# checked. Keeps the 14 newest backups of each kind.
# Usage: app-backup [nightly|deploy|manual]
set -euo pipefail
umask 077
kind=${1:-manual}
work=$(mktemp -d)
trap 'rm -rf "$work"' EXIT
mkdir -p "$HOME/backups" "$work/data"
cd "$HOME/data"
rsync -a --exclude='*.db' --exclude='*.db-*' --exclude='*.sqlite*' ./ "$work/data/"
find . -type f \( -name '*.db' -o -name '*.sqlite' -o -name '*.sqlite3' \) | while read -r db; do
  mkdir -p "$work/data/$(dirname "$db")"
  sqlite3 "$db" ".backup '$work/data/$db'"
  [ "$(sqlite3 "$work/data/$db" 'PRAGMA quick_check')" = ok ]
done
cp "$HOME/app.env" "$work/"
if git -C "$HOME/app.git" rev-parse -q --verify HEAD >/dev/null; then
  git -C "$HOME/app.git" bundle create -q "$work/app.bundle" --all
fi
out="$HOME/backups/app-$kind-$(date -u +%Y%m%d-%H%M%S).tar.gz"
tar -czf "$out.part" -C "$work" .
mv "$out.part" "$out"
ls -1t "$HOME/backups/app-$kind-"*.tar.gz | tail -n +15 | xargs -r rm --
echo "$out"
EOF
chmod +x ~/bin/app-backup

Run it every night with a systemd timer:

sudo tee /etc/systemd/system/app-backup.service >/dev/null <<'EOF'
[Unit]
Description=Back up the app's data, settings and repository to ~/backups

[Service]
Type=oneshot
User=exedev
ExecStart=/home/exedev/bin/app-backup nightly
EOF
sudo tee /etc/systemd/system/app-backup.timer >/dev/null <<'EOF'
[Unit]
Description=Back up the app every night

[Timer]
OnCalendar=*-*-* 03:00:00 UTC
RandomizedDelaySec=30m
Persistent=true

[Install]
WantedBy=timers.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now app-backup.timer
systemctl list-timers app-backup.timer

Expect the next run, tonight. You'll take the first backup once the app is deployed.

Get the code#

The VM deploys from a bare git repository, ~/app.git. Create it one of two ways.

Start a new app (REPO=new): an empty repository whose branch is main.

git init --bare -b main ~/app.git

Bring your GitHub repository: a copy of it. A public repository clones directly; replace OWNER/NAME:

git clone --bare https://github.com/OWNER/NAME.git ~/app.git
git -C ~/app.git symbolic-ref --short HEAD

The last line prints the branch that will deploy: your default branch.

For a private repository, connect GitHub to exe.dev once (on the Integrations page) and attach the repository to this VM. On your computer:

ssh exe.dev integrations add github --name nodejs-repo --repository OWNER/NAME --readonly --attach vm:my-nodejs

Then clone through the integration on the VM. No token lands on the disk (GitHub integration):

git clone --bare https://github.int.exe.xyz/OWNER/NAME.git ~/app.git

If that clone fails with "not found" or a 403, the integration isn't attached to this VM yet.

Add the deploy hook#

Git runs hooks/pre-receive before it accepts a push, as Heroku does. This one builds the pushed commit in its own directory under ~/releases, runs migrations, switches ~/app to it, restarts the service, and checks that it answers. If any step fails, it switches back and rejects the push, so main on the VM is always what's running.

cat > ~/app.git/hooks/pre-receive <<'EOF'
#!/usr/bin/env bash
# Deploys the app. Git runs this before accepting a push to ~/app.git;
# if the deploy fails, the push is rejected and the running version stays.
# To redeploy main by hand (after editing ~/app.env, say):
#   ~/app.git/hooks/pre-receive HEAD
set -euo pipefail
export GIT_DIR=$HOME/app.git
branch=$(git symbolic-ref --short HEAD)  # the branch that deploys
rev=
if [ $# -gt 0 ]; then
  rev=$(git rev-parse --verify "$1^{commit}")
else
  while read -r _ new ref; do
    [ "$ref" = "refs/heads/$branch" ] || continue
    case $new in
      *[!0]*) rev=$new ;;
      *) echo "==> Refusing to delete $branch: it's what deploys."; exit 1 ;;
    esac
  done
  [ -n "$rev" ] || exit 0  # other branches are kept, not deployed
fi

exec 9>"$HOME/.deploy.lock" && flock 9  # one deploy at a time
release=$HOME/releases/$(date -u +%Y%m%d-%H%M%S)-${rev:0:7}
previous=$(readlink "$HOME/app" || true)
fail() {  # put the previous release back and reject the push
  trap - ERR
  echo "==> Deploy FAILED${1:+: $1}. Still running: ${previous:-nothing}"
  if [ -n "$previous" ] && [ "$(readlink "$HOME/app")" != "$previous" ]; then
    ln -sfn "$previous" "$HOME/app.new" && mv -T "$HOME/app.new" "$HOME/app"
    sudo systemctl restart app
  fi
  rm -rf "$release"
  exit 1
}
trap fail ERR

echo "==> Building ${rev:0:7} in $release"
mkdir -p "$release"
git archive "$rev" | tar -x -C "$release"
unset GIT_DIR GIT_OBJECT_DIRECTORY GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_QUARANTINE_PATH
cd "$release"
set -a; . "$HOME/app.env"; set +a
unset NODE_ENV  # install devDependencies too, for the build; app.service sets it
export COREPACK_ENABLE_DOWNLOAD_PROMPT=0
if [ -f bun.lock ] || [ -f bun.lockb ]; then bun install --frozen-lockfile
elif [ -f pnpm-lock.yaml ]; then pnpm install --frozen-lockfile
elif [ -f yarn.lock ] && [ -f .yarnrc.yml ]; then yarn install --immutable
elif [ -f yarn.lock ]; then yarn install --frozen-lockfile
elif [ -f package-lock.json ]; then npm ci
else npm install
fi
npm run build --if-present
migrate=${MIGRATE_COMMAND:-}
if [ -z "$migrate" ] && node -e 'process.exit(require("./package.json").scripts?.["db:migrate"] ? 0 : 1)'; then
  migrate="npm run db:migrate"
fi
if [ -n "$migrate" ]; then
  "$HOME/bin/app-backup" deploy >/dev/null  # back up before migrating
  bash -c "$migrate"
  echo
fi

echo "==> Starting the new version"
ln -sfn "$release" "$HOME/app.new" && mv -T "$HOME/app.new" "$HOME/app"
sudo systemctl restart app
for _ in $(seq 60); do
  code=$(curl -s -o /dev/null -m 10 -w '%{http_code}' http://localhost:8000/ || true)
  case $code in 000|5??) sleep 1 ;; *) break ;; esac
done
case $code in
  000|5??) fail "the new version answers HTTP $code (journalctl -u app -n 50)" ;;
esac
trap - ERR
ls -1d "$HOME"/releases/*/ | head -n -3 | xargs -r rm -rf  # keep 3
echo "==> Deployed ${rev:0:7}: HTTP $code on port 8000"
EOF
chmod +x ~/app.git/hooks/pre-receive

The hook installs with your lockfile's package manager, then runs the build script if package.json has one and the db:migrate script if it has one (or MIGRATE_COMMAND from ~/app.env), after a deploy backup. It counts any answer on port 8000 below 500 as up.

Start a new app#

Skip to Deploy and check if you brought a repository. Otherwise, make an Express 5 app with a script for migrations, and point it at ~/data:

rm -rf /tmp/new-app && mkdir -p "/tmp/new-app/$(hostname)" && cd "/tmp/new-app/$(hostname)"
git init -q -b main
npm init -y >/dev/null
npm pkg set type=module 'engines.node=>=26' 'scripts.start=node server.js' \
  'scripts.dev=node --watch --env-file-if-exists=.env server.js' 'scripts.db:migrate=node migrate.js'
npm pkg delete main scripts.test
npm install express@5
printf 'node_modules/\n.env\n*.db\n*.db-*\n' > .gitignore
echo 'DATABASE_URL=file:/home/exedev/data/app.db' >> ~/app.env

The database connection, the migration runner, and the first migration:

cd "/tmp/new-app/$(hostname)"
cat > db.js <<'EOF'
import { DatabaseSync } from "node:sqlite";

// On the VM, ~/app.env sets DATABASE_URL=file:/home/exedev/data/app.db
const file = (process.env.DATABASE_URL ?? "file:app.db").replace(/^file:/, "");
export const db = new DatabaseSync(file);
db.exec("PRAGMA journal_mode = WAL; PRAGMA busy_timeout = 5000;");
EOF
cat > migrate.js <<'EOF'
// Applies migrations/NNN-*.sql in order, each in a transaction.
// SQLite's user_version remembers the last one applied.
import { readdirSync, readFileSync } from "node:fs";
import { db } from "./db.js";

const dir = new URL("migrations/", import.meta.url);
const done = db.prepare("PRAGMA user_version").get().user_version;
for (const file of readdirSync(dir).filter((f) => f.endsWith(".sql")).sort()) {
  const n = parseInt(file, 10);
  if (n <= done) continue;
  db.exec("BEGIN");
  try {
    db.exec(readFileSync(new URL(file, dir), "utf8"));
    db.exec(`PRAGMA user_version = ${n}`);
    db.exec("COMMIT");
  } catch (err) {
    db.exec("ROLLBACK");
    throw err;
  }
  console.log(`Applied ${file}`);
}
EOF
mkdir -p migrations
cat > migrations/001-messages.sql <<'EOF'
CREATE TABLE messages (
  id INTEGER PRIMARY KEY,
  author TEXT NOT NULL,
  body TEXT NOT NULL,
  created_at TEXT NOT NULL DEFAULT (datetime('now'))
);
EOF

The app: a guestbook that saves messages signed with the visitor's exe.dev name, and shuts down cleanly when systemd stops it.

cd "/tmp/new-app/$(hostname)"
cat > server.js <<'EOF'
import express from "express";
import { db } from "./db.js";

const app = express();
// exe.dev's proxy connects from 127.0.0.1: trust its X-Forwarded-* headers from there only.
app.set("trust proxy", "loopback");
app.use(express.urlencoded({ extended: false }));

const esc = (s) => String(s).replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);

app.get("/", (req, res) => {
  const rows = db.prepare("SELECT author, body FROM messages ORDER BY id DESC LIMIT 50").all();
  const list = rows.map((m) => `<li><b>${esc(m.author)}</b>: ${esc(m.body)}</li>`).join("");
  res.send(`<!doctype html>
<html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width">
<title>Guestbook</title></head>
<body style="font-family: system-ui; max-width: 36rem; margin: 2rem auto; padding: 0 1rem">
<h1>Guestbook</h1>
<form method="post"><input name="body" required maxlength="280" placeholder="Say hello"> <button>Sign</button></form>
${list ? `<ul>${list}</ul>` : "<p>No messages yet. Be the first.</p>"}
</body></html>`);
});

app.post("/", (req, res) => {
  const body = String(req.body.body ?? "").trim().slice(0, 280);
  // exe.dev's proxy tells the app who is signed in.
  const email = req.get("x-exedev-email");
  const author = email ? email.split("@")[0] : "a visitor";
  if (body) db.prepare("INSERT INTO messages (author, body) VALUES (?, ?)").run(author, body);
  res.redirect(303, "/");
});

const port = Number(process.env.PORT ?? 3000);
const server = app.listen(port, (err) => {
  if (err) throw err;
  console.log(`Listening on http://localhost:${port}`);
});
// systemd sends SIGTERM on restart: finish the requests in flight, then exit.
process.on("SIGTERM", () => server.close(() => process.exit(0)));
EOF

Commit and push to the VM's repository. The push deploys:

cd "/tmp/new-app/$(hostname)"
git add .gitignore package.json package-lock.json db.js migrate.js migrations server.js
git -c user.name="$(hostname)" -c user.email="exedev@$(hostname).exe.xyz" commit -qm "Express guestbook on SQLite"
git push ~/app.git HEAD:main

The output ends with ==> Deployed and a commit. The code now lives in ~/app.git (the owner clones it from there), so remove the scratch copy:

cd ~ && rm -rf /tmp/new-app

Deploy and check#

If you brought a repository, put its settings in ~/app.env first. Look for .env.example or the README; generate secrets such as SESSION_SECRET with openssl rand -hex 32. If it uses SQLite, point it at ~/data, for example DATABASE_URL=file:/home/exedev/data/app.db. Then deploy its default branch:

~/app.git/hooks/pre-receive HEAD

(A new app deployed when you pushed it.) Check, for either kind:

systemctl is-enabled app; systemctl is-active app
readlink ~/app
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8000/

Expect enabled, active, the release directory, and 200 (or your home page's usual status, such as a 302 to a login page). For a new app, sign the guestbook through the port the proxy uses, as a signed-in visitor would:

curl -s -o /dev/null -H 'X-ExeDev-Email: setup@example.com' --data-urlencode 'body=Hello from setup' http://localhost:8000/
curl -s http://localhost:8000/ | grep -o '<b>setup</b>: Hello from setup'
sqlite3 ~/data/app.db 'PRAGMA user_version; DELETE FROM messages'

Expect <b>setup</b>: Hello from setup and 1, the migration applied; the last command also removes the test message.

Check the backup#

Take the first backup by hand, then open it in a scratch directory, never over ~/data, to check that it holds what a restore needs:

latest=$(~/bin/app-backup manual)
rm -rf /tmp/restore-check && mkdir /tmp/restore-check
tar -xzf "$latest" -C /tmp/restore-check
ls -A /tmp/restore-check /tmp/restore-check/data
git -C ~/app.git bundle verify /tmp/restore-check/app.bundle
find /tmp/restore-check/data -type f \( -name '*.db' -o -name '*.sqlite' -o -name '*.sqlite3' \) |
  while read -r db; do echo "$db: $(sqlite3 "$db" 'PRAGMA integrity_check')"; done
rm -rf /tmp/restore-check

Expect app.bundle, app.env, and data; The bundle records a complete history; and ok for each database (a new app has app.db).

Setup is done. Continue with Open your app.

On the same VM#

On the VM, pick the archive (ls -lt ~/backups), unpack it, and swap its data in while the app is stopped. The current data is kept aside:

backup=~/backups/app-nightly-20261031-030512.tar.gz   # the one you want
rm -rf /tmp/restore && mkdir /tmp/restore && tar -xzf "$backup" -C /tmp/restore
sudo systemctl stop app
mv ~/data ~/data.before-restore-$(date +%s)
cp -a /tmp/restore/data ~/data
sudo systemctl start app

Open the app and check your data. If the backup is older than your latest migration, apply it with ~/app.git/hooks/pre-receive HEAD. ~/app.env is in /tmp/restore too, if you need an old setting back. Delete ~/data.before-restore-* when you're sure.

On a new VM#

Create the VM and follow Set up by hand up to, but not including, "Get the code". Copy the archive over from your computer (scp app-nightly-20261031-030512.tar.gz my-nodejs.exe.xyz:), then on the VM:

rm -rf /tmp/restore && mkdir /tmp/restore && tar -xzf ~/app-nightly-20261031-030512.tar.gz -C /tmp/restore
git clone --bare /tmp/restore/app.bundle ~/app.git && git -C ~/app.git remote remove origin
install -m 600 /tmp/restore/app.env ~/app.env
rm -rf ~/data && cp -a /tmp/restore/data ~/data

Then follow Add the deploy hook and deploy with ~/app.git/hooks/pre-receive HEAD. On your computer, point the exe remote at the new VM: git remote set-url exe <new-vm>.exe.xyz:app.git.

Express and your other packages are dependencies of your app, so update them on your computer and deploy:

npm outdated
npm update
git commit -am "Update dependencies" && git push exe main

Node.js patch releases arrive with the system's updates. On the VM:

sudo apt-get update && sudo apt-get install -y nodejs
sudo systemctl restart app
node --version

To move to a newer major version (Node.js 27 is due to become LTS in October 2027), take a backup, switch the apt repository, and redeploy right away: if your app uses native modules, such as better-sqlite3 or bcrypt, the running release's copies were built for the old Node.js, and the deploy rebuilds them.

~/bin/app-backup
curl -fsSL https://deb.nodesource.com/setup_27.x | sudo -E bash -
sudo apt-get install -y nodejs
~/app.git/hooks/pre-receive HEAD

On the VM, the app's logs:

journalctl -u app -n 100 --no-pager

• git push says Deploy FAILED and pre-receive hook declined. The lines above it are the error: a failed install or build, a migration error, or, after Starting the new version, an app that crashed or didn't answer (its logs are in journalctl -u app). The running version didn't change; fix it and push again.
• npm ci fails: package.json and package-lock.json are not in sync. Run npm install on your computer and commit package-lock.json.
• The app starts, but the deploy says HTTP 000. It isn't listening on port 8000: read PORT from the environment instead of hard-coding a port.
• Error: Cannot find module at start. A package the app needs at runtime is in devDependencies, or a TypeScript app's start script points at files the build script didn't write.
• SyntaxError: Cannot use import statement outside a module. Add "type": "module" to package.json, or use require.
• Every visitor has the same IP, or logins don't stick. Set trust proxy; see Express behind the proxy.
• A new environment variable has no effect. sudo systemctl restart app; if the build uses it, redeploy with ~/app.git/hooks/pre-receive HEAD.
• no such table. Migrations didn't run: check that npm run db:migrate exists and works, and look for its output in the push.
• The site shows exe.dev's error page after a reboot. Check systemctl status app; it should be enabled. readlink ~/app must point at an existing release.
• Disk filling up. du -sh ~/releases/* ~/backups ~/.npm; the hook keeps three releases, and npm cache clean --force empties npm's cache.