Deploy to VPS (Hetzner, Digital Ocean, EC2, etc.) via Docker

This guide provides step-by-step instructions for deploying the GoLiveKit application using GitHub Actions, Docker, and Traefik on a VPS.

Prerequisites

1. VPS Setup

Choose either Digital Ocean, Hetzner, or EC2 (or any VPS provider):

Digital Ocean Setup

1. Create a droplet with SSH access
2. SSH to your server: ssh root@your-server-ip
3. Install Docker:

   curl -fsSL https://get.docker.com | sudo bash

4. Verify Docker installation:

   sudo systemctl status docker

   Expected output: Active: active (running)

Hetzner Setup

• Follow similar steps as Digital Ocean
• Ensure Docker is installed and running

2. Domain Configuration

1. Purchase a domain name
2. Point your domain's DNS A record to your VPS IP address
3. Ensure both yourdomain.com and www.yourdomain.com point to your VPS

GitHub Repository Setup

1. Enable GitHub Container Registry

1. Go to your GitHub repository
2. Navigate to Settings → Actions → General
3. Under Workflow permissions, select Read and write permissions

2. Generate GitHub Container Registry Token

1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Generate a new token with these permissions:
   • write:packages
   • read:packages
   • delete:packages
3. Copy the token (you'll need it for GHCR_TOKEN secret)

3. Configure Repository Secrets

Go to your repository Settings → Secrets and variables → Actions and add these secrets:

Required Secrets

Environment Variables

[!IMPORTANT] If your app and Postgres run in Docker Compose, set DB_HOST to the Postgres service name (usually postgres), not localhost. Inside containers, localhost points to the same container and causes Prisma P1001 errors. For internal Docker network connections without Postgres TLS enabled, use DB_SSLMODE=disable.

Create your ENV_KEYS secret with all the environment variables your application needs. Example structure:

NEXT_PUBLIC_BASE_HOST=https://yourdomain.com
NEXT_PUBLIC_BRAND_NAME=GoLiveKit

# DB connection
DB_USER=db_user
DB_PASS=db_pass
DB_HOST=postgres
DB_PORT=5432
DB_NAME=db_name
DB_SSLMODE=disable

# Auth providers
BETTER_AUTH_SECRET="auth_secret"
BETTER_AUTH_URL=https://yourdomain.com
GOOGLE_CLIENT_ID=google_client_id
GOOGLE_CLIENT_SECRET=google_client_secret

# Email SMTP config
EMAIL_SERVER_USER=your_email@domain.com
EMAIL_SERVER_PASSWORD=your_email_password
EMAIL_SERVER_HOST=smtp.gmail.com
EMAIL_SERVER_PORT=465
EMAIL_FROM=Your Name from GoLiveKit<your_email@domain.com>

# Payments
## Stripe
STRIPE_SECRET_KEY=sk_test_your_stripe_secret_key
STRIPE_PUBLISHABLE_KEY=pk_test_your_stripe_publishable_key

# Notifications
NOTIFICATION_PROVIDER=telegram
TELEGRAM_CHANNEL_ID=your_telegram_channel_id
TELEGRAM_BOT_TOKEN=your_telegram_bot_token

SSH Key Setup

1. On your local machine, generate SSH key pair:

   ssh-keygen -t rsa -b 4096 -C "your-email@example.com"

2. Copy public key to your VPS:

   ssh-copy-id root@your-vps-ip

3. Copy the private key content to the VPS_SSH_KEY GitHub secret:

   cat ~/.ssh/id_rsa

Traefik Authentication

Generate basic auth credentials for Traefik dashboard:

1. Install htpasswd (usually comes with Apache):

   # Ubuntu/Debian
   sudo apt-get install apache2-utils
   
   # macOS
   brew install httpd

2. Generate auth string:

   htpasswd -nbB YOUR_USER YOUR_PASSWORD

3. Replace YOUR_USER and YOUR_PASSWORD with real credentials you will actually use to log in.

   Example:

   htpasswd -nbB bobby 12345abc

4. Copy the full output (for example user:$2y$...) to the TRAEFIK_AUTH_USERS secret exactly as-is.

   Do not wrap it in quotes and do not manually escape $.

5. Use that same username/password to log in to all services protected by traefik-auth middleware (Traefik dashboard, Dozzle, Adminer).

Deployment Process

Automatic Deployment

The application automatically deploys when you push to the master branch:

1. Linting: Code is linted for quality checks
2. Build: Docker image is built and pushed to GitHub Container Registry
3. Deploy: Application is deployed to your VPS with:
   • SSL certificates via Let's Encrypt
   • Automatic HTTP to HTTPS redirects
   • WWW to non-WWW redirects
   • Traefik reverse proxy setup

Post-Deployment

Access Your Application

• Main site: https://yourdomain.com
• Traefik dashboard: https://traefik.yourdomain.com (protected by basic auth)
• Dozzle (Docker logs UI): https://dozzle.yourdomain.com (protected by basic auth)
• Adminer (DB UI): https://adminer.yourdomain.com (protected by basic auth)

Protected services use the credentials generated with htpasswd and stored in TRAEFIK_AUTH_USERS.

Monitoring and Maintenance

1. Check application logs:

   docker logs golivekit

2. Check Traefik logs:

   docker logs traefik

3. Monitor disk usage:

   docker system df

4. Clean up old images (done automatically in CI/CD):

   docker system prune -af

SSL Certificate Renewal

Let's Encrypt certificates are automatically renewed by Traefik. No manual intervention required.

Security Considerations

1. Keep secrets secure: Never commit secrets to your repository
2. Regular updates: Keep Docker images and VPS updated
3. Firewall: Configure firewall to only allow necessary ports (22, 80, 443)
4. SSH security: Use key-based authentication, disable password login
5. Traefik dashboard: Always protect with strong basic auth credentials

Architecture Overview

The deployment consists of:

• Next.js Application: Main application container
• Traefik: Reverse proxy with automatic SSL
• GitHub Actions: CI/CD pipeline
• GitHub Container Registry: Docker image storage

Docker image size: ~556 MB