--- title: "Deploy Next.js on your own server" description: "Run a Next.js app on an exe.dev VM: git push to deploy, HTTPS, Server Actions, ISR and image optimization, SQLite on a persistent disk, nightly backups." url: https://exe-staging.dev/deploy/nextjs category: "Frameworks" updated: 2026-10-17 --- # Deploy Next.js on your own server Your Next.js app on a server of its own. git push to deploy. - **Software:** Next.js (https://nextjs.org) - **Source:** https://github.com/vercel/next.js - **License:** MIT - **Time:** 15 minutes - **Example VM name:** `my-nextjs` (yours will differ; on the VM, `hostname` prints it) - **Machine-readable:** https://exe-staging.dev/deploy/nextjs/manifest.json ## What you get - Node.js 24 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 build 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 create-next-app project whose /guestbook page saves messages to SQLite. Running on the VM: - **Next.js 16**: next start, as app.service under systemd, port 8000, data in `~/app → the current release in ~/releases` - **Node.js 24 LTS**: NodeSource's apt package; npm, pnpm, and Yarn - **git push deploys**: A pre-receive hook in ~/app.git builds, migrates, and switches - **SQLite**: Drizzle ORM 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-nextjs.exe.xyz/ (private): Your app, until you make it public ## Deploy with Shelley Open https://exe-staging.dev/new?prompt=REPO%3D%3Cfill-this-in%3E%0A%0ASet%20up%20Next.js%20on%20this%20VM%20by%20following%20the%20exe.dev%20recipe%20at%20https%3A%2F%2Fexe-staging.dev%2Fdeploy%2Fnextjs.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%20Next.js%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-nextjs.%20This%20VM%27s%20name%20is%20the%20output%20of%20%60hostname%60%3A%20use%20it%20wherever%20the%20recipe%20writes%20my-nextjs.%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%2024%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%20build%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%20create-next-app%20project%20whose%20%2Fguestbook%20page%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%20a%20build%20fails%2C%20read%20its%20output%2C%0Afix%20what%20you%20can%20without%20editing%20the%20code%2C%20and%20redeploy%20with%0A~%2Fapp.git%2Fhooks%2Fpre-receive%20HEAD.%0AFinish%20with%20the%20app%27s%20URL%20%28and%20%2Fguestbook%20for%20a%20new%20app%29%20and%20the%20git%0Acommands%20the%20owner%20runs%20on%20their%20own%20computer%2C%20from%20%22Deploy%20with%20git%0Apush%22%3A%20%60git%20clone%20-o%20exe%60%20for%20a%20new%20app%2C%20%60git%20remote%20add%20exe%60%20for%20a%0AGitHub%20repository%2C%20then%20%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/nextjs/prompt.txt | ssh exe.dev new --prompt=/dev/stdin ``` Or follow the steps below by hand. Next.js runs best on a server that stays put. On an exe.dev VM your app runs `next start` all the time: no cold starts and no function timeouts, with ISR pages, optimized images, and a SQLite database on a real disk that's still there tomorrow. You deploy with `git push`, 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 app you already have on GitHub, or a fresh one from `create-next-app`. Leaving Vercel? See [what changes](#coming-from-vercel). ## Open your app When setup finishes, open `https://my-nextjs.exe.xyz/` and sign in to exe.dev if asked. A new app shows the create-next-app welcome page; open `/guestbook` and sign it. Your message goes through a Server Action into SQLite in `~/data/app.db`, 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-nextjs.exe.xyz:app.git my-nextjs cd my-nextjs ``` 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-nextjs.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 build 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-nextjs@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 or Yarn, matching your lockfile), `next build`, and your `db:migrate` script if you have one. Only then does `~/app` switch to it and `app.service` restart, which takes a second or two. If the build or anything after it fails, including a new version that doesn't answer, 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`. > [!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-nextjs.exe.xyz:app.git`. ## Settings and secrets Environment variables live in one file on the VM, `~/app.env`, as `KEY=value` lines. Both the build and the running server read it. Put values containing spaces or `$` in single quotes. On the VM: ```bash nano ~/app.env ~/app.git/hooks/pre-receive HEAD ``` The second line redeploys the current commit, so the change takes effect. Why rebuild, not just restart? Because Next.js reads some variables at build time: - `NEXT_PUBLIC_*` variables are copied into the JavaScript sent to browsers when `next build` runs. Changing one needs a rebuild, and anyone can read them, so never put secrets there. - Other variables stay on the server. Code that runs per request sees the current value after `sudo systemctl restart app`. But a page prerendered at build time keeps the value it was built with. Keep a copy of `~/app.env` somewhere safe; the nightly backup includes it. ## Your database A new app uses SQLite through [Drizzle ORM](https://orm.drizzle.team), with the database at `~/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. Drizzle is a thin, typed layer over SQL with no generated client or engine binary, and its migrations are plain SQL files you commit. Change the schema in `db/schema.ts`, then **on your computer**: ```bash npm run db:generate # writes a new SQL file in drizzle/ git add db drizzle && git commit -m "Add a column" && git push exe main ``` The deploy runs `npm run db:migrate` (here `drizzle-kit migrate`) after a successful build and before the switch. That's the hook's convention for any app: a `db:migrate` script that applies migrations without prompting. - **Prisma**: point it at the same disk with `DATABASE_URL="file:/home/exedev/data/app.db"` and add `"db:migrate": "prisma migrate deploy"`. Keep `prisma generate` in `postinstall` or `build`, as on Vercel. - **Other migration commands**: set `MIGRATE_COMMAND='npx prisma migrate deploy'` (or whatever yours is) 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). Drizzle and Prisma both speak it. Put uploads and any other files your app writes under `~/data` too, so the backup picks them up. Releases are replaced on every deploy. ## Server Actions just work To stop cross-site request forgery, Next.js rejects a Server Action unless the browser's `Origin` matches the host the request was sent to. Behind most reverse proxies that check fails, and people reach for `serverActions.allowedOrigins`. You don't need it here: exe.dev's [HTTPS proxy](/docs/proxy) passes the public host in `X-Forwarded-Host`, and Next.js checks against that, for `my-nextjs.exe.xyz`, its other ports, and your own domain alike. If you put something in between that rewrites that header, actions fail with `Invalid Server Actions request` in `journalctl -u app`, after a line like ``x-forwarded-host header with value `localhost:8000` does not match origin``. Fix the proxy, or list the public host in `next.config.ts`: ```ts experimental: { serverActions: { allowedOrigins: ["my-nextjs.exe.xyz"] } }, ``` One thing does differ from Vercel: `request.url` in `proxy.ts` (formerly `middleware.ts`) and in route handlers says `http://localhost:8000`, so absolute URLs built from it point nowhere. Relative redirects, such as `redirect("/login")`, are fine. When you need the public origin, use `X-Forwarded-Host`, as in the [exe.dev login](#let-exedev-handle-sign-in) example below. For Open Graph images and canonical links, set `metadataBase: new URL("https://my-nextjs.exe.xyz")` in your root layout's `metadata`. ## 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-nextjs ``` `ssh exe.dev share set-private my-nextjs` closes it again. To serve it on your own domain, point a CNAME at `my-nextjs.exe.xyz` and run `ssh exe.dev domain add my-nextjs app.example.com`; exe.dev issues the certificate ([custom domains](/docs/cnames)). Next.js needs no change, and Server Actions keep working on the new host. 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)). 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-nextjs.exe.xyz/__exe.dev/login?redirect=/`. Read the headers in any Server Component, Server Action, or route handler: ```ts import { headers } from "next/headers"; const email = (await headers()).get("x-exedev-email"); // null 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 from `proxy.ts`: ```ts import { NextResponse, type NextRequest } from "next/server"; // /admin is only for people signed in to exe.dev. export function proxy(request: NextRequest) { if (request.headers.get("x-exedev-email")) return NextResponse.next(); // request.url says localhost:8000; the public host is in X-Forwarded-Host. const host = request.headers.get("x-forwarded-host") ?? request.headers.get("host"); const login = new URL(`https://${host}/__exe.dev/login`); login.searchParams.set("redirect", request.nextUrl.pathname); return NextResponse.redirect(login); } export const config = { matcher: "/admin/:path*" }; ``` Who may use `/admin` is then up to you: compare the email with a list in `~/app.env`, say. ## Images, ISR, and the cache The features that need special care on serverless hosts are ordinary on one long-running server: - **Image optimization.** `next/image` works with no configuration: sharp comes with Next.js, and resized WebP files (AVIF too, if you add it to `images.formats`) are cached in `.next/cache/images`. The service preloads jemalloc, as sharp recommends on Linux; it avoids memory fragmentation and lets sharp use both CPUs. - **ISR and prerendered pages** live on disk in the release's `.next` directory. When a page with `cacheLife("minutes")` (or `export const revalidate = 60` without Cache Components) goes stale, the next visitor gets the cached copy while Next.js renders a fresh one and writes it to disk, where it survives restarts and reboots. - **`revalidatePath`, `revalidateTag`, and `updateTag`** work as the Next.js docs describe, with no cache handler to write: there's one server, so its cache is the only one to update. - **`'use cache'` results** stay in memory by default, so a restart empties them and they're refilled on demand. Every deploy starts with a fresh cache, because Next.js keys cached entries by build. There's no CDN in front, but `/_next/static` files are served with `immutable` cache headers, so browsers keep them. ## Cron jobs Run scheduled work with systemd timers, the same way the backup runs. The easy pattern, which matches Vercel Cron, is a route handler that the timer calls with a secret. In your app, `app/api/cron/daily/route.ts`: ```ts export async function GET(request: Request) { if (request.headers.get("authorization") !== `Bearer ${process.env.CRON_SECRET}`) { return new Response("Unauthorized", { status: 401 }); } // ...the daily work: send digests, clean up old rows... return Response.json({ ok: true }); } ``` Then, **on the VM**, add a secret and a timer: ```bash grep -q '^CRON_SECRET=' ~/app.env || echo "CRON_SECRET=$(openssl rand -hex 32)" >> ~/app.env sudo systemctl restart app sudo tee /etc/systemd/system/app-cron-daily.service >/dev/null <<'EOF' [Unit] Description=Call the app's daily cron route [Service] Type=oneshot User=exedev EnvironmentFile=/home/exedev/app.env ExecStart=/usr/bin/curl -fsS -H "Authorization: Bearer ${CRON_SECRET}" http://localhost:8000/api/cron/daily EOF sudo tee /etc/systemd/system/app-cron-daily.timer >/dev/null <<'EOF' [Unit] Description=Run the app's daily cron route at 05:00 UTC [Timer] OnCalendar=*-*-* 05:00:00 UTC Persistent=true [Install] WantedBy=timers.target EOF sudo systemctl daemon-reload sudo systemctl enable --now app-cron-daily.timer sudo systemctl start app-cron-daily.service && journalctl -u app-cron-daily -n 3 ``` The last line runs it once and shows the route's answer. `OnCalendar` reads like cron: `*:0/15` is every 15 minutes, `Mon *-*-* 09:00` is Monday mornings. For long jobs, skip the route and run a script in the app's directory: `WorkingDirectory=/home/exedev/app` and `ExecStart=/usr/bin/node scripts/nightly.mjs`. ## Coming from Vercel Your code mostly moves as is. What changes: - **Deploys.** `git push exe main` instead of Vercel's GitHub app. There are no preview deployments; for staging, make a second VM from this recipe ([dev, test, prod](/deploy/dev-test-prod)). - **Environment variables.** Run `vercel env pull .env.production.local --environment=production` on your computer and copy the values into `~/app.env`. Vercel's own variables (`VERCEL_URL`, `VERCEL_ENV`) don't exist here; set `metadataBase` and any site URL yourself. - **Build settings.** The hook installs with your lockfile's package manager and runs your `build` script. If you changed the install or build command in Vercel's project settings or `vercel.json`, or have a `vercel-build` script, make `build` do the same, or edit the hook. - **`vercel.json`.** Crons become [timers](#cron-jobs). Move `redirects`, `rewrites`, and `headers` into `next.config.ts`. - **Storage.** Vercel Blob becomes files in `~/data`. Hosted databases from the Marketplace, such as Neon Postgres or Upstash Redis, keep working from here with the same URLs; or move the data onto the VM. - **Limits.** No function timeouts, cold starts, or 4.5 MB request cap. Server Actions still accept 1 MB bodies by default (raise `experimental.serverActions.bodySizeLimit` for uploads). - **What you no longer get.** A global CDN and edge regions: the app runs on one VM in one region. `@vercel/analytics` and `@vercel/speed-insights` only report on Vercel, so remove them. - **Domains and logs.** Domains are a CNAME away ([custom domains](/docs/cnames)), and logs are `journalctl -u app -f`. ISR, `next/image`, Server Actions, streaming, `after()`, and `proxy.ts` all work with `next start` without changes. ## 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-