Deploy Next.js

This guide deploys a Next.js application, connects it to a managed PostgreSQL database, and covers the environment variable and multi instance details that trip people up. For the shared deploy flow, see Deploy from GitHub.

Prepare Your App

Standalone Output

Enable standalone output. It bundles only what the server needs and produces a server.js that reads PORT and HOSTNAME:

const nextConfig = { output: 'standalone' };
export default nextConfig;

Bind the Port

The standalone server honors environment variables, so set these as environment variables and run node server.js:

HOSTNAME=0.0.0.0
PORT=8080

Expose the same port in Networking. If you run next start instead of standalone, wrap it so $PORT expands, since the start command is a direct exec: sh -c "next start -H 0.0.0.0 -p $PORT".

Deploy

Create an application from your repository. Buildpacks runs next build, or use a Dockerfile. With standalone output, a Dockerfile must copy three paths into the runner, or static assets and the public folder return 404:

COPY --from=build /app/public ./public
COPY --from=build /app/.next/static ./.next/static
COPY --from=build /app/.next/standalone ./
CMD ["node", "server.js"]

Connect a Database

Create a managed PostgreSQL database and copy its connection string into a DATABASE_URL environment variable. Connections require SSL, so append ?sslmode=require. With Prisma:

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

Run Migrations

Out Plane has no pre deploy hook. Run npx prisma migrate deploy once from the browser terminal, or fold it into the start command:

sh -c "npx prisma migrate deploy && node server.js"

Environment Variables

The split between build time and runtime variables matters in Next.js.

Set NEXT_PUBLIC_* variables in a Build scope Environment Variable Group, and never put a secret in one. Set NEXT_TELEMETRY_DISABLED=1 to skip telemetry.

Production Notes

• next/image needs sharp on Linux. Install it with npm i sharp.
• Incremental static regeneration caches to local disk, which is per instance and reset on each deploy. The first requests after a deploy rebuild those pages.
• With more than one instance, set NEXT_SERVER_ACTIONS_ENCRYPTION_KEY (a base64 key) as a build variable so every instance shares it. Otherwise Server Actions fail with "Failed to find Server Action".
• Put runtime dependencies in dependencies, not devDependencies, or standalone output misses them.

Next Steps