vxaboveground/overlord
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

better readme

Browse Source
This commit is contained in:
KingKDot
2026-05-07 21:06:09 -05:00
parent 6433f3b989
commit 6a0d10843e
1 changed files with 185 additions and 237 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+185 -237
View File
@@ -1,5 +1,5 @@
<p align="center"> <p align="center">
<img src="https://raw.githubusercontent.com/vxaboveground/Overlord/refs/heads/main/Overlord-Server/public/assets/overlord.png" alt="Overlord" /> <img src="https://raw.githubusercontent.com/vxaboveground/Overlord/refs/heads/main/Overlord-Server/public/assets/overlord.png" alt="Overlord" width="280" />
</p> </p>
# Overlord # Overlord
@@ -8,14 +8,16 @@
Hello, I made this project for fun. Hello, I made this project for fun.
It is written using a combination of Typescript + Node.JS for the server and GOLang for the client. <br> The server is TypeScript on Node/Bun. The client is Go. Operators talk to the server through a web panel or the Electron desktop app, and agents connect over encrypted WebSockets.
Connections are done via encrypted websockets to connect to the server from the client. <br>
You need to use docker to get this to run easier/for quicker deployment. <br> Docker is the easiest way to run it.
--- ---
- [Quick Start (Docker)](#quick-start-docker) - [Quick Start (Docker)](#quick-start-docker)
- [Docker Install By OS](#docker-install-by-os) - [Windows](#windows)
- [Linux](#linux)
- [macOS](#macos)
- [No Docker (.bat / .sh)](#no-docker-bat--sh) - [No Docker (.bat / .sh)](#no-docker-bat--sh)
- [Production Package Scripts](#production-package-scripts) - [Production Package Scripts](#production-package-scripts)
- [Docker Notes (TLS, reverse proxy, cache)](#docker-notes-tls-reverse-proxy-cache) - [Docker Notes (TLS, reverse proxy, cache)](#docker-notes-tls-reverse-proxy-cache)
@@ -24,161 +26,95 @@ You need to use docker to get this to run easier/for quicker deployment. <br>
## Quick Start (Docker) ## Quick Start (Docker)
If you just want it running fast, use this. Pick your OS below. Each section is self-contained: install Docker, get the project, start it.
> **⚠️ 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](#docker-install-by-os) for the correct commands. > Windows and macOS use `docker-compose.windows.yml`. Linux uses the default `docker-compose.yml` (host networking).
<details> After the first start, open `https://localhost:5173`. Default login is `admin` / `admin` unless you set `OVERLORD_USER` / `OVERLORD_PASS`. First startup writes generated secrets to `data/save.json` (inside the container: `/app/data/save.json`) — keep that file private and back it up.
<summary>Installation instructions for Linux</summary> ---
1. Create a `docker-compose.yml` file and paste this:
```yaml
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:
```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`.
</details>
## Docker Install By OS
### Windows ### Windows
<details> <details>
<summary>Installation instructions for Windows</summary> <summary>Step-by-step: Windows</summary>
<br> <br>
Install Docker Desktop (includes Docker Compose):
**1. Install Docker Desktop**
Either from the website:
- https://docs.docker.com/desktop/setup/install/windows-install/ - https://docs.docker.com/desktop/setup/install/windows-install/
or with winget: Or with winget:
```powershell ```powershell
winget install -e --id Docker.DockerDesktop winget install -e --id Docker.DockerDesktop
``` ```
After install, start Docker Desktop once, then verify: Start Docker Desktop once, then verify:
```powershell ```powershell
docker --version docker --version
docker compose 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.). **2. Get the project**
Clone the repo or download the files, then run: ```powershell
git clone https://github.com/vxaboveground/Overlord.git
cd Overlord
```
**3. Start it**
```powershell ```powershell
docker compose -f docker-compose.windows.yml up -d docker compose -f docker-compose.windows.yml up -d
``` ```
To rebuild after an update: **4. Open the panel**
```powershell ```text
docker compose -f docker-compose.windows.yml up --build -d https://localhost:5173
``` ```
### Linux (Debian, official apt repo method) **5. Update later**
Official docs: ```powershell
docker compose -f docker-compose.windows.yml down
docker compose -f docker-compose.windows.yml pull
docker compose -f docker-compose.windows.yml up -d
```
- https://docs.docker.com/engine/install/debian/ **6. Stop**
```powershell
docker compose -f docker-compose.windows.yml down
```
</details>
---
### Linux
<details>
<summary>Step-by-step: Linux (Debian / Ubuntu / Kali)</summary>
<br>
**1. Install Docker**
Official docs: https://docs.docker.com/engine/install/debian/
Set up Docker's apt repository: Set up Docker's apt repository:
```bash ```bash
# Add Docker's official GPG key:
sudo apt update sudo apt update
sudo apt install -y ca-certificates curl sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings 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 curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /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 sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb Types: deb
URIs: https://download.docker.com/linux/debian URIs: https://download.docker.com/linux/debian
@@ -190,60 +126,101 @@ EOF
sudo apt update sudo apt update
``` ```
If you use a derivative distro (for example Kali), you may need to replace: On a derivative distro (e.g. Kali), replace the codename expansion with the matching Debian codename, e.g. `bookworm`.
```bash Install Docker:
(. /etc/os-release && echo "$VERSION_CODENAME")
```
with the matching Debian codename (for example `bookworm`).
Install latest Docker packages:
```bash ```bash
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
``` ```
Verify service status: Make sure the daemon is running:
```bash
sudo systemctl status docker
```
If your system does not auto-start Docker:
```bash ```bash
sudo systemctl start docker sudo systemctl start docker
``` ```
Optional (run Docker without sudo): Optional — run Docker without sudo:
```bash ```bash
sudo usermod -aG docker $USER sudo usermod -aG docker $USER
newgrp docker newgrp docker
``` ```
Verify CLI: Verify:
```bash ```bash
docker --version docker --version
docker compose version docker compose version
``` ```
**2. Grab the compose file**
Make a folder for it, drop in the file, and you're done:
```bash
mkdir overlord && cd overlord
wget https://raw.githubusercontent.com/vxaboveground/Overlord/refs/heads/main/docker-compose.yml
```
No `wget`? Use `curl`:
```bash
mkdir overlord && cd overlord
curl -O https://raw.githubusercontent.com/vxaboveground/Overlord/refs/heads/main/docker-compose.yml
```
**3. Start it**
```bash
docker compose up -d
```
The image is pulled automatically from `ghcr.io/vxaboveground/overlord:latest` on first run.
**4. Open the panel**
```text
https://localhost:5173
or
https://IP:5173
```
**5. Update later**
From the same folder:
```bash
docker compose down
docker compose pull
docker compose up -d
```
**6. Stop**
```bash
docker compose down
```
</details> </details>
---
### macOS ### macOS
<details> <details>
<summary>Installation instructions for Mac</summary> <summary>Step-by-step: macOS</summary>
<br> <br>
Install Docker Desktop: **1. Install Docker Desktop**
Either from the website:
- https://docs.docker.com/desktop/setup/install/mac-install/ - https://docs.docker.com/desktop/setup/install/mac-install/
or with Homebrew: Or with Homebrew:
```bash ```bash
brew install --cask docker brew install --cask docker
@@ -256,43 +233,56 @@ docker --version
docker compose 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.). **2. Get the project**
Clone the repo or download the files, then run: ```bash
git clone https://github.com/vxaboveground/Overlord.git
cd Overlord
```
**3. Start it**
macOS uses the same compose file as Windows:
```bash ```bash
docker compose -f docker-compose.windows.yml up -d docker compose -f docker-compose.windows.yml up -d
``` ```
To rebuild after an update: **4. Open the panel**
```text
https://localhost:5173
```
**5. Update later**
```bash ```bash
docker compose -f docker-compose.windows.yml up --build -d docker compose -f docker-compose.windows.yml down
docker compose -f docker-compose.windows.yml pull
docker compose -f docker-compose.windows.yml up -d
```
**6. Stop**
```bash
docker compose -f docker-compose.windows.yml down
``` ```
</details> </details>
---
## No Docker (.bat / .sh) ## No Docker (.bat / .sh)
<details> If you don't want Docker, use the included scripts.
<summary>If you do not want Docker, use the included scripts.</summary>
<br>
Prerequisites for local (non-Docker) runs: Prerequisites:
- Bun in PATH - Bun in PATH
- Go 1.21+ in PATH - Go 1.21+ in PATH
</details>
<hr>
### Windows ### Windows
<details>
<summary>Script instructions for Windows</summary>
<br>
Development mode (starts server + client): Development mode (starts server + client):
```bat ```bat
@@ -311,37 +301,24 @@ Build client binaries (adds client builds to the build queue):
build-clients.bat build-clients.bat
``` ```
</details>
<hr>
### Linux / macOS ### Linux / macOS
<details>
<summary>Installation instructions for Linux / Mac</summary>
<br>
Make scripts executable once: Make scripts executable once:
```bash ```bash
chmod +x start-dev.sh start-dev-server.sh start-dev-client.sh start-prod.sh build-prod-package.sh 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): Development mode (server in background, client in foreground):
```bash ```bash
./start-dev.sh ./start-dev.sh
``` ```
Only server: Only server, or only client:
```bash ```bash
./start-dev.sh server ./start-dev.sh server
```
Only client:
```bash
./start-dev.sh client ./start-dev.sh client
``` ```
@@ -351,7 +328,7 @@ Production mode:
./start-prod.sh ./start-prod.sh
``` ```
</details> ---
## Production Package Scripts ## Production Package Scripts
@@ -363,104 +340,75 @@ Windows:
build-prod-package.bat build-prod-package.bat
``` ```
Linux/macOS: Output: `release/`
Linux / macOS:
```bash ```bash
./build-prod-package.sh ./build-prod-package.sh
``` ```
Package output: Output: `release/prod-package/`
- Windows script: `release` ---
- Linux/macOS script: `release/prod-package`
## Docker Notes (TLS, reverse proxy, cache) ## Docker Notes (TLS, reverse proxy, cache)
<p>Here we will store some notes for you to read depending on what it is. Configs, work arounds etc.</p> Notes on configs and workarounds.
<hr>
### BuildKit cache for faster rebuilds ### BuildKit cache for faster rebuilds
`docker-compose.yml` includes `build.cache_from` and `build.cache_to` using `.docker-cache/buildx`. `docker-compose.yml` ships with `build.cache_from` and `build.cache_to` pointing at `.docker-cache/buildx`. Local builds reuse it automatically — no extra setup.
Rebuild:
```sh
docker compose up --build -d
```
<hr>
### Runtime client build cache ### Runtime client build cache
The compose setup uses a persistent volume for runtime client builds: The compose setup uses a persistent volume for runtime client builds:
- volume: `overlord-client-build-cache` - Volume: `overlord-client-build-cache`
- mount: `/app/client-build-cache` - Mount: `/app/client-build-cache`
- env: `OVERLORD_CLIENT_BUILD_CACHE_DIR` (default `/app/client-build-cache`) - Env: `OVERLORD_CLIENT_BUILD_CACHE_DIR` (default `/app/client-build-cache`)
<hr>
### Certbot TLS ### Certbot TLS
To use certbot certificates in production Docker: To use Let's Encrypt certificates in production Docker:
#### Set: 1. Set `OVERLORD_TLS_CERTBOT_ENABLED=true`
OVERLORD_TLS_CERTBOT_ENABLED=true 2. Set `OVERLORD_TLS_CERTBOT_DOMAIN=your-domain.com`
#### Set: 3. Mount letsencrypt into the container read-only, e.g. `/etc/letsencrypt:/etc/letsencrypt:ro`
OVERLORD_TLS_CERTBOT_DOMAIN=your-domain.com
- Mount letsencrypt into container read-only (example: `/etc/letsencrypt:/etc/letsencrypt:ro`)
#### Default cert paths: 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 cert: /etc/letsencrypt/live/<domain>/fullchain.pem
OVERLORD_TLS_CERTBOT_CERT_FILE key: /etc/letsencrypt/live/<domain>/privkey.pem
OVERLORD_TLS_CERTBOT_KEY_FILE ca: /etc/letsencrypt/live/<domain>/chain.pem
OVERLORD_TLS_CERTBOT_CA_FILE ```
<hr> Override with:
### Reverse proxy TLS offload (Render, etc.) - `OVERLORD_TLS_CERTBOT_LIVE_PATH`
- `OVERLORD_TLS_CERTBOT_CERT_FILE`
- `OVERLORD_TLS_CERTBOT_KEY_FILE`
- `OVERLORD_TLS_CERTBOT_CA_FILE`
#### If your platform terminates TLS before traffic reaches Overlord, set: ### Reverse proxy TLS offload
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: If your platform terminates TLS before traffic reaches Overlord (Render, Caddy, nginx, etc.), set:
- 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
<hr>
For ngrok/local reverse proxy use, a common setup is:
```sh
OVERLORD_TLS_OFFLOAD=true OVERLORD_TLS_OFFLOAD=true
OVERLORD_HEALTHCHECK_URL=http://localhost:5173/health OVERLORD_HEALTHCHECK_URL=http://localhost:5173/health
OVERLORD_PUBLISH_HOST=127.0.0.1 OVERLORD_PUBLISH_HOST=127.0.0.1
``` ```
Then point ngrok at local HTTP: When enabled:
```sh - Container serves internal HTTP on `0.0.0.0:$PORT`
ngrok http http://127.0.0.1:5173 - External URL stays `https://...` through your platform proxy
``` - Health checks should use `http://localhost:$PORT/health` inside the container
- Don't expose the internal container HTTP port directly to the internet
<hr> ### Notes
Notes: - Keep `HOST=0.0.0.0` inside the container. Limit exposure with `OVERLORD_PUBLISH_HOST`, not the bind host.
- If your `.env` secret/password contains `$`, escape it as `$$` to avoid Docker Compose variable-expansion warnings.
- 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.