Deploy a Next.js app with Postgres on your own server in 10 minutes

[thegdsks]

You have a Next.js app on GitHub and a cheap Linux server. This walkthrough takes you from a blank box to https://your-domain.com with a Postgres database attached, a build on every push, a health check that gates each release, and a rollback command for the day something breaks. There is no Dockerfile to write, no nginx config, and no certbot cron job. It comes down to one install command, one import command, and one domain.

Contents

• What you will have at the end
• How the path works
• Before you start
• Step 1: Install Levelrail
• Step 2: Let it read your repo
• Step 3: Create the app, the database and the first build
• Step 4: Set your env vars and secrets
• Step 5: Point your domain at it
• Step 6: Turn on push to deploy
• Logs and rollback
• Add Postgres to an app you already deployed
• Troubleshooting
• What to do next

What you will have at the end

• A Next.js app running in a container on your server, served over HTTPS with a certificate that renews itself
• A managed Postgres 16 database, connected to the app through an environment variable
• A build on every git push, using the Railpack builder when your repo has no Dockerfile
• A readiness check that has to pass before traffic moves to the new version
• Searchable logs from the CLI and the dashboard
• A one-command rollback to any earlier successful deploy

How the path works

flowchart LR
    A["git push"] --> B["Detect stack<br/>Next.js, port, env keys"]
    B --> C["Build<br/>Dockerfile or Railpack"]
    C --> D{"Health gate<br/>readiness probe"}
    D -->|passes| E["Traffic moves<br/>TLS domain"]
    D -->|fails| F["Old version<br/>keeps serving"]

Loading

The gate is the part to remember. A new container has to answer its readiness probe before it takes traffic. If it never does, the version that was already running keeps serving, and you get a structured reason for the failure instead of a blank 502.

Before you start

You need	Details
A Linux server	Ubuntu or Debian on amd64 or arm64, root access, curl. The installer warns below 1 GB of RAM, and 2 GB gives a Next.js build room. The preflight check requires 10 GB of free disk.
Open ports	80 and 443 free (for the web and certificates). The dashboard defaults to 8080.
A domain	Optional for a first run. An A record pointing at the server's public IP is enough when you are ready.
A GitHub repo	Any Next.js app. With no Dockerfile it builds with Railpack. If it has a Dockerfile, that wins.

Tip

No domain yet? The dashboard can issue a real Let's Encrypt certificate for a <dashed-ip>.sslip.io hostname with no DNS at all, so you can finish this whole tutorial before you buy one.

Step 1: Install Levelrail

SSH into the server and run the installer:

curl -fsSL https://levelrail.com/install.sh | sudo sh

It checks the machine first (root, architecture, systemd, Docker version, RAM, disk, ports), installs Docker if it is missing, downloads the release and verifies its SHA-256 checksum, installs levelrail-cli into /usr/local/bin, starts a levelrail systemd service, and waits for its health endpoint. When it finishes it prints your dashboard URL and a one-time setup token.

Open the http://<ip>:8080/login?setup=<token> link from the summary, create the admin account, and let the setup wizard run its server checks.

While you are here, copy master.key out of the data directory to somewhere safe. It encrypts every secret you store, and the installer reminds you to back it up for that reason.

Next, sign the CLI in. Set the control plane URL, then approve a short device code in the dashboard, the same flow as gh auth login:

export APP_API_URL=http://<ip>:8080
levelrail-cli auth login --device
levelrail-cli auth whoami

Credentials are saved to ~/.config/levelrail-cli/credentials. Add --profile NAME to keep several control planes side by side. For CI, create an API token under Settings, API tokens, and pass it with --token or APP_API_TOKEN. Everything below works from the dashboard too.

Then turn on HTTPS for the dashboard itself, from the Domains page or with the CLI:

levelrail-cli settings ingress https enable --email you@yourdomain.com

That gives the dashboard a <dashed-ip>.sslip.io address with a real certificate. If you want your own domain on it later, pick a dashboard-only subdomain such as console.example.com and keep your app's domain separate. Update APP_API_URL to the new https address afterwards.

Step 2: Let it read your repo

Before anything is created, ask Levelrail what it sees. This reads files through the GitHub API, clones nothing, and creates nothing:

levelrail-cli import https://github.com/OWNER/REPO --analyze --name shop

You get a table with these rows: Name, Stack, Build, Port, Health, Memory, Domain, Database and Env. For a Next.js repo with no Dockerfile, the interesting ones look like this:

