Docker on a VPS

Complete VPS deployment guide for Roost using docker-compose.yml.

This Docker path now includes Traefik + Let’s Encrypt SSL by default. Installer also applies Docker Engine 29+ API compatibility for Traefik automatically.

What This Covers

• Frontend + backend deployment on a VPS
• Built-in Traefik reverse proxy
• Automatic Let’s Encrypt SSL certificates
• Supabase Cloud or Supabase Self-hosted
• Optional Redis container profile
• Optional self-hosted MinIO profile for S3-compatible storage

Prerequisites

• Ubuntu/Debian VPS recommended (2 vCPU, 4GB RAM minimum)
• Domain pointed to your VPS public IP
• Ports 80 and 443 open in firewall/security group
• Git access to your Roost repository

Step 1: Clone and Run Installer

git clone https://github.com/msrbuilds/roost.git
cd roost
bash install.sh

When prompted:

1. Choose Docker (Self-hosted VPS) target.
2. Enter a real domain (not localhost).
3. Enter Let’s Encrypt email (required).
4. Choose database provider and optional services.
5. For S3-Compatible storage, choose:
   • Self-host MinIO on this VPS (auto profile), or
   • external provider (R2 / remote MinIO)

Installer generates:

• .env.local
• server/.env
• .env (Docker runtime env, including Traefik/SSL settings)
• Post-install validation output (domain, SSL email, compose config, Traefik API compatibility)

Step 2: Database Provider Paths

Supabase Cloud

• Choose Supabase Cloud in installer.
• Provide project URL, anon key, service role key.
• Run schema.sql in Supabase SQL Editor (or Supabase CLI).

Supabase Self-hosted

• Choose Supabase Self-hosted in installer.
• Provide your self-hosted Supabase URL.
• Choose Auto-generate JWT/anon/service keys (recommended) or enter existing keys manually.
• Use Supabase Self-Hosted Guide for Supabase stack setup.

MinIO (S3-Compatible, Self-hosted on this VPS)

If selected in installer:

• .env includes MinIO root credentials, bucket, and S3_ENDPOINT=https://your-domain.
• COMPOSE_PROFILES=minio is enabled.
• MinIO remains internal; the authenticated backend proxies authorized downloads.
• A minio-init job auto-creates private upload and backup buckets.

Step 3: Deploy

docker compose up -d --build

Check status:

docker compose ps
docker compose logs -f traefik
docker compose logs -f backend
docker compose logs -f frontend

Step 4: Verify SSL + Routing

curl https://your-domain.com/api/health
curl -I https://your-domain.com

Expected:

• Frontend served over HTTPS at root path
• Backend reachable at /api/* over same domain

Traffic Model

• Traefik listens on host ports 80 and 443.
• Frontend/backend are internal-only containers (not directly published to host).
• HTTP is redirected to HTTPS.

Updates

git pull
docker compose up -d --build

Troubleshooting

SSL certificate not issued

• Confirm DNS A record points to VPS public IP.
• Confirm ports 80/443 are open.
• Check logs: docker compose logs -f traefik

Traefik log: client version 1.24 is too old

This means Traefik cannot query your Docker socket API.

• Re-run installer once (latest installer auto-applies Docker API compatibility override):
  • bash install.sh
• Or pull latest repo changes and recreate:
  • git pull
  • docker compose up -d --force-recreate traefik
• Verify:
  • docker compose logs --tail=80 traefik

Containers fail due missing env values

• Re-run bash install.sh and choose Docker target again.
• Confirm .env exists in project root.

Redis connection errors

• Confirm .env has REDIS_URL=redis://redis:6379.
• Confirm .env has COMPOSE_PROFILES=redis.

MinIO upload or download fails

• Confirm .env has S3_ENDPOINT=https://your-domain.
• Confirm .env has COMPOSE_PROFILES including minio.
• Confirm the backend has matching MinIO credentials and PUBLIC_API_URL.
• Check MinIO init logs: docker compose logs -f minio-init.

CORS errors

• Ensure ALLOWED_ORIGINS and FRONTEND_URL in .env match your production domain.

Next Guides

• Dockploy (VPS)
• Netlify
• Vercel