CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing
+
+## Propose changes
+
+Open a pull request against `develop`. Keep the default branch for releases and
+stable tips; land work on `develop` first.
+
+Point at an existing issue when one fits. Prefer a short issue that states the
+symptom or request before a large PR.
+
+## Commits
+
+Subject form:
+
+```
+area: Imperative summary
+```
+
+- **Area** is a real package, directory, or subsystem token (`ci:`, `docs:`,
+  Go package name). Not a lone filename.
+- **Imperative** mood: Fix, Add, Remove — not "Fixed" or "This patch…".
+- No trailing period. Aim ≤ ~70–75 characters for the whole subject.
+- Not conventional-commits (`feat:` / `fix:` / `chore:` as types).
+
+Body explains **why**. Establish the problem, then say what you are doing.
+One logical change per commit; split fix and cleanup.
+
+## Pull requests
+
+Title matches the primary commit subject.
+
+- **What** changed
+- **Why** (problem and impact)
+- **Test** (concrete steps; "CI green" alone is weak)
+
+## Issues and closing
+
+Cite leftover issues by **full URL**. Gitea closes issues when `#N` appears in
+merge text, so do not put `#N` in the merge message unless that issue is actually
+done. Use `Fixes #N` / `Closes #N` only when the leftover work is finished.

README.md

@@ -13,22 +13,28 @@ A pure-Go reverse proxy with embedded web UI. Supports proxy hosts, TCP/UDP stre
 ```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)
+# Admin UI + API on 127.0.0.1:8081
+# Proxy HTTP on :8080, HTTPS on :18443
 ```
 
-Visit http://localhost:81
+Visit http://localhost:8081
 
 Data (db, certs, logs, www html) lives in `./data` relative to where you ran the binary.
 
 ## Docker (recommended)
 ```bash
 docker compose up -d
+# compose sets ADMIN_PORT=81 PROXY_HTTP_PORT=80 PROXY_HTTPS_PORT=443
+# proxy :80/:443 published; admin binds 127.0.0.1:81 (not published by default)
 # or
 docker build -t helix-proxy:dev .
-docker run -p 81:81 -v $PWD/data:/app/data --workdir /app helix-proxy:dev
+docker run -p 80:80 -p 443:443 \
+  -e ADMIN_PORT=81 -e PROXY_HTTP_PORT=80 -e PROXY_HTTPS_PORT=443 \
+  -v $PWD/data:/app/data --workdir /app helix-proxy:dev
 ```
 
+Publishing admin (`-p 81:81`) also needs `-e ADMIN_HOST=0.0.0.0`. Do not publish :81 on untrusted networks.
+
 PUID/PGID + DISABLE_IPV6 example (see docker-compose.yml for full):
 ```yaml
 # user: "0:0"  # root to allow chown+drop inside
@@ -41,7 +47,7 @@ environment:
 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/).
+See docker-compose.yml for full example (listens on 80/81/443 via env, publishes 80/443, volume for data/).
 
 ## Paths (all overridable)
 - `data/db.bolt` (or `DATA_DIR`)

docker-compose.yml

@@ -12,14 +12,18 @@ services:
       - ./data:/app/data
     # user: "0:0"   # required when using PUID/PGID != built-in to allow binary to chown+drop
     # working_dir: /app   # binary uses CWD for relative data/ + data/www/
-    # environment:
-    #   - JWT_SECRET=  # optional; otherwise a random secret is stored in data/.jwt_secret
-    #   - DATA_DIR=/app/data
-    #   - WWW_DIR=/app/data/www
-    #   - PUID=1000
-    #   - PGID=1000
-    #   - DISABLE_IPV6=1
-    #   # PUID_NO_DROP=1   # if using low ports (80/443) + PUID: chown as root but skip drop (stay root for bind; default drop runs as PUID after, requires high ports or NET_BIND_SERVICE cap)
+    environment:
+      - ADMIN_PORT=81
+      - PROXY_HTTP_PORT=80
+      - PROXY_HTTPS_PORT=443
+      # ADMIN_HOST defaults to 127.0.0.1 (healthcheck hits 127.0.0.1:81)
+      # - JWT_SECRET=  # optional; otherwise a random secret is stored in data/.jwt_secret
+      # - DATA_DIR=/app/data
+      # - WWW_DIR=/app/data/www
+      # - PUID=1000
+      # - PGID=1000
+      # - DISABLE_IPV6=1
+      # # PUID_NO_DROP=1   # if using low ports (80/443) + PUID: chown as root but skip drop (stay root for bind; default drop runs as PUID after, requires high ports or NET_BIND_SERVICE cap)
     # To use optional SQL backend instead of default yaml:
     #   - DB_TYPE=postgres
     #   - DB_POSTGRES_HOST=db