Field	What you will see
Stack	Next.js, with the evidence "next dependency found, built with Railpack"
Build	railpack
Port	3000
Health	/
Memory	768 MiB

Every suggestion comes with its evidence, so you can tell a real finding from a guess.

What the detection looks at

Suggestion	Where it looks
Framework	package.json dependencies (also go.mod, requirements.txt, Gemfile and others)
Build type	Dockerfiles in the tree, then Railpack when there is none
Port	Dockerfile EXPOSE, a --port flag in your scripts, then the framework default
Health path	Dockerfile HEALTHCHECK, then the framework default
Env variable names	.env.example, .env.sample, .env.template, .env.dist, README tables
Database	DATABASE_URL, POSTGRES_* and similar names, plus driver dependencies

If your repo has a .env.example, the analysis lists the variable names it finds, flags the ones that look like secrets, and proposes a database. A repo that mentions POSTGRES_URL gets this suggestion:

Database  postgres 16 as shop-postgres -> POSTGRES_URL

Only names are read, never values. A required variable blocks the next step until you supply a value, which you can do inline with --env KEY=VALUE (repeat it for more than one).

Step 3: Create the app, the database and the first build

Happy with the plan? Run the same command with --apply, adding a value for anything the analysis marked as required:

levelrail-cli import https://github.com/OWNER/REPO --apply --name shop --env NEXTAUTH_SECRET=a-long-random-string

It creates the database, the app, the database connection and the repository link, then starts the first build. The last line looks like this:

app "shop" created with database(s) shop-postgres; build started (deploy attempt "dep_...")

Copy that dep_... id and follow the build:

levelrail-cli apps deploys logs shop dep_... --follow

Or block until the deploy finishes, which suits scripts:

levelrail-cli apps wait shop

apps wait exits 0 when the deploy converged (it prints rolled out), 5 when it converged as a failure, and 6 on timeout. The default timeout is 5 minutes.

Your readiness probe decides whether the deploy succeeds. If your app answers 200 on /, you are done. If you have a dedicated route, set it:

levelrail-cli apps health set shop --probe readiness --path /healthz

Prefer clicks? The New app page in the dashboard runs the same analysis and shows the same evidence, then a single Deploy button opens the live build log.

Step 4: Set your env vars and secrets

App env vars and secrets are injected when the container is created, not during next build. That matters for exactly one family of variables: NEXT_PUBLIC_* values are compiled into the browser bundle at build time. Commit them in a .env.production file in your repo (they end up in public JavaScript anyway) and next build picks them up, with Railpack or a Dockerfile. Everything else is read at runtime and is set as follows.

Kind	Where it lives	Command
Plain env vars	Stored with the app	levelrail-cli apps env import shop --file .env.production --apply
Secrets	Encrypted per app, values never returned	levelrail-cli apps secrets set shop NEXTAUTH_SECRET 'a-long-random-string' --apply
Database URL	Injected from the connection	Created for you in step 3

apps env import shows which keys are new, changed or unchanged, and skips keys that are already secrets. Add --dry-run to preview without saving, or --keep-existing to leave changed keys alone. --apply restarts the app so the running container picks up the change.

Tip

Bulk-load secrets from a file with levelrail-cli apps secrets set shop --env-file .env.secrets. Each key becomes its own encrypted secret.

Step 5: Point your domain at it

Create an A record for app.example.com pointing at the server's public IP. Then attach the domain and wait for it to go live:

levelrail-cli apps domains add shop app.example.com --wait

--wait prints each go-live step and polls for 2 minutes by default (change it with --timeout), exiting non-zero if the domain is not live by then. The certificate is requested and renewed for you, so there is no separate proxy to manage. If you have connected Cloudflare or Route53, apps domains add creates the DNS record too.

If DNS is still propagating, check what the control plane sees. The domain has to be attached to the app first, which is why the check comes second:

levelrail-cli domains check shop app.example.com

It does a real DNS lookup and reports connected, not_resolving, resolves_elsewhere or unconfigured.

To see every address the app answers on:

levelrail-cli apps urls shop

Step 6: Turn on push to deploy

--apply linked the repository and ran the first build. To have pushes trigger new builds, connect GitHub once in the dashboard (the GitHub App settings page), then register the repo as the app's source. That call also installs the push webhook. The --build-type flag matches what the analysis picked in step 2, since the default here is dockerfile:

levelrail-cli github-app use-as-source OWNER REPO --app-name shop --build-type railpack

From then on, pushes to the default branch deploy. Make a visible change, push it, and watch:

git commit -am "update the headline" && git push
levelrail-cli apps deploys list shop

