VPS Deployment & Go Sidecar
Deploying to a Linux VPS gives you bare-metal speed, complete ownership of your infrastructure, and predictable $4–$20/month hosting costs without compute markup.
Architecture on VPS
When targeting a VPS, NextDeploy orchestrates three core components:
- Caddy Reverse Proxy: Handles automatic Let's Encrypt TLS certificate generation, HTTP/2 and HTTP/3 termination, and direct streaming of static files (
/_next/static/*andpublic/*) from NVMe disk. nextdeploydDaemon: A lightweight Go agent installed on your VPS that manages atomic releases, process supervision via systemd, and dual-stage health probing.- Optional Go Sidecar (
gosidecar): An in-memory Go reverse proxy that sits between Caddy and Node.js to serve prerendered RSC payloads and execute image transformations at native machine speed.
Incoming Request (:443)
│
▼
┌───────────┐ Static File
│ Caddy ├──────────────────────────► Disk: /var/www/.../shared_static
└─────┬─────┘
│ Dynamic / SSR
▼
┌──────────────────────────────────────┐
│ Go Sidecar (:3001) │
│ ┌────────────────────────────────┐ │
│ │ Prerendered HTML / RSC Cache │ │
│ └────────────────┬───────────────┘ │
│ │ Cache Miss │
│ ▼ │
│ ┌────────────────────────────────┐ │
│ │ Image Transcoding Engine │ │
│ └────────────────┬───────────────┘ │
└───────────────────┼──────────────────┘
│ Dynamic SSR / API / Actions
▼
┌─────────────────────┐
│ Next.js Node Server │
│ (:3000) │
└─────────────────────┘Step-by-Step Setup
1. Configure SSH Access
Ensure your local machine can connect to your VPS with SSH key authentication:
ssh -i ~/.ssh/id_ed25519 ubuntu@203.0.113.10Verify that the remote user has sudo access if automatic dependency provisioning is required.
2. Prepare the Server (prepare)
Run the automated preparation command to bootstrap your server:
nextdeploy prepareThis command connects via SSH and:
- Installs and configures Caddy with systemd integration.
- Configures Linux kernel cgroups v2 memory sandboxing.
- Installs the matching version of
nextdeployd. - Sets up deployment directory structures (
/var/www/apps/<app-name>).
3. Configure nextdeploy.yml
In your Next.js project root, ensure target_type is set to vps:
version: "1.0"
target_type: vps
app:
name: my-store
domain: store.example.com
port: 3000
gosidecar:
enabled: true
image_optimization: true
isr_cache: true
deployment:
server:
host: 203.0.113.10
user: ubuntu
ssh_key: ~/.ssh/id_ed25519
use_sudo: true
healthcheck:
path: /api/health
timeout: 5s4. Deploy (ship)
Ship your app:
nextdeploy shipNextDeploy will:
- Build your Next.js standalone application locally.
- Synchronize static assets to the cumulative
shared_staticpool. - Rsync server runtime files to
/var/www/apps/<app>/releases/<timestamp>. - Spawn the new Node.js instance on an isolated port.
- Perform dual-stage TCP + HTTP health probing.
- Atomically flip the
currentsymlink. - Gracefully drain and terminate the previous release.
Enabling the Go Sidecar
The Go sidecar is designed specifically for high-traffic Next.js apps. It intercepts requests before they hit Node.js:
- Static Pages & RSC: Serves
.rscand.htmldirectly from memory or disk cache in sub-millisecond latency. - Image Optimization: Bypasses Node.js image processing completely. Uses Go concurrency to transcode WebP/AVIF images.
- Zero Configuration: Enable it in
nextdeploy.yml:
app:
gosidecar:
enabled: true
image_optimization: true
isr_cache: true
max_image_workers: 4Upgrading the VPS Daemon
When updating your local nextdeploy CLI, upgrade the remote server agent with:
nextdeploy upgrade-daemon