Overlord

TELEGRAM SERVER JOIN NOW NO EXCUSES WE GIVE SUPPORT AND IT'S FUN

Hello, I made this project for fun.

---

• Quick Start (Docker)
• Docker Install By OS
• No Docker (.bat / .sh)
• Production Package Scripts
• Docker Notes (TLS, reverse proxy, cache)

---

Quick Start (Docker)

If you just want it running fast, use this.

1. Create a docker-compose.yml file and paste this:

services:
  overlord-server:
    image: ghcr.io/vxaboveground/overlord:latest
    build:
      context: .
      dockerfile: Dockerfile
      cache_from:
        - type=local,src=.docker-cache/buildx
      cache_to:
        - type=local,dest=.docker-cache/buildx,mode=max
    container_name: overlord-server
    ports:
      - "5173:5173"
    environment:
      - OVERLORD_USER=admin
      - OVERLORD_PASS=
      - JWT_SECRET=
      - OVERLORD_AGENT_TOKEN=
      - PORT=5173
      - HOST=0.0.0.0
      - OVERLORD_TLS_CERT=/app/certs/server.crt
      - OVERLORD_TLS_KEY=/app/certs/server.key
      - OVERLORD_TLS_CA=
      - OVERLORD_TLS_OFFLOAD=false
      - OVERLORD_AUTH_COOKIE_SECURE=auto
      - OVERLORD_TLS_CERTBOT_ENABLED=false
      - OVERLORD_TLS_CERTBOT_LIVE_PATH=/etc/letsencrypt/live
      - OVERLORD_TLS_CERTBOT_DOMAIN=
      - OVERLORD_TLS_CERTBOT_CERT_FILE=fullchain.pem
      - OVERLORD_TLS_CERTBOT_KEY_FILE=privkey.pem
      - OVERLORD_TLS_CERTBOT_CA_FILE=chain.pem
      - OVERLORD_CLIENT_BUILD_CACHE_DIR=/app/client-build-cache
      - OVERLORD_FILE_UPLOAD_INTENT_TTL_MS=1800000
      - OVERLORD_FILE_UPLOAD_PULL_TTL_MS=1800000
    volumes:
      - overlord-data:/app/data
      - overlord-certs:/app/certs
      - overlord-client-build-cache:/app/client-build-cache
    restart: unless-stopped
    networks:
      - overlord-network
    healthcheck:
      test: ["CMD-SHELL", "curl -f ${OVERLORD_HEALTHCHECK_URL:-https://localhost:5173/health} >/dev/null 2>&1 || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

networks:
  overlord-network:
    driver: bridge

volumes:
  overlord-data:
  overlord-certs:
  overlord-client-build-cache:

2. Start it:

docker compose up -d

3. Open the panel:

https://localhost:5173

4. Update later:

docker compose pull
docker compose up -d

5. Stop:

docker compose down

First startup generates secrets and stores them in data/save.json (inside container: /app/data/save.json). Keep that file private and backed up.

Default bootstrap login is admin / admin unless you set OVERLORD_USER and OVERLORD_PASS.

Docker Install By OS

Windows

Install Docker Desktop (includes Docker Compose):

• https://docs.docker.com/desktop/setup/install/windows-install/

or with winget:

winget install -e --id Docker.DockerDesktop

After install, start Docker Desktop once, then verify:

docker --version
docker compose version

Windows users: use docker-compose.windows.yml instead of the default docker-compose.yml. The Windows compose file is pre-configured for Docker Desktop on Windows (no network_mode: host, correct volume paths, etc.).

Clone the repo or download the files, then run:

docker compose -f docker-compose.windows.yml up -d

To rebuild after an update:

docker compose -f docker-compose.windows.yml up --build -d

Linux (Debian, official apt repo method)

Official docs:

• https://docs.docker.com/engine/install/debian/

Set up Docker's apt repository:

# Add Docker's official GPG key:
sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/debian
Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
Components: stable
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update

If you use a derivative distro (for example Kali), you may need to replace:

(. /etc/os-release && echo "$VERSION_CODENAME")

with the matching Debian codename (for example bookworm).

Install latest Docker packages:

sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Verify service status:

sudo systemctl status docker

If your system does not auto-start Docker:

sudo systemctl start docker

Optional (run Docker without sudo):

sudo usermod -aG docker $USER
newgrp docker

Verify CLI:

docker --version
docker compose version

macOS

Install Docker Desktop:

• https://docs.docker.com/desktop/setup/install/mac-install/

or with Homebrew:

brew install --cask docker

Start Docker Desktop once, then verify:

docker --version
docker compose version

No Docker (.bat / .sh)

If you do not want Docker, use the included scripts.

Prerequisites for local (non-Docker) runs:

• Bun in PATH
• Go 1.21+ in PATH

Windows

Development mode (starts server + client):

start-dev.bat

Production mode (build + run server executable):

start-prod.bat

Build client binaries:

build-clients.bat

Linux / macOS

Make scripts executable once:

chmod +x start-dev.sh start-dev-server.sh start-dev-client.sh start-prod.sh build-prod-package.sh

Development mode (starts server in background + client in foreground):

./start-dev.sh

Only server:

./start-dev.sh server

Only client:

./start-dev.sh client

Production mode:

./start-prod.sh

Production Package Scripts

Build a production-ready package where the server can still build client binaries at runtime.

Windows:

build-prod-package.bat

Linux/macOS:

./build-prod-package.sh

Package output:

• Windows script: release
• Linux/macOS script: release/prod-package

Docker Notes (TLS, reverse proxy, cache)

BuildKit cache for faster rebuilds

docker-compose.yml includes build.cache_from and build.cache_to using .docker-cache/buildx.

Rebuild:

docker compose up --build -d

Runtime client build cache

The compose setup uses a persistent volume for runtime client builds:

• volume: overlord-client-build-cache
• mount: /app/client-build-cache
• env: OVERLORD_CLIENT_BUILD_CACHE_DIR (default /app/client-build-cache)

Certbot TLS

To use certbot certificates in production Docker:

• Set OVERLORD_TLS_CERTBOT_ENABLED=true
• Set OVERLORD_TLS_CERTBOT_DOMAIN=your-domain.com
• Mount letsencrypt into container read-only (example: /etc/letsencrypt:/etc/letsencrypt:ro)

Default cert paths:

• cert: /etc/letsencrypt/live/<domain>/fullchain.pem
• key: /etc/letsencrypt/live/<domain>/privkey.pem
• ca: /etc/letsencrypt/live/<domain>/chain.pem

Override with:

• OVERLORD_TLS_CERTBOT_LIVE_PATH
• OVERLORD_TLS_CERTBOT_CERT_FILE
• OVERLORD_TLS_CERTBOT_KEY_FILE
• OVERLORD_TLS_CERTBOT_CA_FILE

Reverse proxy TLS offload (Render, etc.)

If your platform terminates TLS before traffic reaches Overlord, set:

• OVERLORD_TLS_OFFLOAD=true
• OVERLORD_HEALTHCHECK_URL=http://localhost:5173/health
• OVERLORD_PUBLISH_HOST=127.0.0.1 (recommended for local proxies like ngrok)

When enabled:

• container serves internal HTTP on 0.0.0.0:$PORT
• external URL remains https://... through your platform proxy
• health checks should use http://localhost:$PORT/health inside the container
• do not expose internal container HTTP port directly to the internet

For ngrok/local reverse proxy use, a common setup is:

OVERLORD_TLS_OFFLOAD=true
OVERLORD_HEALTHCHECK_URL=http://localhost:5173/health
OVERLORD_PUBLISH_HOST=127.0.0.1

Then point ngrok at local HTTP:

ngrok http http://127.0.0.1:5173

Notes:

• Keep HOST=0.0.0.0 inside the container. Limiting exposure should be done with publish binding (OVERLORD_PUBLISH_HOST), not server bind host.
• If your .env secret/password includes $, escape as $$ to avoid Docker Compose variable-expansion warnings.