Deployment Guide

docsblog-app supports multiple deployment platforms. Choose the one that best fits your needs:

Common Setup

Regardless of which platform you choose, complete these steps first:

Environment Variables

Copy .env.example to .env and configure the core variables:

NEXT_PUBLIC_SITE_URL=https://your-domain.com
NEXT_PUBLIC_BASE_URL=https://your-domain.com
ENABLE_ADMIN=false

Tip: The admin panel is for local development only. Set ENABLE_ADMIN to false in production.

Local Build Verification

pnpm install
pnpm build

Verify the build succeeds before proceeding with platform deployment.

Cloudflare Workers

Deploy to Cloudflare Workers using the OpenNext adapter, with ISR incremental static regeneration and KV caching.

1. Create a Cloudflare Account

1. Sign up at dash.cloudflare.com/sign-up (free tier works)
2. Note your Account ID (visible on the dashboard home page)

2. Create an API Token

1. Go to API Tokens management
2. Click Create Token → select Edit Cloudflare Workers template
3. Confirm permissions: Account - Workers Scripts - Edit, Account - Workers KV Storage - Edit
4. Create and copy the token (shown only once)

3. Create a KV Namespace

npx wrangler kv namespace create NEXT_INC_CACHE_KV

Note the id from the output.

4. Configure wrangler.jsonc

Fill in the KV ID and production domain:

{
  "kv_namespaces": [
    {
      "binding": "NEXT_INC_CACHE_KV",
      "id": "<your-kv-namespace-id>"
    }
  ],
  "env": {
    "production": {
      "vars": {
        "NEXT_PUBLIC_SITE_URL": "https://your-domain.com",
        "NEXT_PUBLIC_BASE_URL": "https://your-domain.com",
        "ENABLE_ADMIN": "false"
      },
      "kv_namespaces": [
        {
          "binding": "NEXT_INC_CACHE_KV",
          "id": "<your-kv-namespace-id>"
        }
      ]
    }
  }
}

5. Deploy

# One-command build + deploy
pnpm run deploy:cf

Build pipeline: aggregate → next build → opennextjs-cloudflare build → wrangler deploy

6. Verify

curl -sI https://your-domain.com | grep x-nextjs-cache
# Expected: x-nextjs-cache: HIT (served from cache)

7. Custom Domain

Go to Cloudflare Dashboard → Workers & Pages → your Worker → Settings → Domains & Routes → Add Domain.

Worker Custom Domains bypass the CDN cache layer. Caching is handled entirely by the KV mechanism.

8. GitHub Actions Auto-Deploy

The project supports automatic deployment when pushing to the main branch. Configure in your GitHub repo:

Create an environment named CLOUDFLARE-DocsBlog-Prod (matches deploy.yml), then push to main to trigger auto-deploy.

For detailed configuration, see docs/deploy-cloudflare.md.

Vercel

Vercel is the official hosting platform for Next.js — zero configuration required.

1. Import Project

1. Log in to the Vercel Dashboard
2. Click Add New → Project
3. Select your Git repository
4. Framework Preset: Next.js (usually auto-detected)
5. Click Deploy

2. Configure Environment Variables

In Vercel Dashboard → Project → Settings → Environment Variables:

NEXT_PUBLIC_ variables are injected at build time. Changes require redeployment.

3. Auto-Deploy

Once connected to a Git repo, every push to main triggers automatic deployment:

git push → Vercel builds (next build) → Deploy → Done

4. Caching

Vercel natively supports Next.js ISR with no extra configuration:

• Set revalidate in pages to enable ISR
• Static pages are automatically cached on the Vercel Edge Network

5. Custom Domain

Dashboard → Project → Settings → Domains → Add your domain. Vercel auto-provisions SSL certificates.

6. Verify

curl -sI https://your-domain.com/ | grep -i x-vercel-cache

Notes

• wrangler.jsonc and open-next.config.ts are Cloudflare-specific files — Vercel ignores them automatically
• Vercel Hobby (free) limits: 100GB bandwidth/month, 6000 build minutes/month

For detailed configuration, see docs/deploy-vercel.md.

Node.js Self-Host

Run with a standard Node.js server — suitable for VPS, cloud servers, intranet deployments, etc.

1. Prerequisites

• Node.js 18+ (20 LTS recommended)
• pnpm package manager

2. Build & Start

pnpm install
pnpm build
pnpm start:node

# Specify a custom port
PORT=8080 pnpm start:node

3. Process Management (PM2)

npm install -g pm2
pm2 start pnpm --name docsblog -- start:node
pm2 startup && pm2 save

4. Reverse Proxy

Nginx

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:3005;
        proxy_http_version 1.1;
        proxy_set_header Upgrade {'$http_upgrade'};
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host {'$host'};
        proxy_set_header X-Real-IP {'$remote_addr'};
        proxy_set_header X-Forwarded-For {'$proxy_add_x_forwarded_for'};
        proxy_set_header X-Forwarded-Proto {'$scheme'};
        proxy_cache_bypass {'$http_upgrade'};
    }
}

Caddy

your-domain.com {
    reverse_proxy 127.0.0.1:3005
}

Caddy automatically provisions and renews SSL certificates.

5. Caching

Node.js deployment uses Next.js default filesystem caching:

• ISR pages cached in .next/cache/ directory
• No KV or Redis configuration needed

Notes

• wrangler.jsonc and open-next.config.ts are Cloudflare-specific files — just ignore them
• For HTTPS, configure through the reverse proxy (Nginx/Caddy), not at the Next.js layer

For detailed configuration, see docs/deploy-node.md.

Troubleshooting

Platform Comparison