Self-Hosting

SSL & Domain Setup

Secure your Kokomo server with HTTPS and configure a custom domain.

SSL is Required

Kokomo clients require HTTPS connections for security. WebSocket connections also need WSS (secure WebSocket) to work properly on most platforms.

Option 1: Caddy (Recommended)

Caddy automatically obtains and renews SSL certificates from Let's Encrypt.

docker-compose.yml (add Caddy service)

services:
  caddy:
    image: caddy:2-alpine
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
      - caddy_config:/config
    depends_on:
      - kokomo-server

volumes:
  caddy_data:
  caddy_config:

Caddyfile

kokomo.yourdomain.com {
    # Reverse proxy to Kokomo server
    reverse_proxy kokomo-server:8080

    # Enable compression
    encode gzip

    # Security headers
    header {
        X-Content-Type-Options nosniff
        X-Frame-Options DENY
        Referrer-Policy strict-origin-when-cross-origin
    }
}

Setup Steps:

Point your domain's DNS A record to your server's IP
Create the Caddyfile in your Kokomo directory
Update KOKOMO_HOST in .env to your domain
Run docker compose up -d
Caddy will automatically obtain SSL certificates

Option 2: Nginx + Let's Encrypt

Traditional setup with Nginx reverse proxy and Certbot for certificates.

Install Certbot

# Ubuntu/Debian
sudo apt install certbot python3-certbot-nginx

# Get certificate
sudo certbot --nginx -d kokomo.yourdomain.com

/etc/nginx/sites-available/kokomo

server {
    listen 80;
    server_name kokomo.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name kokomo.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/kokomo.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/kokomo.yourdomain.com/privkey.pem;

    # SSL settings
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;

    # Proxy settings
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket timeout
        proxy_read_timeout 86400;
    }
}

Enable site and restart

sudo ln -s /etc/nginx/sites-available/kokomo /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

Option 3: Cloudflare Tunnel

Expose your server without opening ports using Cloudflare Tunnel.

docker-compose.yml (add cloudflared)

services:
  cloudflared:
    image: cloudflare/cloudflared:latest
    restart: always
    command: tunnel --no-autoupdate run
    environment:
      - TUNNEL_TOKEN=your-tunnel-token
    depends_on:
      - kokomo-server

Setup Steps:

Create a Cloudflare Tunnel in the Zero Trust dashboard
Configure the tunnel to point to http://kokomo-server:8080
Copy the tunnel token to your docker-compose.yml
Run docker compose up -d

Update Configuration

After setting up SSL, update your environment:

.env

# Update host to your domain
KOKOMO_HOST=kokomo.yourdomain.com

# If using a reverse proxy, you may need:
TRUST_PROXY=true

Verify Setup

Test HTTPS

# Check SSL certificate
curl -I https://kokomo.yourdomain.com/health

# Test WebSocket (should connect without error)
wscat -c wss://kokomo.yourdomain.com/ws

Your server is now accessible via HTTPS! Clients can connect securely.

Database Setup Connect Clients