Deploying a Next.js App on Gigalixir

A Next.js app deploys on Gigalixir with three file changes and a git push. Free TLS, managed PostgreSQL, and zero forced restarts are included with no extra configuration.

Gigalixir is known for Elixir and Phoenix, but the underlying platform runs any app with a standard Heroku-compatible buildpack. Node.js and Next.js are fully supported. The same production features that Elixir teams depend on — zero-downtime deploys, no daily restarts, second-by-second billing, and managed PostgreSQL — apply to Next.js apps without modification.

What the Platform Handles Automatically

Before touching configuration, here is what Gigalixir provides without any setup:

• Free TLS certificates via Let's Encrypt, managed and renewed automatically
• Zero-downtime deploys with no forced daily restarts
• Managed PostgreSQL with HA and read replica options
• Per-second billing — scaling up for a 2-hour spike and scaling back down charges only for those 2 hours
• SSH access on Standard Tier
• AWS and GCP regions available in the US and Europe

Gigalixir sees this regularly in support: Node.js developers come for a Heroku alternative and stay because the billing model and restart behavior are more predictable for long-running server processes.

The Three Files That Make It Work

A standard Next.js project needs three changes to deploy on Gigalixir. No application code changes required.

1. .buildpacks

Create a .buildpacks file at the project root:

https://github.com/heroku/heroku-buildpack-nodejs

Gigalixir reads this file during the build phase. Without it, the platform looks for an Elixir release. This one line tells it to use the Heroku Node.js buildpack instead.

2. Procfile

Create a Procfile at the project root:

web: npm run start

Only the web process type is scaled by Gigalixir. Background workers typically run as a separate app or are handled within the same Node.js process.

3. package.json — PORT binding and Node version

Gigalixir injects a PORT environment variable and the app must listen on it. The platform uses port 4000. Update the start script and pin the Node.js version:

{
  "scripts": {
    "start": "next start -p ${PORT:-3000}"
  },
  "engines": {
    "node": ">=20.x"
  }
}

The ${PORT:-3000} fallback keeps the app working locally on port 3000 when PORT is not set. Hardcoding port 3000 or 8080 is the most common reason a Next.js app fails its health check on Gigalixir.

Deploying Step by Step

1. Install the CLI and log in

pip3 install gigalixir
gigalixir login

2. Create the app

gigalixir apps:create -n your-app-name

This creates the app and sets the gigalixir git remote on the local repo automatically. To choose a cloud provider and region, add --cloud gcp or --cloud aws and --region us-east-1 (or europe-west1 for EU). The default is GCP in us-central1.

3. Create a PostgreSQL database

gigalixir pg:create --size=0.6

Wait about 20 seconds, then retrieve the connection string:

gigalixir pg

Gigalixir sets DATABASE_URL automatically when a database is provisioned. A standard Node.js PostgreSQL client reads it directly:

const { Pool } = require('pg');
const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  ssl: { rejectUnauthorized: false }
});

4. Set environment variables

gigalixir config:set NODE_ENV=production YOUR_SECRET_KEY=your-secret-here

Environment variables are injected at runtime and never baked into the slug. Gigalixir restarts the app automatically when config vars change.

5. Deploy

git add .
git commit -m "configure for gigalixir"
git push gigalixir main

Only the main or master branch builds. Pushes to other branches are ignored.

The build log streams to the terminal. The buildpack installs Node.js, runs npm install, runs npm run build (Next.js compiles here), strips devDependencies, packages the slug, and deploys. Total build time is approximately 2 minutes, mostly the Next.js compile step.

6. Scale the app

gigalixir ps:scale --replicas=1 --size=0.5

A size 0.5 replica has 500MB of memory and costs $25/month at full utilization on Standard Tier. A size 1.0 replica (1GB) costs $50/month. Billing is prorated to the second.

One Gotcha: Health Checks and Startup Time

Gigalixir starts HTTP health checks on port 4000 immediately when the pod launches. Next.js takes 1–2 seconds to initialize, so a brief "Unhealthy" status appears in gigalixir ps right after deploy. It resolves on its own once the app is ready. This is normal behavior for any non-Elixir runtime where the process takes a moment to start — not an error.

Free Tier Limitations Before Going to Production

The Free Tier runs one replica at size 0.5 with no credit card required. It is appropriate for testing and prototyping only.

• No SSH access
• No database backups
• Free Tier database limited to 10k rows and 2 connections; idle connections terminated after 5 minutes
• App scales to 0 replicas after 30 days without a deploy (warning email sent at 23 days)

Standard Tier removes all of these constraints.

Static IPs, Long-Lived WebSockets, and Custom Domains

Static IPs are available on Enterprise plans only. Standard Tier apps do not have static outbound IPs. For third-party services that require IP allowlisting, route outbound traffic through QuotaGuard Static, a proxy that provides dedicated static IPs without requiring an Enterprise plan.

Long-lived WebSocket connections: Gigalixir runs on Kubernetes with nginx as the ingress layer. Nginx reloads happen under normal Kubernetes operation. Connections open at the time of a reload are dropped after 60 minutes. Client-side reconnection logic handles this cleanly.

Custom domains are a single command:

gigalixir domains:add www.example.com

TLS is provisioned and renewed automatically. No configuration needed.

Next.js on Gigalixir Is Three Files and One Push

The complete diff from a standard Next.js project: a .buildpacks file, a Procfile, and two additions to package.json. No application code changes. The platform handles TLS, zero-downtime deploys, managed PostgreSQL, and billing from there.

Full pricing is at gigalixir.com/pricing. Questions about Enterprise plans, static IPs, or dedicated ingress can be directed to the contact page.