diff --git a/README.md b/README.md index 7c75216..c4759e1 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,10 @@ 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)](#quick-start-docker) @@ -24,6 +28,10 @@ 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](#docker-install-by-os) for the correct commands. +
+ +Installation instructions for Linux + 1. Create a `docker-compose.yml` file and paste this: ```yaml @@ -114,10 +122,15 @@ 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/ @@ -217,8 +230,15 @@ docker --version docker compose version ``` +
+ ### macOS + +
+ Installation instructions for Mac +
+ Install Docker Desktop: - https://docs.docker.com/desktop/setup/install/mac-install/ @@ -250,17 +270,29 @@ 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. +
+ 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): ```bat @@ -273,14 +305,22 @@ Production mode (build + run server executable): start-prod.bat ``` -Build client binaries: +Build client binaries (adds client builds to the build queue): ```bat build-clients.bat ``` +
+ +
+ ### Linux / macOS +
+ Installation instructions for Linux / Mac +
+ Make scripts executable once: ```bash @@ -311,6 +351,8 @@ Production mode: ./start-prod.sh ``` +
+ ## Production Package Scripts Build a production-ready package where the server can still build client binaries at runtime. @@ -334,6 +376,10 @@ Package output: ## 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`. @@ -344,6 +390,8 @@ Rebuild: docker compose up --build -d ``` +
+ ### Runtime client build cache The compose setup uses a persistent volume for runtime client builds: @@ -352,34 +400,40 @@ The compose setup uses a persistent volume for runtime client builds: - 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` +#### 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: +#### Default cert paths: + cert: /etc/letsencrypt/live//fullchain.pem + key: /etc/letsencrypt/live//privkey.pem + ca: /etc/letsencrypt/live//chain.pem -- cert: `/etc/letsencrypt/live//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 -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) +#### 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: @@ -388,6 +442,8 @@ When enabled: - 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 @@ -402,6 +458,8 @@ 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.