initial commit

README.md

@@ -0,0 +1,70 @@
+# Helix Proxy
+
+A pure-Go reverse proxy with embedded web UI. Supports proxy hosts, TCP/UDP streams, redirections, dead hosts, certificates (Let's Encrypt + custom), access lists, audit, and more. Single static binary. Single built-in admin (no multi-user registration; defaults to "password", first login forces a change which is then bcrypt-hashed and stored in the DB).
+
+**Key features / differences from traditional setups**:
+- **Entirely replaces nginx**: pure Go reverse proxy (http) + TCP/UDP stream proxy engine. No nginx binary, no config files on disk for routing, live updates.
+- **Single binary**: the modern Svelte SPA UI is built and **embedded** (`//go:embed`) into the Go executable.
+- **Storage**: default is a single `data/db.bolt` (cwd-relative, bbolt embedded).
+- **No magic paths**: everything defaults to paths relative to the process CWD (`data/db.bolt`, `data/www/`, `data/certs/`, ...). All overridable with env vars (`DATA_DIR`, `WWW_DIR`, etc.).
+- **www/html lives in data/** by default (single volume tree).
+
+## Quick start (binary)
+```bash
+make          # builds UI (placeholder) + Go binary with embed
+./helix-proxy
+# Admin UI + API on :81
+# Proxy on :8080 (or 80/443 when you have perms / run in docker)
+```
+
+Visit http://localhost:81
+
+Data (db, certs, logs, www html) lives in `./data` relative to where you ran the binary.
+
+## Docker (recommended)
+```bash
+docker compose up -d
+# or
+docker build -t helix-proxy:dev .
+docker run -p 81:81 -v $PWD/data:/app/data --workdir /app helix-proxy:dev
+```
+
+PUID/PGID + DISABLE_IPV6 example (see docker-compose.yml for full):
+```yaml
+# user: "0:0"  # root to allow chown+drop inside
+environment:
+  - PUID=1000
+  - PGID=1000
+  - DISABLE_IPV6=1
+  # PUID_NO_DROP=1  # for low ports (80/443) + PUID: do chown as root but do not drop (stay root to bind low ports; default with PUID drops to non-root after chown, so use high ports or NET_BIND_SERVICE cap or run without PUID for low ports)
+```
+Binary auto-chowns data tree (if started root) then drops privs (unless PUID_NO_DROP); umask support via UMASK env. Files 0600, dirs 0755.
+Note: privilege drop happens early (before listeners); low-port binds require either root (with PUID_NO_DROP), capabilities, high ports in config, or external setuid wrapper.
+
+See docker-compose.yml for full example (exposes 80/81/443, volume for data/).
+
+## Paths (all overridable)
+- `data/db.bolt` (or `DATA_DIR`)
+- `data/certs/`, `data/logs/`, `data/letsencrypt-acme-challenge/`
+- `data/www/` (default site / custom html; `WWW_DIR` or `HTML_DIR`)
+- etc.
+
+## Status
+Core features implemented and verified:
+- cwd-relative + env-overridable paths/storage (single `data/db.bolt` primary via bbolt)
+- pure-Go engine: proxy hosts (full: locations, advanced_config parser, ssl_forced, block_exploits, websocket, hsts, caching w/ HIT/MISS, access lists, custom certs, LE), streams (tcp/udp +ssl term), redirection hosts (full forward_http_code/preservePath/scheme + CRUD), dead hosts (per-dead custom content + CRUD)
+- certificates: custom PEM (meta keys compat) + full Let's Encrypt issuance/renewal via lego (http-01). In PROXY_MODE=development *all* LE certs are self-signed test certs (domain-based sim tricks removed).
+- single admin (defaults to "password"; first login forces change; hashed + stored in DB; no registration or multi-user)
+- audit (userId=1), settings (default_site + letsencrypt_email etc)
+- live reload on all CRUD, dual https/http + SNI, embedded Svelte SPA (full tabs, pickers, edits)
+- single binary (go build embeds UI after make ui-build), docker multi-stage + full PUID/PGID/umask
+- no nginx, no .conf files, no external processes for proxying
+
+LE note: for real certs use a public DNS domain pointing at your server (port 80/http reachable). By default (production), real LE http-01 is used. Set PROXY_MODE=development and *all* letsencrypt cert requests will produce self-signed test certs instead (for dev/testing; see TESTING.md). Real LE will be used otherwise (requires valid email, port 80 reachable etc).
+
+## Development
+- `make ui-build` (once real Svelte UI added to ui/)
+- `make`
+- `make docker`
+
+Contributions / v2 features: open an issue or just ask to implement the next piece (advanced config, full certs with lego, streams, full Svelte UI, SQL backend, etc.).