Open a pull request and, with previews enabled, you also get a temporary environment per PR that is torn down when the PR closes. The previews page covers it.

Logs and rollback

Search the stored logs, or follow them live:

levelrail-cli apps logs shop --q "error" --since 1h --tail 100
levelrail-cli apps logs shop --follow

Check where the app stands:

levelrail-cli apps status shop

When a deploy goes wrong, list the history and send the app back to one that worked. Rollback redeploys that deploy's exact image, pinned by digest or by a rollback pin that image cleanup never removes, and brings back its env, health checks, replicas and resources. Secrets, domains and volumes stay as they are now. --watch follows it through the readiness gate:

levelrail-cli apps deploys list shop
levelrail-cli apps deploys rollback-to shop <deploy-id> --watch

If a deploy fails, read the structured reason instead of scrolling raw logs. Without an id it shows the newest attempt:

levelrail-cli apps deploys show shop

Add Postgres to an app you already deployed

Already running a Next.js app without a database? Create one and connect it:

levelrail-cli databases create --name shop-postgres --engine postgres --version 16
levelrail-cli apps connect shop shop-postgres --env-var DATABASE_URL
levelrail-cli apps connections list shop

apps connect injects the full connection string into the variable you name, at the app's next container start. Without --env-var it defaults to <DATABASE>_DATABASE_URL, so name it DATABASE_URL if that is what Prisma or Drizzle expects. The connections list also shows a reachability badge, so you can tell whether the app and database share a node. If you imported with --apply in step 3, this database already exists and is connected. Scheduled backups and restore are covered on the backups page.

Run migrations after a deploy

You can run a command in the app's running container and get its real exit code back:

levelrail-cli apps exec shop -- npx prisma migrate deploy

Swap in your own migration command. The command is a plain argv with no shell, so put -- before it when it takes flags.

Troubleshooting

What you see	Likely cause	What to do
Failure code port_not_listening	Next.js is bound to localhost, or the port is wrong	Bind 0.0.0.0 on the app port. The PORT env var is injected.
Failure code health_check_failed	The readiness path is slow or returns an error	Point the probe at a cheap route with apps health set, or raise --ready-timeout for a slow start.
Failure code compile_error	The build failed in next build	Read the excerpt in apps deploys show shop, fix it, and confirm next build passes locally.
Failure code build_out_of_memory	The build ran out of memory	Add RAM or swap, or build on a larger node.
Failure code missing_env	A required variable has no value	Set it with apps env import or apps secrets set, then redeploy.
Failure code oom_killed	The running container passed its memory limit	Raise the memory limit (768 MiB is the Next.js default).
Failure code dockerfile_error	A Dockerfile exists but is invalid, or a COPY source is not committed	Fix the Dockerfile, or set the build type to railpack with --build-type railpack.
NEXT_PUBLIC_ value is wrong in the browser	It is not in the build, since app env is only injected at container start	Commit it in .env.production and push a new build.
Domain will not go live	DNS has not propagated, or ports 80 and 443 are blocked	Run domains check, and open both ports in your firewall.
You are locked out after enabling HTTPS	Plain HTTP sign-in is refused once an https dashboard URL is set	Add APP_ALLOW_INSECURE_LOGIN=true through sudo systemctl edit levelrail temporarily.

The full list of failure codes

dockerfile_error, dependency_install_failed, compile_error, build_config_error, build_out_of_memory, build_timeout, image_pull_failed, port_not_listening, health_check_failed, container_crashed, oom_killed, missing_env, registry_push_failed, disk_full, docker_unreachable, freeze_window_hold, approval_pending, scan_gate_blocked, rollback_target_gone, and unknown. Each one has a cause and a suggested fix on the deploy failures page.

Rollbacks need the old image to still exist. If you ever see rollback_target_gone, the image was garbage collected: redeploy from source and raise the retained rollback image count so the next one is covered.

What to do next

• Let idle apps sleep to save memory: levelrail-cli apps sleep enable shop --after 30m
• Add per-PR preview environments
• Wire git integrations for GitLab, Bitbucket or Gitea
• Learn the domain options, from wildcard certificates to redirects, in Domains and ingress
• Moving off Vercel? Read the migration runbook
• Browse every command in the CLI reference

Try it, then tell us how it went

If this saved you an afternoon, a star on glincker/levelrail helps other people find it. Running a stack I did not cover, or hit a snag? Reply in this thread with your framework and what the analysis step printed. I read every one, and the real repos people bring here shape what detection learns next.