# Overlord
# [TELEGRAM SERVER JOIN NOW NO EXCUSES WE GIVE SUPPORT AND IT'S FUN](https://t.me/WindowsBatch)
Hello, I made this project for fun.
---
- [Quick Start (Docker)](#quick-start-docker)
- [Docker Install By OS](#docker-install-by-os)
- [No Docker (.bat / .sh)](#no-docker-bat--sh)
- [Production Package Scripts](#production-package-scripts)
- [Docker Notes (TLS, reverse proxy, cache)](#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:
```yaml
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:
```sh
docker compose up -d
```
3. Open the panel:
```text
https://localhost:5173
```
4. Update later:
```sh
docker compose pull
docker compose up -d
```
5. Stop:
```sh
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:
```powershell
winget install -e --id Docker.DockerDesktop
```
After install, start Docker Desktop once, then verify:
```powershell
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:
```powershell
docker compose -f docker-compose.windows.yml up -d
```
To rebuild after an update:
```powershell
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:
```bash
# 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 </fullchain.pem`
- key: `/etc/letsencrypt/live//privkey.pem`
- ca: `/etc/letsencrypt/live//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:
```sh
OVERLORD_TLS_OFFLOAD=true
OVERLORD_HEALTHCHECK_URL=http://localhost:5173/health
OVERLORD_PUBLISH_HOST=127.0.0.1
```
Then point ngrok at local HTTP:
```sh
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.