Deploy a Next.js App in 5 Minutes

This tutorial walks through deploying a Next.js application from a GitHub repo to Vardo, end to end.

Prerequisites

• A running Vardo instance (installation guide)
• A GitHub account with a repo containing a Next.js app
• A domain pointed at your server (or a subdomain of your Vardo base domain)

Step 1: Connect GitHub

Vardo deploys from GitHub repos using a GitHub App. If you skipped this during the setup wizard, configure it now:

1. Go to Settings → Integrations → GitHub
2. Click Create GitHub App — this opens GitHub with the app manifest pre-filled
3. Click Create GitHub App on the GitHub page
4. You'll be redirected back to Vardo with the credentials saved automatically

Once connected, Vardo can read repos the app has been granted access to and receive push webhooks for automatic deployments.

Step 2: Create a Project

Projects are groupings of related apps (think: a product or client).

1. Go to Projects in the sidebar
2. Click New Project
3. Give it a name — for example, my-app
4. Click Create

Step 3: Create an App from a GitHub Repo

1. Inside your project, click New App
2. Choose GitHub as the source
3. Search for and select your repository
4. Select the branch to deploy from (usually main)
5. Choose a deploy type:

Build options:

• Dockerfile — if your repo has a Dockerfile, Vardo uses it directly
• Nixpacks — auto-detects Node.js and builds without a Dockerfile. Handles pnpm install, pnpm build, and starts the app on port 3000.
• Railpacks — alternative buildpack with faster builds

For a standard Next.js app without a Dockerfile, Nixpacks is the easiest option — it detects your package manager and framework automatically.

6. Click Create App

Step 4: Configure Environment Variables

Before deploying, add any environment variables your app needs:

1. Open the app detail page
2. Click the Environment tab
3. Add key/value pairs — for example:

   DATABASE_URL=postgresql://...
   NEXTAUTH_SECRET=...
   NEXTAUTH_URL=https://my-app.example.com

4. Click Save

Environment variables are encrypted at rest and injected into the container at runtime.

Step 5: Deploy

1. Click Deploy on the app detail page
2. Watch the build log in real time — Vardo pulls the repo, builds the image, and starts the container
3. When the status changes to Running, the app is live

A typical Next.js deploy takes 2-5 minutes depending on your server specs and the app's build time.

Automatic deployments: Vardo sets up a webhook on your repo automatically. Every push to the configured branch triggers a new deploy.

Step 6: Add a Custom Domain

By default, Vardo assigns a subdomain under your base domain (e.g., my-app.example.com). To use a custom domain:

1. Go to the app's Domains tab
2. Click Add Domain
3. Enter your custom domain (e.g., app.mycompany.com)
4. Add a DNS record at your registrar:

   CNAME  app.mycompany.com  →  host.example.com

   Or if your DNS provider requires an A record, point it directly to your server IP
5. Click Verify — Vardo checks DNS and provisions a Let's Encrypt certificate automatically
6. Once verified, the domain is live with HTTPS

What Just Happened

Here's what Vardo does under the hood when you deploy:

1. Clone — pulls the repo at the selected commit SHA
2. Build — runs docker build using your Dockerfile or Nixpacks
3. Deploy — starts the new containers in the inactive blue-green slot
4. Health check — waits for the new containers to become healthy (up to 60 seconds)
5. Route — Traefik discovers the new containers and routes traffic to them
6. Cleanup — tears down the old slot

Zero-downtime: the old slot keeps serving traffic until the new one passes health checks. If the new slot fails, the old one stays up.

Common Errors and Fixes

Build fails: pnpm: command not found

Your Dockerfile doesn't have pnpm installed. Add this before the install step:

RUN npm install -g pnpm

Or use a base image that includes it.

Container starts but immediately exits

Check the logs tab. Common causes:

• Missing environment variable (e.g., DATABASE_URL not set)
• App listening on wrong port — Vardo expects port 3000; make sure your Next.js server uses PORT=3000 or the Compose template sets it
• Build artifact missing — ensure your Dockerfile copies the .next directory

Domain shows "Invalid certificate"

DNS hasn't propagated yet. Wait a few minutes and click Verify again. Let's Encrypt certificate provisioning happens automatically once DNS resolves.

Webhook not triggering deploys

Go to your GitHub repo → Settings → Webhooks and check the recent deliveries. If the webhook is failing, re-save the GitHub integration in Vardo (Settings → Integrations → GitHub) to regenerate the secret.

Next Steps

• Set up automatic backups for your app's database
• Add health monitoring under Metrics in the sidebar
• Configure email notifications for deploy failures under Settings → Notifications