Deployment

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 or Hetzner (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

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=localhost
DB_PORT=5432
DB_NAME=db_name

# 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 -nb admin your-secure-password

3. Copy the output to TRAEFIK_AUTH_USERS secret To generate user and hash, run command and enter your password echo $(htpasswd -nB user) | sed -e s/\\$/\\$\\$/g copy user:hash and add into your secret, for example user:$$2y$$05$$0m9M5goxIdsbkjd3TfPA/eYbsI84Er0.2YGj6iFPevXu/wP7E8fpe then, login using user:password (not hash)

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

Manual Deployment

If you need to deploy manually:

1. SSH to your VPS:

   ssh root@your-vps-ip

2. Login to GitHub Container Registry:

   echo "your_ghcr_token" | docker login ghcr.io -u your_github_username --password-stdin

3. Pull and run the latest image:

   docker pull ghcr.io/your_username/golivekit:latest
   docker compose -f docker-compose-prod.yml down
   docker compose -f docker-compose-prod.yml up -d

Post-Deployment

Access Your Application

• Main site: https://yourdomain.com
• Traefik dashboard: https://traefik.yourdomain.com (protected by basic auth)

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.

Troubleshooting

Common Issues

1. Domain not resolving: Check DNS configuration
2. SSL certificate issues: Verify domain points to VPS and ports 80/443 are open
3. Application not starting: Check environment variables and logs
4. 502 Bad Gateway: Usually indicates the application container is not running

Useful Commands

# Check container status
docker ps

# View application logs
docker logs golivekit

# Restart the application
docker compose -f docker-compose-prod.yml restart nextjs

# Check Traefik configuration
docker logs traefik

# Test SSL certificate
curl -I https://yourdomain.com

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: ~239 MB

Traefik dashboard: https://traefik.yourdomain.com