VPS (Generic)

This guide works on any Linux VPS with Docker installed. Tested on Ubuntu 22.04+ and Debian 12+.

Prerequisites

• A VPS with at least 1 GB RAM and Docker installed
• A domain pointing to your VPS IP (optional but recommended for TLS)
• SSH access

1. Install Docker

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# Log out and back in, then verify:
docker --version

2. Run WCP

docker run -d \
  --name wcp \
  --restart unless-stopped \
  -p 8000:8000 \
  -v wcp_data:/data \
  -e WCP_DB_PATH=/data/sync.db \
  -e WCP_CONFIG_PATH=/data/config.json \
  -e WCP_CORS_ORIGINS=https://your-dashboard.example.com \
  ghcr.io/lucasmella-stack/wcp:latest

Verify it’s running:

curl http://localhost:8000/health
# {"status":"ok","version":"0.1.0"}

3. Add TLS with Caddy (Recommended)

Caddy provides automatic HTTPS with zero configuration.

# Install Caddy
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update && sudo apt install caddy

Create /etc/caddy/Caddyfile:

wcp.yourdomain.com {
    reverse_proxy localhost:8000
}

dashboard.yourdomain.com {
    root * /var/www/wcp-dashboard
    file_server
    try_files {path} /index.html
}

sudo systemctl reload caddy

Caddy automatically provisions Let’s Encrypt certificates.

4. Deploy the Dashboard

# On your local machine, build the dashboard
cd dashboard
VITE_API_URL=https://wcp.yourdomain.com npm run build

# Upload to the VPS
scp -r dist/* user@your-vps:/var/www/wcp-dashboard/

5. Firewall

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 22/tcp
sudo ufw enable

6. Updates

docker pull ghcr.io/lucasmella-stack/wcp:latest
docker stop wcp && docker rm wcp
# Re-run the docker run command from step 2

Or use Watchtower for automatic updates:

docker run -d --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower --interval 3600 wcp

Alternative: Docker Compose

Create docker-compose.yml:

services:
  wcp:
    image: ghcr.io/lucasmella-stack/wcp:latest
    restart: unless-stopped
    ports:
      - "8000:8000"
    volumes:
      - wcp_data:/data
    environment:
      - WCP_DB_PATH=/data/sync.db
      - WCP_CONFIG_PATH=/data/config.json
      - WCP_CORS_ORIGINS=https://your-dashboard.example.com

volumes:
  wcp_data:

docker compose up -d