Deployment

A VPS (Virtual Private Server) is the most cost-effective way to deploy a Grit application. You get full control over the server, and a $5-10/month VPS can handle thousands of users.

After provisioning your VPS with Ubuntu 22.04+ (recommended), SSH in as root and set up a non-root user with sudo access.

2a. SSH into your server

2b. Create a deploy user

Running everything as root is a security risk. Create a dedicated deploy user:

2c. Update packages and set timezone

Docker is the only dependency you need on the server. Install Docker Engine and Docker Compose:

Clone your project to the server and set up production environment variables. We recommend /opt/myapp as the deployment directory.

Production .env

Update these critical values for production. Never use default credentials in production:

APP_ENV=production
APP_PORT=8080

# Database — change password!
DATABASE_URL=postgres://grit:YOUR_STRONG_DB_PASSWORD@postgres:5432/myapp?sslmode=disable
POSTGRES_USER=grit
POSTGRES_PASSWORD=YOUR_STRONG_DB_PASSWORD
POSTGRES_DB=myapp

# Auth — generate a random 64-char secret
# openssl rand -hex 32
JWT_SECRET=GENERATE_A_RANDOM_64_CHAR_STRING

# Redis
REDIS_URL=redis://redis:6379

# Frontend URLs (update with your domains)
WEB_URL=https://yourdomain.com
ADMIN_URL=https://admin.yourdomain.com
CORS_ORIGINS=https://yourdomain.com,https://admin.yourdomain.com

# Storage (Cloudflare R2 recommended for production)
STORAGE_DRIVER=r2
R2_ENDPOINT=https://your-account.r2.cloudflarestorage.com
R2_ACCESS_KEY=your-access-key
R2_SECRET_KEY=your-secret-key
R2_BUCKET=myapp-uploads

# Email
RESEND_API_KEY=re_your_api_key
MAIL_FROM=noreply@yourdomain.com

# AI (optional)
AI_PROVIDER=claude
AI_API_KEY=sk-ant-xxxxx
AI_MODEL=claude-sonnet-4-5-20250929

# Disable GORM Studio in production
GORM_STUDIO_ENABLED=false

Environment Variables Reference

Grit includes a production-ready docker-compose.prod.yml that builds optimized containers for the Go API and Next.js apps, plus PostgreSQL and Redis.

Expected output: you should see all containers running (api, web, admin, postgres, redis). The first build may take a few minutes as Docker builds the Go binary and Next.js apps.

What the production build does

View logs

Caddy is a modern web server that automatically provisions SSL certificates from Let's Encrypt. It's the easiest way to get HTTPS working.

6a. Install Caddy

6b. Configure the Caddyfile

Before editing, make sure your DNS A records point to your server's IP address. Caddy will automatically obtain SSL certificates once DNS is configured.

# Go API
api.yourdomain.com {
    reverse_proxy localhost:8080
}

# Next.js Web App
yourdomain.com {
    reverse_proxy localhost:3000
}

# Admin Panel
admin.yourdomain.com {
    reverse_proxy localhost:3001
}

6c. Start Caddy

Caddy will automatically obtain and renew SSL certificates from Let's Encrypt. After a few seconds, your site will be live at https://yourdomain.com.

DNS Records

Add these DNS A records at your domain registrar or Cloudflare:

Lock down your server to only expose the ports you need. UFW (Uncomplicated Firewall) makes this simple:

This blocks all inbound traffic except SSH (22), HTTP (80), and HTTPS (443). Database (5432) and Redis (6379) ports are only accessible from within Docker's network.

Automate deployments so that every push to main deploys to production. Here's a GitHub Actions workflow that SSHs into your server and redeploys:

name: Deploy to VPS

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy via SSH
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.VPS_HOST }}
          username: deploy
          key: ${{ secrets.VPS_SSH_KEY }}
          script: |
            cd /opt/myapp
            git pull origin main
            docker compose -f docker-compose.prod.yml up -d --build
            docker image prune -f

Set up GitHub Secrets

In your GitHub repo, go to Settings → Secrets → Actions and add:

Always back up your production database. Losing data is irreversible.

Manual backup

Automated daily backups (cron)

Set up a cron job to backup daily and keep the last 7 days:

# Daily DB backup at 3 AM, keep last 7 days
0 3 * * * cd /opt/myapp && docker compose -f docker-compose.prod.yml exec -T postgres pg_dump -U grit myapp | gzip > /backups/myapp-$(date +\%Y\%m\%d).sql.gz && find /backups -name "myapp-*.sql.gz" -mtime +7 -delete

Managed database backups

If you use a managed PostgreSQL service (DigitalOcean Managed Databases, Supabase, Neon, etc.), backups are handled automatically. This is the recommended approach for important production workloads.

Grit's Go API includes a built-in request logger middleware. For production, add proper monitoring to catch issues before your users do:

To update your running application with minimal downtime, use Docker's rolling update capability:

Docker Compose detects which services have changed and only rebuilds and restarts those. PostgreSQL and Redis keep running throughout. The typical downtime for an API update is under 5 seconds.

Before going live, make sure you have completed these steps: