Learn how to deploy a Next.js application on Peon using Git, automated CI/CD, and Nixpacks. Connect your repository, configure builds, deploy on every push, and run your app on your own Linux server with a Vercel-like developer experience without cloud lock-in.
Deploying Next.js in a production environment requires more than a simple development server. This guide provides a comprehensive, step-by-step walkthrough for deploying a professional-grade Next.js stack—including frontend pages, API routes, and automated CI/CD—onto your own VPS using Peon and Nixpacks, without the need for a manual Dockerfile.
Overview of the Stack
By following this guide, you will set up the following components:
Prerequisites
Before beginning, ensure you have the following ready:
On your local machine:
Node.js 20+ (22 recommended) and a package manager (npm, pnpm, or yarn).
Git installed and a GitHub account.
OpenSSH client (ssh-keygen).
On Peon:
A Peon workspace (Cloud or self-hosted).
A DigitalOcean Droplet (or any Linux VPS) with at least 1 GB RAM.
Step 1 — Initialize Your Next.js Application
Bootstrap a new Next.js project using the App Router and navigate into the directory:
npx create-next-app@latest nextjs-peon
cd nextjs-peon
During setup, select Yes for TypeScript and App Router. To test the dual-capability of the service, update app/page.tsx for the UI and create an API route at app/api/hello/route.ts :
import { NextResponse } from "next/server";
export async function GET() {
return NextResponse.json({ status: "ok", message: "Hello from Peon" });
}
Step 2 — Create a GitHub Repo and Push
Create a new repository on GitHub named nextjs-peon .
Initialize Git locally and push to the main branch:
git init
git branch -M main
git add .
git commit -m "Initial Next.js application"
git remote add origin https://github.com/YOUR_USER/nextjs-peon.git
git push -u origin main
Step 3 — Provision a DigitalOcean Droplet and SSH key
Peon does not host your containers in its own cloud. It SSHs into your VPS, installs Docker, and runs your apps there. Create that machine first.
Generate an SSH key pair
On your laptop:
ssh-keygen -t ed25519 -C "peon-nextjs" -f ~/.ssh/peon_nextjs
Press Enter for an empty passphrase (or set one if you prefer).
Create the Droplet
In DigitalOcean → Create → Droplets.
Choose a region, image (Ubuntu LTS 22.04/24.04), and size (at least 1 GB RAM).
Authentication: SSH key → paste the public key from ~/.ssh/peon_nextjs.pub .
Create the Droplet and note its public IPv4 address.
Verify SSH from your laptop: ssh -i ~/.ssh/peon_nextjs root@YOUR_DROPLET_IP .
Step 4 — Configure SSH Authentication in Peon
Peon requires the private key to access your server:
Open Peon → sidebar Keys & Tokens .
Add a new SSH / private key.
Paste the full private key from ~/.ssh/peon_nextjs .
Important formatting note: The key must start with '-----BEGIN OPENSSH PRIVATE KEY-----' and end with '-----END OPENSSH PRIVATE KEY-----'. Keep the line breaks as in the file; do not add extra spaces, wrap the key in quotes, or paste only the middle lines.
Give the key a clear name (e.g., peon-nextjs-droplet ) and save.
Never commit this private key to GitHub. It lives only on your machine and in Peon’s encrypted key store.
Step 5 — Provision the Server in Peon
Open Servers → add / create a server.
Configure connection parameters:
a. Name: Descriptive ID (e.g., nextjs-peon).
b. IP / Hostname: Public IPv4 of the DigitalOcean Droplet.
c. Port : Default to 22
d. User: root.
e. SSH host key fingerprint : Optional; leave blank for automatic fingerprint recording upon first connection.
f. SSH key: The key you added in Step 4 .
g. Gateway type: Traefik.
Save and click Connect to server. Wait until the server status is Online.
Initiate the connection: Navigate to the server dashboard select 'Connect to server', and monitor the activity log until the validation process confirms the server status is 'Online'.
Step 6 — Connect GitHub to Peon
In the Peon dashboard, navigate to Git Sources .
Add a GitHub App connection and install it on the account or organization owning the nextjs-peon repository.
Grant the app access to the specific repository.
Step 7 — Create the Next.js Application Service
Add a New service of type Application (Git) using the following configuration:
Step 8 — Environment and Domain Configuration
Under the Environment tab, define the following variables:
NODE_ENV=production
PORT=3000
NIXPACKS_NODE_VERSION=22
Finally, add your domain in the Domains tab and point an A record to your server IP.
Step 9 — Deployment and CI/CD
Click Deploy on the service dashboard. Nixpacks will build your app and Traefik will provision HTTPS.
To enable push-to-deploy, go to Configuration → Advanced and toggle Auto deploy to ON.
git add .
git commit -m "Trigger Peon deploy"
git push origin main
Step 9 — Deployment and CI/CD
Click Deploy on the service dashboard. Nixpacks will build your app and Traefik will provision HTTPS.
To enable push-to-deploy, go to Configuration → Advanced and toggle Auto deploy to ON.
git add .
git commit -m "Trigger Peon deploy"
git push origin main
Step 10 — Final Smoke-Test
Verify your deployment:
UI Check: Visit your domain to see the homepage.
API Check: Visit /api/hello to confirm JSON response.
CD Loop: Push a commit and watch Peon trigger a rolling update.
Cheat Sheet
Top comments (0)