overlord/README.md

Overlord

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

Hello, I made this project for fun.

It is written using a combination of Typescript + Node.JS for tue server and GOLang for the client.
Connections are done via encrypted websockets to connect to the server from the client.
You need to use docker to get this to run easier/for quicker deployment.

---

• 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.

⚠️ The compose file below is for Linux ONLY. If you are on Windows or macOS, use docker-compose.windows.yml instead. See Docker Install By OS for the correct commands.

Installation instructions for Linux

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

services:
  overlord-server:
    image: ${DOCKER_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
    network_mode: host
    environment:
      PORT: ${PORT:-5173}
      HOST: ${HOST:-0.0.0.0}
      OVERLORD_USER: ${OVERLORD_USER:-admin}
      OVERLORD_PASS: ${OVERLORD_PASS:-}
      JWT_SECRET: ${JWT_SECRET:-}
      OVERLORD_AGENT_TOKEN: ${OVERLORD_AGENT_TOKEN:-}
      NODE_ENV: ${NODE_ENV:-production}
      OVERLORD_TLS_CERT: ${OVERLORD_TLS_CERT:-/app/certs/server.crt}
      OVERLORD_TLS_KEY: ${OVERLORD_TLS_KEY:-/app/certs/server.key}
      OVERLORD_TLS_CA: ${OVERLORD_TLS_CA:-}
      OVERLORD_TLS_OFFLOAD: ${OVERLORD_TLS_OFFLOAD:-false}
      OVERLORD_AUTH_COOKIE_SECURE: ${OVERLORD_AUTH_COOKIE_SECURE:-auto}
      OVERLORD_TLS_CERTBOT_ENABLED: ${OVERLORD_TLS_CERTBOT_ENABLED:-false}
      OVERLORD_TLS_CERTBOT_LIVE_PATH: ${OVERLORD_TLS_CERTBOT_LIVE_PATH:-/etc/letsencrypt/live}
      OVERLORD_TLS_CERTBOT_DOMAIN: ${OVERLORD_TLS_CERTBOT_DOMAIN:-}
      OVERLORD_TLS_CERTBOT_CERT_FILE: ${OVERLORD_TLS_CERTBOT_CERT_FILE:-fullchain.pem}
      OVERLORD_TLS_CERTBOT_KEY_FILE: ${OVERLORD_TLS_CERTBOT_KEY_FILE:-privkey.pem}
      OVERLORD_TLS_CERTBOT_CA_FILE: ${OVERLORD_TLS_CERTBOT_CA_FILE:-chain.pem}
      OVERLORD_CLIENT_BUILD_CACHE_DIR: ${OVERLORD_CLIENT_BUILD_CACHE_DIR:-/app/client-build-cache}
      OVERLORD_FILE_UPLOAD_INTENT_TTL_MS: ${OVERLORD_FILE_UPLOAD_INTENT_TTL_MS:-1800000}
      OVERLORD_FILE_UPLOAD_PULL_TTL_MS: ${OVERLORD_FILE_UPLOAD_PULL_TTL_MS:-1800000}
    volumes:
      - overlord-data:/app/data
      - overlord-certs:/app/certs
      - overlord-client-build-cache:/app/client-build-cache
      - overlord-plugins:/app/plugins
    restart: unless-stopped
    init: true
    security_opt:
      - no-new-privileges:true
    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

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

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

Installation instructions for 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

Installation instructions for Mac

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

macOS users: use docker-compose.windows.yml instead of the default docker-compose.yml. The Windows/macOS compose file is pre-configured for Docker Desktop (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

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

Script instructions for Windows

Development mode (starts server + client):

start-dev.bat

Production mode (build + run server executable):

start-prod.bat

Build client binaries (adds client builds to the build queue):

build-clients.bat

---

Linux / macOS

Installation instructions for Linux / Mac

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)

Here we will store some notes for you to read depending on what it is. Configs, work arounds etc.

---

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.