Deploy Next.js on your own server

Create the VM#

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

ssh exe.dev new --name=my-nextjs
ssh my-nextjs.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 24, 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. Next.js 16 needs Node.js 20.9 or later.

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

Expect v24. and a patch version. corepack enable provides pnpm and yarn for repositories that use them; libjemalloc2 is the memory allocator sharp recommends; 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 the build (NEXT_PUBLIC_*
# values end up in the browser's JavaScript) and by app.service.
# After changing it, redeploy: ~/app.git/hooks/pre-receive HEAD
EOF
fi
stat -c '%a %n' ~/app.env

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

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

[Service]
User=exedev
WorkingDirectory=/home/exedev/app
EnvironmentFile=/home/exedev/app.env
Environment=PORT=8000
# sharp, behind next/image, recommends jemalloc over glibc's allocator.
Environment=LD_PRELOAD=libjemalloc.so.2
ExecStart=/home/exedev/app/node_modules/.bin/next 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. The service runs next start directly, not npm start, so a start script that sets another port doesn't get in the way. If your app has a custom server (a server.js), change ExecStart to /usr/bin/node server.js and have it listen on PORT.

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 nextjs-repo --repository OWNER/NAME --readonly --attach vm:my-nextjs

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  # the build needs devDependencies; next sets NODE_ENV itself
export COREPACK_ENABLE_DOWNLOAD_PROMPT=0
if [ -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
migrate=${MIGRATE_COMMAND:-}
if [ -z "$migrate" ] && [ "$(npm pkg get scripts.db:migrate)" != "{}" ]; 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 npm run build and the db:migrate script if package.json 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 if you brought a repository. Otherwise, generate an app with create-next-app's defaults (TypeScript, Tailwind CSS, ESLint, the App Router, and Cache Components):

rm -rf /tmp/new-app && mkdir /tmp/new-app && cd /tmp/new-app
npx --yes create-next-app@latest "$(hostname)" --yes

Add Drizzle with SQLite, and scripts for making and applying migrations:

cd "/tmp/new-app/$(hostname)"
npm install drizzle-orm better-sqlite3
npm install --save-dev drizzle-kit @types/better-sqlite3
npm pkg set 'scripts.db:generate=drizzle-kit generate' 'scripts.db:migrate=drizzle-kit migrate'
printf '\n# SQLite databases (on the VM, data lives in ~/data)\n*.db\n*.db-*\n' >> .gitignore
echo 'DATABASE_URL=file:/home/exedev/data/app.db' >> ~/app.env

The schema, the connection, and Drizzle Kit's configuration:

cd "/tmp/new-app/$(hostname)"
mkdir -p db
cat > db/schema.ts <<'EOF'
import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";

export const messages = sqliteTable("messages", {
  id: integer("id").primaryKey({ autoIncrement: true }),
  author: text("author").notNull(),
  body: text("body").notNull(),
  createdAt: integer("created_at", { mode: "timestamp" })
    .notNull()
    .$defaultFn(() => new Date()),
});
EOF
cat > db/index.ts <<'EOF'
import Database from "better-sqlite3";
import { drizzle } from "drizzle-orm/better-sqlite3";

// 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:/, "");
const sqlite = new Database(file);
sqlite.pragma("journal_mode = WAL");
sqlite.pragma("busy_timeout = 5000");

export const db = drizzle(sqlite);
EOF
cat > drizzle.config.ts <<'EOF'
import { defineConfig } from "drizzle-kit";

export default defineConfig({
  dialect: "sqlite",
  schema: "./db/schema.ts",
  out: "./drizzle",
  dbCredentials: { url: process.env.DATABASE_URL ?? "file:app.db" },
});
EOF

The guestbook: a Server Action that saves a message, signed with the visitor's exe.dev name, and a list read from the database on each request. connection() keeps that read out of the build; Cache Components asks for it to sit inside <Suspense>.

cd "/tmp/new-app/$(hostname)"
mkdir -p app/guestbook
cat > app/guestbook/page.tsx <<'EOF'
import { Suspense } from "react";
import { headers } from "next/headers";
import { connection } from "next/server";
import { revalidatePath } from "next/cache";
import { desc } from "drizzle-orm";
import { db } from "@/db";
import { messages } from "@/db/schema";

async function sign(formData: FormData) {
  "use server";
  const body = String(formData.get("body") ?? "").trim().slice(0, 280);
  if (!body) return;
  // exe.dev's proxy tells the app who is signed in.
  const email = (await headers()).get("x-exedev-email");
  const author = email ? email.split("@")[0] : "a visitor";
  db.insert(messages).values({ author, body }).run();
  revalidatePath("/guestbook");
}

async function Messages() {
  await connection(); // read the database on each request, not at build time
  const rows = db.select().from(messages).orderBy(desc(messages.id)).limit(50).all();
  if (rows.length === 0) return <p>No messages yet. Be the first.</p>;
  return (
    <ul className="space-y-2">
      {rows.map((m) => (
        <li key={m.id}>
          <b>{m.author}</b>: {m.body}
        </li>
      ))}
    </ul>
  );
}

export default function GuestbookPage() {
  return (
    <main className="mx-auto max-w-xl space-y-6 p-8">
      <h1 className="text-2xl font-semibold">Guestbook</h1>
      <form action={sign} className="flex gap-2">
        <input name="body" required maxLength={280} placeholder="Say hello"
          className="flex-1 rounded border px-3 py-2" />
        <button className="rounded bg-black px-4 py-2 text-white">Sign</button>
      </form>
      <Suspense fallback={<p>Loading…</p>}>
        <Messages />
      </Suspense>
    </main>
  );
}
EOF

Generate the first migration, commit, and push to the VM's repository. The push deploys:

cd "/tmp/new-app/$(hostname)"
npm run db:generate
git add .gitignore package.json package-lock.json drizzle.config.ts db drizzle app
git -c user.name="$(hostname)" -c user.email="exedev@$(hostname).exe.xyz" commit -qm "Add a guestbook: Drizzle with 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 AUTH_SECRET with openssl rand -base64 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/
cd ~/app && node -p "require(require.resolve('sharp', { paths: [require.resolve('next')] })).versions.sharp"

Expect enabled, active, the release directory, 200 (or your home page's usual status, such as a 307 to a login page), and sharp's version. For a new app, check that the guestbook reads the database:

curl -s http://localhost:8000/guestbook | grep -o 'No messages yet' | head -1
sqlite3 ~/data/app.db .tables

Expect No messages yet and __drizzle_migrations messages.

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-20261017-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. ~/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-20261017-030512.tar.gz my-nextjs.exe.xyz:), then on the VM:

rm -rf /tmp/restore && mkdir /tmp/restore && tar -xzf ~/app-nightly-20261017-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.

Next.js is a dependency of your app, so update it on your computer and deploy:

npm install next@latest react@latest react-dom@latest eslint-config-next@latest
npm run build
git commit -am "Update Next.js" && git push exe main

For a new major version, read the upgrade guide first; npx @next/codemod@canary upgrade latest does most of the work.

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 LTS major (Node.js 26 is due to become LTS in late October 2026), take a backup, switch the apt repository, and redeploy right away without restarting first: the running release's native modules, such as better-sqlite3, were built for the old Node.js.

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

Node.js 25 and later no longer include Corepack, hence the npm install line, which keeps pnpm and yarn working.

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, often the same one npm run build gives on your computer. The running version didn't change; fix it and push again.
• Error: Cannot find module or next: not found during the build or at start. The package manager didn't install everything. Check that your lockfile is committed and up to date (npm install on your computer, then commit package-lock.json).
• A Yarn 2+ app can't find next. With Plug'n'Play there's no node_modules for app.service to start from; add nodeLinker: node-modules to .yarnrc.yml.
• The build runs out of memory. Large apps can need more than Node's default heap: add NODE_OPTIONS=--max-old-space-size=4096 to ~/app.env, or give the VM more memory.
• A new environment variable has no effect. Redeploy with ~/app.git/hooks/pre-receive HEAD; NEXT_PUBLIC_* values are fixed at build time.
• Invalid Server Actions request. Something between exe.dev and Next.js rewrites X-Forwarded-Host; see Server Actions.
• Redirects go to localhost:8000. The code builds URLs from request.url; use X-Forwarded-Host or a relative path.
• SqliteError: 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.