Skip to main content
Developer Documentation

Self-Hosting
Guide

Deploy NXTG.AI on your own infrastructure using Docker, Vercel, or a bare Node.js server. This guide covers prerequisites, configuration, and production deployment.

Prerequisites

Before you begin, ensure you have the following tools installed and accounts configured.

Node.js 18+
LTS recommended. Check with node --version
pnpm 8+
Install via npm install -g pnpm
Git
Required for the git-based CMS workflow
Clerk account
Free tier available at clerk.com — needed for auth

Quick Start

Get a local development environment running in under five minutes.

1

Clone the repository

bash
git clone https://github.com/nxtg-ai/nxtg.ai.git
cd nxtg.ai
2

Install dependencies

bash
pnpm install
3

Configure environment

bash
cp .env.example .env.local
# Open .env.local and fill in your Clerk keys

At minimum, set NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY from your Clerk dashboard. See the environment configuration section for all variables.

4

Start the development server

bash
pnpm dev

The site will be available at http://localhost:3000.

Docker Deployment

Docker is the recommended approach for self-hosted production deployments. The multi-stage build produces a minimal image with only the runtime dependencies needed to serve the application.

Dockerfile

Dockerfile
FROM node:18-alpine AS deps
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN npm install -g pnpm && pnpm install --frozen-lockfile

FROM node:18-alpine AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm install -g pnpm && pnpm build

FROM node:18-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build /app/.next ./.next
COPY --from=build /app/public ./public
COPY --from=build /app/package.json ./package.json
COPY --from=build /app/node_modules ./node_modules
EXPOSE 3000
CMD ["node_modules/.bin/next", "start"]

docker-compose.yml

docker-compose.yml
services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=${NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY}
      - CLERK_SECRET_KEY=${CLERK_SECRET_KEY}
      - NEXT_PUBLIC_SITE_URL=${NEXT_PUBLIC_SITE_URL}
      - DATABASE_URL=${DATABASE_URL}
    depends_on:
      - postgres
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: nxtgai
      POSTGRES_USER: ${POSTGRES_USER:-nxtgai}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  postgres_data:

Build and run

bash
docker build -t nxtg-ai .
docker run -p 3000:3000 --env-file .env.local nxtg-ai

# Or with compose:
docker compose up -d

Environment Configuration

All configuration is managed through environment variables. Copy .env.example to .env.local for local development, or inject them directly in your deployment platform.

VariableDescriptionRequired
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEYClerk publishable key for client-side auth initializationRequired
CLERK_SECRET_KEYClerk secret key for server-side authenticationRequired
NEXT_PUBLIC_CLERK_SIGN_IN_URLPath to the sign-in pageRequired
NEXT_PUBLIC_CLERK_SIGN_UP_URLPath to the sign-up pageRequired
DATABASE_URLPostgreSQL connection string for persistent storageOptional
NEXT_PUBLIC_SITE_URLPublic-facing base URL of your deploymentOptional
GITHUB_TOKENGitHub personal access token for the git-based CMS workflowOptional
WAITLIST_WEBHOOK_URLWebhook endpoint for waitlist form submissionsOptional

Production Deployment

Vercel (Recommended)

Zero-configuration deployment with edge network

Vercel is the recommended deployment target. Import your repository, set environment variables in the dashboard under Settings → Environment Variables, and deploy. Vercel handles ISR, Edge Functions, and the Cross-Origin Isolation headers automatically.

Deploy to Vercel

Docker

Full control over your infrastructure

bash
docker build -t nxtg-ai .
docker run -p 3000:3000 \
  -e NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_... \
  -e CLERK_SECRET_KEY=sk_live_... \
  nxtg-ai

Node.js

Direct server deployment with PM2 or systemd

bash
pnpm build
pnpm start

# Or with PM2 for process management:
pm2 start pnpm --name "nxtg-ai" -- start

Troubleshooting

Common issues encountered when self-hosting and their solutions.

Clerk authentication fails on startup

Verify that NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY are both set in your environment. The publishable key must match the secret key — mixing keys from different Clerk applications will cause authentication failures. Check your Clerk dashboard for the correct key pair.

WebContainers fail to load in /os route

The /os route requires Cross-Origin Isolation (COOP/COEP headers) to use SharedArrayBuffer for WebContainers. These headers are configured in middleware.ts and are automatically applied to the /os route. If hosting behind a reverse proxy (nginx, Caddy), ensure the proxy passes these headers through and does not strip them.

pnpm install fails with frozen lockfile error

In CI environments, use pnpm install --frozen-lockfile to respect the lockfile exactly. If you intentionally updated dependencies, run pnpm install locally first, commit the updated pnpm-lock.yaml, then re-run CI. Never delete the lockfile to resolve conflicts — update it properly.

MDX content not appearing after changes

Content in src/content/ is processed by Velite at build time and output to .velite/. In development, Velite watches for changes automatically. In production, a fresh build is required after any content change. Run pnpm build to regenerate the .velite/ output. Ensure .velite/ is not gitignored in your production build environment.

Need deployment help?

Our team can assist with enterprise deployment architecture and configuration.

Contact Us