Your First Deployment

Learn how to deploy your first Next.js application with NextDeploy in just a few steps.

Prerequisites

Make sure you have:

  • ✓NextDeploy CLI installed
  • ✓A Next.js project ready to deploy
  • A Linux VPS (Ubuntu/Debian) or AWS Account
  • ✓A VPS with SSH access
  • ✓Doppler account for secrets (optional)

Step-by-Step Guide

Step 1: Initialize Your Project

cd your-nextjs-project
nextdeploy init

This creates:

  • • nextdeploy.yml - Primary configuration
  • • .nextdeploy/ - Auto-generated route metadata cache

Step 2: Configure Your Deployment

Edit nextdeploy.yml for your target environment:

For AWS Serverless:

version: 1.0
target_type: "serverless"
serverless:
  provider: "aws"
  region: "us-east-1"
  s3_bucket: "my-nextjs-assets"

For Linux VPS:

version: 1.0
target_type: "vps"
servers:
  - host: 192.168.1.100
    ssh_key: "~/.ssh/id_rsa"

Step 3: Server Preparation (VPS Only)

nextdeploy prepare

NextDeploy will securely connect to your server, install dependencies, and configure the background daemon automatically.

Step 4: Continuous Integration (Zero-Touch)

nextdeploy generate-ci

This generates a GitHub Actions workflow. Add your secrets to GitHub and NextDeploy handles everything on Git Push.

Step 5: Deploy Manually

nextdeploy build
nextdeploy deploy

The CLI analyzes your Route Plan and executes a Zero-Downtime port swap (VPS) or S3 static synchronization (AWS).

Step 6: Instant Rollbacks

nextdeploy rollback

Because NextDeploy uses a Symlink architecture on VPS targets, rollbacks occur instantly without rebuilds.

What Happens During Deployment

  1. Project analyzed to determine Next.js Output Mode
  2. VPS: Bundle transferred, extracted to isolated release directory
  3. VPS: Dynamic port allocated, Next.js server booted via systemd
  4. VPS: Symlink updated to point to new release
  5. VPS: Caddy config dynamically rewritten and reloaded without dropping traffic
  6. AWS: Static assets intelligently pushed to S3/CloudFront
  7. AWS: Lambda Web Adapter attached for Next.js SSR backend

Common Issues

SSH Connection Failed

Make sure your SSH key is properly configured:

ssh -i ~/.ssh/id_rsa deploy@192.0.2.123

Port Already in Use

If port 3000 is already in use, change it in nextdeploy.yml:

app:
  port: 8080

Next Steps

PreviousSecret Management
NextCLI Reference