Self-hosting Cap Web - Cap

Cap Web is our web application for uploading and sharing Caps - it's what runs right here on Cap.so. You can upload videos to it from the dashboard or from Cap Desktop.

Quick Start (One Command)

The fastest way to self-host Cap is with Docker Compose. This single command will start everything you need:

bash

git clone https://github.com/CapSoftware/Cap.git
cd Cap
docker compose up -d

That's it! Cap will be available at http://localhost:3000.

<Warning title="Security Notice for Production Deployments"> The default `docker-compose.yml` includes placeholder secrets for quick local testing. **If you're deploying to a public server or production environment**, you must change these values. See the [Production Checklist](#production-checklist) below. </Warning>

bash

docker compose logs cap-web

Deployment Options

Option 1: Docker Compose (Recommended)

Best for VPS, home servers, or any Docker-capable host.

What's included:

Cap Web application
Media server (FFmpeg processing)
MySQL database
MinIO (S3-compatible storage)

Steps:

Clone the repository
Run docker compose up -d
Access Cap at http://localhost:3000

Note: The main docker-compose.yml builds the media server from source, so a full clone of the repository is required. The Coolify compose file uses a pre-built image from ghcr.io instead.

Custom configuration:

Create a .env file to customize your deployment:

bash

# Public URL (required for production)
CAP_URL=https://cap.yourdomain.com

# S3 public URL (for video playback)
S3_PUBLIC_URL=https://s3.yourdomain.com

# Optional: Custom ports
CAP_PORT=3000
MINIO_PORT=9000

# Optional: Custom passwords (auto-generated if not set)
MYSQL_PASSWORD=your-secure-password
MINIO_ROOT_PASSWORD=your-minio-password

Option 2: Railway (One-Click)

Railway provides a fully managed deployment with automatic SSL and scaling. Login credentials appear in Railway's Deploy Logs after deployment.

Option 3: Coolify

For Coolify users, use docker-compose.coolify.yml which includes environment variable placeholders:

Create a new Docker Compose project in Coolify
Point to the Cap repository
Set compose file to docker-compose.coolify.yml
Configure environment variables in Coolify's UI
Deploy

Note: The Coolify compose file uses slightly different environment variable names: WEB_URL instead of CAP_URL, and S3_PUBLIC_ENDPOINT instead of S3_PUBLIC_URL.

Connecting Cap Desktop

Open Cap Desktop settings
Set 'Cap Server URL' to your deployment URL (e.g., https://cap.yourdomain.com)
Uploads will now go to your self-hosted instance

Email Configuration

By default, login links are printed to the server logs. To send emails:

Create an account at Resend

Add these environment variables:

bash

RESEND_API_KEY=re_xxxxx
RESEND_FROM_DOMAIN=yourdomain.com

Optional Features

AI Features

For video transcription and AI summaries:

bash

DEEPGRAM_API_KEY=your-key    # Transcription
GROQ_API_KEY=your-key        # AI summaries (preferred)
OPENAI_API_KEY=your-key      # AI summaries (fallback)

Google OAuth

bash

GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-secret

Production Checklist

<Warning title="Critical: Change Default Secrets Before Going Public"> The default `docker-compose.yml` contains **hardcoded placeholder secrets** that are visible in the public repository. Anyone who knows you're using Cap with defaults could potentially:

Forge authentication sessions (via NEXTAUTH_SECRET)
Decrypt sensitive database fields (via DATABASE_ENCRYPTION_KEY)
Spoof webhook requests (via MEDIA_SERVER_WEBHOOK_SECRET)

This is fine for local development or testing on a private network, but you must generate unique secrets before exposing Cap to the internet. </Warning>

Generate secure secrets:

bash

openssl rand -hex 32

Run this command three times to generate values for:

NEXTAUTH_SECRET
DATABASE_ENCRYPTION_KEY
MEDIA_SERVER_WEBHOOK_SECRET

Full production checklist:

Set secure passwords: MYSQL_PASSWORD, MINIO_ROOT_PASSWORD
Set secure secrets: DATABASE_ENCRYPTION_KEY, NEXTAUTH_SECRET, MEDIA_SERVER_WEBHOOK_SECRET
Set CAP_URL to your public URL
Set S3_PUBLIC_URL to your MinIO/S3 public URL
Configure a reverse proxy (nginx, Caddy, Traefik) with SSL
Set up email with Resend
Configure backups for MySQL and MinIO volumes

Architecture

┌─────────────────┐     ┌─────────────────┐
│   Cap Desktop   │────▶│    Cap Web      │
└─────────────────┘     │   (port 3000)   │
                        └────────┬────────┘
                                 │
                    ┌────────────┼────────────┐
                    ▼            ▼            ▼
             ┌──────────┐ ┌──────────┐ ┌──────────┐
             │  MySQL   │ │  MinIO   │ │  Media   │
             │ (3306)   │ │ (9000)   │ │  Server  │
             └──────────┘ └──────────┘ └──────────┘

Environment Variables Reference

See packages/env/server.ts for all available options.

Troubleshooting

Can't access Cap after starting:

bash

docker compose logs cap-web

Database migration issues:

bash

docker compose down -v  # Warning: deletes data
docker compose up -d

Reset everything:

bash

docker compose down -v
docker compose up -d

Support

If you encounter issues with self-hosting:

Open a GitHub issue
Check existing issues for solutions

We do not offer direct support for self-hosted deployments.