Deploy guides

How to deploy a Next.js app on Stackap

To deploy a Next.js app on Stackap you create a project, set your environment variables, and push; the server generates the Dockerfile, builds, checks health and goes live over HTTPS.

Before you start

This guide takes a Next.js app from a local repository to a live domain. It assumes you already have a Stackap server and an access token, which today means being invited, because Stackap is in early access.

The shortest version is two commands once the project exists: set variables, then deploy. The rest of this page is what to check so the first build succeeds.

Check these in your Next.js project

• package.json lists next, and has build and start scripts.
• A lockfile is committed. A stale lockfile makes npm ci fail, so run an install and commit the result.
• Every variable the browser needs starts with NEXT_PUBLIC_. They are baked in during the build.
• No page needs a real secret while the site is statically generated, because the build sees placeholders for everything that is not public.
• If you use remote images, the hosts are listed in the Next.js config.

What to watch while it builds

A large Next.js build is the heaviest thing the server does. One 31,592-page site takes about 96 seconds and peaks near 2.8 GB of memory, so expect the build log, not the site, to be the slow part.

Read the build log first with --source build. If the build passes and the app still does not go live, switch to --source runtime, which shows what the container printed when it tried to start.

When it does not go live

Build fails at install

Almost always a stale lockfile. Regenerate it locally, commit, and push again.

Build passes, health check fails

The app did not answer on the expected port or path. Check the runtime log for a crash and confirm the app reads PORT.

Pages show placeholder data

A page read a non-public variable at build time and saw the placeholder. Fetch that data at request time instead.

Images do not load

The remote image host is missing from the Next.js config.

Steps

1. Get access, a token and an SSH key. Ask for an invitation at the contact page. You will be given the API address of the server and a token that is shown once. Keep it in a password manager. Pushing uses SSH, so the public key you push with must also be registered with your organization, which an owner token can do through POST /v1/ssh-keys, or the operator can do for you.
2. Log in and create the project. Log in once, then create a project for the app.

   $ stackap login --url https://api.<your-domain> --token-stdin
   $ stackap create my-next-app --name "My Next App"

3. Prepare the repository. Add the project's Stackap remote next to your existing one, and make sure the branch you intend to ship is the project's production branch. Only that branch triggers a build.
4. Set environment variables. Set public variables first, because they are fixed at build time, then secrets. Each value is read from standard input so it never appears in a shell history.

   $ stackap env set my-next-app NEXT_PUBLIC_SITE_URL --stdin
   $ stackap env set my-next-app SESSION_SECRET --stdin

5. Push. Deploy. Stackap generates the Dockerfile, builds, starts the container beside the old one, checks health, then switches.

   $ stackap deploy my-next-app
   $ stackap logs my-next-app --source build

6. Point your domain at it. Add the hostname. Stackap checks that DNS points at the server before it issues a certificate, so create the record at your DNS provider first.

   $ stackap domains add my-next-app www.example.com

Early-access scope

• No preview deployments, so test a branch locally or on a second project before it reaches production.
• Non-public variables are placeholders at build time, so build-time data fetching with secrets does not work.
• The domain step needs a DNS edit that you make by hand at your DNS provider.

Questions

Last updated 2026-10-03.