From 83c2b38545b72be674cdf14e005a6074ce00187f Mon Sep 17 00:00:00 2001 From: John Romkey <58883+romkey@users.noreply.github.com> Date: Mon, 16 Nov 2026 09:44:36 -0800 Subject: [PATCH 1/4] Add Komodo, Prometheus and other experiments; deprecate unused apps; document conventions New experiments: - komodo (core, periphery, bundled MongoDB) - prometheus with node-exporter, cadvisor, nut-exporter and an optional snmp-exporter, plus an example prometheus.yml with jobs for every app that exports metrics - laser-cutterd, unifi-occupancy, unifi-audit-daemon, library Changed: - grafana: open-source image, Postgres database, Prometheus network, Authentik OAuth settings in .env.example - vllm, llama-cpp, comfyui: networks and ports moved to docker-compose.networks.yml / docker-compose.ports.yml overlays, selected with COMPOSE_ACCESS in .env; COMPOSE_FILE assembled from per-choice parts Deprecated: statping, camera2prusa, homebox, influxdb, osticket, portainer, stable-diffusion-webui, telegraf, chronograf. Backups: remove the empty .rsync-exclude files and fix the workflow so it collects apps/*/.rsync.exclude and experiments/*/.rsync.exclude. Add AGENTS.md (with CLAUDE.md pointing to it) and a hackstack-app skill describing the repo's compose, .env, config and README conventions. Co-Authored-By: Claude Opus 5.5 --- .claude/skills/hackstack-app/SKILL.md | 34 ++++ .cursor/rules/docker-compose.mdc | 6 +- .../workflows/concatenate_rsync_exclude.yml | 35 +++- .rsync.exclude.initial | 3 +- AGENTS.md | 185 +++++++++++++++++ CLAUDE.md | 1 + apps/access-control-webhook/.rsync-exclude | 0 apps/adminer/.rsync-exclude | 0 apps/airconnect/.rsync-exclude | 0 apps/authentik/.rsync-exclude | 0 apps/autogenerate-hosts/.rsync-exclude | 0 apps/backrest/.rsync-exclude | 0 apps/bfg-repo-cleaner/.rsync-exclude | 0 apps/caddy-home-assistant-liar/.rsync-exclude | 0 apps/calibre-web/.rsync-exclude | 0 apps/cloudflare-ddns/.rsync-exclude | 0 apps/cups/.rsync-exclude | 0 apps/cyberchef/.rsync-exclude | 0 apps/db-backup/.rsync-exclude | 0 apps/dnsmasq/.rsync-exclude | 0 apps/dozzle/.rsync-exclude | 0 apps/esphome/.rsync-exclude | 0 apps/event-manager/.rsync-exclude | 0 apps/geowiki/.rsync-exclude | 0 apps/glances/.rsync-exclude | 0 apps/glitchtip/.rsync-exclude | 0 apps/home-assistant/.rsync-exclude | 0 apps/invidious/.rsync-exclude | 0 apps/jellyfin/.rsync-exclude | 0 apps/llama-cpp/.env.example | 41 +++- apps/llama-cpp/.rsync-exclude | 0 apps/llama-cpp/README.md | 45 +++-- apps/llama-cpp/docker-compose.arc.yml | 2 +- apps/llama-cpp/docker-compose.jetson.yml | 2 +- apps/llama-cpp/docker-compose.networks.yml | 16 ++ apps/llama-cpp/docker-compose.nfs.yml | 3 +- apps/llama-cpp/docker-compose.nvidia.yml | 2 +- apps/llama-cpp/docker-compose.ports.yml | 6 + apps/llama-cpp/docker-compose.spark.yml | 2 +- apps/llama-cpp/docker-compose.strix.yml | 2 +- apps/llama-cpp/docker-compose.yml | 16 +- apps/mariadb/.rsync-exclude | 0 apps/matomo/.rsync-exclude | 0 apps/matter/.rsync-exclude | 0 apps/mdns-repeater/.rsync-exclude | 0 apps/member-zone/.rsync-exclude | 0 .../.rsync-exclude | 0 apps/mosquitto/.rsync-exclude | 0 apps/mqtt-explorer/.rsync-exclude | 0 apps/music-assistant/.rsync-exclude | 0 apps/netboot/.rsync-exclude | 0 apps/nginx-proxy-manager/.rsync-exclude | 0 apps/ollama/.rsync-exclude | 0 apps/openwebui/.rsync-exclude | 0 apps/partdb/.rsync-exclude | 0 apps/peanut/.rsync-exclude | 0 apps/piper/.rsync-exclude | 0 apps/planka/.rsync-exclude | 0 apps/postfix/.rsync-exclude | 0 apps/postgresql/.rsync-exclude | 0 apps/rsyslog/.rsync-exclude | 0 apps/sensors2mqtt/.rsync-exclude | 0 .../shairport-metadata-display/.rsync-exclude | 0 apps/shairport-sync/.rsync-exclude | 0 apps/statping/.rsync-exclude | 0 apps/upsd/.rsync-exclude | 0 apps/vaultwarden/.rsync-exclude | 0 apps/vllm/.env.example | 41 +++- apps/vllm/README.md | 46 +++-- apps/vllm/docker-compose.arc.yml | 4 +- apps/vllm/docker-compose.jetson.yml | 2 +- apps/vllm/docker-compose.networks.yml | 16 ++ apps/vllm/docker-compose.nfs.yml | 4 +- apps/vllm/docker-compose.nvidia.yml | 2 +- apps/vllm/docker-compose.ports.yml | 6 + apps/vllm/docker-compose.spark.yml | 2 +- apps/vllm/docker-compose.strix.yml | 2 +- apps/vllm/docker-compose.yml | 20 +- apps/watchtower/.rsync-exclude | 0 apps/weather/.rsync-exclude | 0 apps/whisper/.rsync-exclude | 0 apps/wiki/.rsync-exclude | 0 apps/z-wavejs/.rsync-exclude | 0 apps/zigbee2mqtt/.rsync-exclude | 0 bin/install-chaos.sh | 2 - .../camera2prusa/.env.example | 0 .../camera2prusa/README.md | 0 .../camera2prusa/docker-compose.yml | 0 .../chronograf/.env.example | 0 .../chronograf/README.md | 0 .../chronograf/docker-compose.yml | 0 deprecated/frigate/.rsync-exclude | 0 .../homebox/.env.example | 0 .../homebox/.gitignore | 0 {experiments => deprecated}/homebox/README.md | 0 .../homebox/config/config.yml.default | 0 .../homebox/docker-compose.yml | 0 .../influxdb/.env.example | 0 .../influxdb/.gitignore | 0 .../influxdb/.rsync.exclude | 0 .../influxdb/README.md | 0 .../influxdb/config/.gitkeep | 0 .../influxdb/docker-compose.yml | 0 deprecated/mopidy/.rsync-exclude | 0 deprecated/openwakeword/.rsync-exclude | 0 .../osticket/.env.example | 0 .../osticket/README.md | 0 .../osticket/docker-compose.yml | 0 .../portainer/.env.example | 0 .../portainer/README.md | 0 .../portainer/docker-compose.yml | 0 deprecated/snapclient/.rsync-exclude | 0 deprecated/snapserver/.rsync-exclude | 0 .../stable-diffusion-webui/.env.example | 0 .../stable-diffusion-webui/README.md | 0 .../docker-compose.nfs.yml | 0 .../stable-diffusion-webui/docker-compose.yml | 0 {apps => deprecated}/statping/.env.example | 0 {apps => deprecated}/statping/README.md | 0 .../statping/docker-compose.yml | 0 .../telegraf/.env.example | 0 .../telegraf/.gitignore | 0 .../telegraf/README.md | 0 .../telegraf/config/telegraf.conf.example | 0 .../telegraf/docker-compose.yml | 0 docs/apps-compose-healthchecks.md | 1 - docs/contributing.md | 2 + docs/core.md | 2 - docs/design.md | 4 +- experiments/avahi-mdns/.rsync-exclude | 0 experiments/camera2prusa/.rsync-exclude | 0 experiments/chronograf/.rsync-exclude | 0 experiments/comfyui/.env.example | 48 +++-- experiments/comfyui/README.md | 46 +++-- experiments/comfyui/docker-compose.jetson.yml | 2 +- .../comfyui/docker-compose.networks.yml | 16 ++ experiments/comfyui/docker-compose.nfs.yml | 4 +- .../comfyui/docker-compose.nvidia-cu128.yml | 2 +- .../comfyui/docker-compose.nvidia-sage.yml | 2 +- experiments/comfyui/docker-compose.nvidia.yml | 2 +- experiments/comfyui/docker-compose.ports.yml | 6 + experiments/comfyui/docker-compose.rocm.yml | 2 +- experiments/comfyui/docker-compose.xpu.yml | 2 +- experiments/comfyui/docker-compose.yml | 16 +- experiments/forgejo/.rsync-exclude | 0 experiments/grafana/.env.example | 45 +++++ experiments/grafana/.rsync-exclude | 0 experiments/grafana/.rsync.exclude | 1 - experiments/grafana/README.md | 51 ++++- .../grafana/config/grafana.ini.example | 11 + experiments/grafana/docker-compose.yml | 14 +- experiments/homebox/.rsync-exclude | 0 experiments/influxdb/.rsync-exclude | 0 experiments/komodo/.env.example | 38 ++++ experiments/komodo/.rsync.exclude | 1 + experiments/komodo/README.md | 43 ++++ experiments/komodo/docker-compose.yml | 68 +++++++ experiments/laser-cutterd/.env.example | 69 +++++++ experiments/laser-cutterd/.gitignore | 1 + experiments/laser-cutterd/README.md | 52 +++++ experiments/laser-cutterd/docker-compose.yml | 29 +++ experiments/library/.env.example | 75 +++++++ experiments/library/.gitignore | 1 + experiments/library/README.md | 84 ++++++++ experiments/library/docker-compose.yml | 74 +++++++ experiments/matrix/.rsync-exclude | 0 experiments/mediawiki/.rsync-exclude | 0 experiments/nextcloud/.rsync-exclude | 0 experiments/olah/.rsync-exclude | 0 experiments/portainer/.rsync-exclude | 0 experiments/prometheus/.env.example | 16 ++ experiments/prometheus/.gitignore | 3 + experiments/prometheus/.rsync.exclude | 1 + experiments/prometheus/README.md | 83 ++++++++ .../prometheus/config/prometheus.yml.example | 191 ++++++++++++++++++ experiments/prometheus/docker-compose.yml | 102 ++++++++++ experiments/qdrant/.rsync-exclude | 0 experiments/rtl_433/.rsync-exclude | 0 experiments/rtlamr2mqtt/.rsync-exclude | 0 .../stable-diffusion-webui/.rsync-exclude | 0 experiments/telegraf/.rsync-exclude | 0 experiments/trimetd/.rsync-exclude | 0 experiments/unifi-audit-daemon/.env.example | 81 ++++++++ experiments/unifi-audit-daemon/.gitignore | 1 + experiments/unifi-audit-daemon/README.md | 63 ++++++ .../unifi-audit-daemon/docker-compose.yml | 39 ++++ experiments/unifi-occupancy/.env.example | 89 ++++++++ experiments/unifi-occupancy/.gitignore | 2 + experiments/unifi-occupancy/.rsync.exclude | 3 + experiments/unifi-occupancy/README.md | 63 ++++++ .../config/config.yaml.example | 68 +++++++ .../unifi-occupancy/docker-compose.yml | 34 ++++ experiments/uptime-kuma/.rsync-exclude | 0 experiments/uptime-kuma/README.md | 6 +- experiments/uptime-kuma/docker-compose.yml | 4 - 195 files changed, 2031 insertions(+), 180 deletions(-) create mode 100644 .claude/skills/hackstack-app/SKILL.md create mode 100644 AGENTS.md create mode 100644 CLAUDE.md delete mode 100644 apps/access-control-webhook/.rsync-exclude delete mode 100644 apps/adminer/.rsync-exclude delete mode 100644 apps/airconnect/.rsync-exclude delete mode 100644 apps/authentik/.rsync-exclude delete mode 100644 apps/autogenerate-hosts/.rsync-exclude delete mode 100644 apps/backrest/.rsync-exclude delete mode 100644 apps/bfg-repo-cleaner/.rsync-exclude delete mode 100644 apps/caddy-home-assistant-liar/.rsync-exclude delete mode 100644 apps/calibre-web/.rsync-exclude delete mode 100644 apps/cloudflare-ddns/.rsync-exclude delete mode 100644 apps/cups/.rsync-exclude delete mode 100644 apps/cyberchef/.rsync-exclude delete mode 100644 apps/db-backup/.rsync-exclude delete mode 100644 apps/dnsmasq/.rsync-exclude delete mode 100644 apps/dozzle/.rsync-exclude delete mode 100644 apps/esphome/.rsync-exclude delete mode 100644 apps/event-manager/.rsync-exclude delete mode 100644 apps/geowiki/.rsync-exclude delete mode 100644 apps/glances/.rsync-exclude delete mode 100644 apps/glitchtip/.rsync-exclude delete mode 100644 apps/home-assistant/.rsync-exclude delete mode 100644 apps/invidious/.rsync-exclude delete mode 100644 apps/jellyfin/.rsync-exclude delete mode 100644 apps/llama-cpp/.rsync-exclude create mode 100644 apps/llama-cpp/docker-compose.networks.yml create mode 100644 apps/llama-cpp/docker-compose.ports.yml delete mode 100644 apps/mariadb/.rsync-exclude delete mode 100644 apps/matomo/.rsync-exclude delete mode 100644 apps/matter/.rsync-exclude delete mode 100644 apps/mdns-repeater/.rsync-exclude delete mode 100644 apps/member-zone/.rsync-exclude delete mode 100644 apps/mosquitto-management-center/.rsync-exclude delete mode 100644 apps/mosquitto/.rsync-exclude delete mode 100644 apps/mqtt-explorer/.rsync-exclude delete mode 100644 apps/music-assistant/.rsync-exclude delete mode 100644 apps/netboot/.rsync-exclude delete mode 100644 apps/nginx-proxy-manager/.rsync-exclude delete mode 100644 apps/ollama/.rsync-exclude delete mode 100644 apps/openwebui/.rsync-exclude delete mode 100644 apps/partdb/.rsync-exclude delete mode 100644 apps/peanut/.rsync-exclude delete mode 100644 apps/piper/.rsync-exclude delete mode 100644 apps/planka/.rsync-exclude delete mode 100644 apps/postfix/.rsync-exclude delete mode 100644 apps/postgresql/.rsync-exclude delete mode 100644 apps/rsyslog/.rsync-exclude delete mode 100644 apps/sensors2mqtt/.rsync-exclude delete mode 100644 apps/shairport-metadata-display/.rsync-exclude delete mode 100644 apps/shairport-sync/.rsync-exclude delete mode 100644 apps/statping/.rsync-exclude delete mode 100644 apps/upsd/.rsync-exclude delete mode 100644 apps/vaultwarden/.rsync-exclude create mode 100644 apps/vllm/docker-compose.networks.yml create mode 100644 apps/vllm/docker-compose.ports.yml delete mode 100644 apps/watchtower/.rsync-exclude delete mode 100644 apps/weather/.rsync-exclude delete mode 100644 apps/whisper/.rsync-exclude delete mode 100644 apps/wiki/.rsync-exclude delete mode 100644 apps/z-wavejs/.rsync-exclude delete mode 100644 apps/zigbee2mqtt/.rsync-exclude rename {experiments => deprecated}/camera2prusa/.env.example (100%) rename {experiments => deprecated}/camera2prusa/README.md (100%) rename {experiments => deprecated}/camera2prusa/docker-compose.yml (100%) rename {experiments => deprecated}/chronograf/.env.example (100%) rename {experiments => deprecated}/chronograf/README.md (100%) rename {experiments => deprecated}/chronograf/docker-compose.yml (100%) delete mode 100644 deprecated/frigate/.rsync-exclude rename {experiments => deprecated}/homebox/.env.example (100%) rename {experiments => deprecated}/homebox/.gitignore (100%) rename {experiments => deprecated}/homebox/README.md (100%) rename {experiments => deprecated}/homebox/config/config.yml.default (100%) rename {experiments => deprecated}/homebox/docker-compose.yml (100%) rename {experiments => deprecated}/influxdb/.env.example (100%) rename {experiments => deprecated}/influxdb/.gitignore (100%) rename {experiments => deprecated}/influxdb/.rsync.exclude (100%) rename {experiments => deprecated}/influxdb/README.md (100%) rename {experiments => deprecated}/influxdb/config/.gitkeep (100%) rename {experiments => deprecated}/influxdb/docker-compose.yml (100%) delete mode 100644 deprecated/mopidy/.rsync-exclude delete mode 100644 deprecated/openwakeword/.rsync-exclude rename {experiments => deprecated}/osticket/.env.example (100%) rename {experiments => deprecated}/osticket/README.md (100%) rename {experiments => deprecated}/osticket/docker-compose.yml (100%) rename {experiments => deprecated}/portainer/.env.example (100%) rename {experiments => deprecated}/portainer/README.md (100%) rename {experiments => deprecated}/portainer/docker-compose.yml (100%) delete mode 100644 deprecated/snapclient/.rsync-exclude delete mode 100644 deprecated/snapserver/.rsync-exclude rename {experiments => deprecated}/stable-diffusion-webui/.env.example (100%) rename {experiments => deprecated}/stable-diffusion-webui/README.md (100%) rename {experiments => deprecated}/stable-diffusion-webui/docker-compose.nfs.yml (100%) rename {experiments => deprecated}/stable-diffusion-webui/docker-compose.yml (100%) rename {apps => deprecated}/statping/.env.example (100%) rename {apps => deprecated}/statping/README.md (100%) rename {apps => deprecated}/statping/docker-compose.yml (100%) rename {experiments => deprecated}/telegraf/.env.example (100%) rename {experiments => deprecated}/telegraf/.gitignore (100%) rename {experiments => deprecated}/telegraf/README.md (100%) rename {experiments => deprecated}/telegraf/config/telegraf.conf.example (100%) rename {experiments => deprecated}/telegraf/docker-compose.yml (100%) delete mode 100644 experiments/avahi-mdns/.rsync-exclude delete mode 100644 experiments/camera2prusa/.rsync-exclude delete mode 100644 experiments/chronograf/.rsync-exclude create mode 100644 experiments/comfyui/docker-compose.networks.yml create mode 100644 experiments/comfyui/docker-compose.ports.yml delete mode 100644 experiments/forgejo/.rsync-exclude delete mode 100644 experiments/grafana/.rsync-exclude delete mode 100644 experiments/grafana/.rsync.exclude delete mode 100644 experiments/homebox/.rsync-exclude delete mode 100644 experiments/influxdb/.rsync-exclude create mode 100644 experiments/komodo/.env.example create mode 100644 experiments/komodo/.rsync.exclude create mode 100644 experiments/komodo/README.md create mode 100644 experiments/komodo/docker-compose.yml create mode 100644 experiments/laser-cutterd/.env.example create mode 100644 experiments/laser-cutterd/.gitignore create mode 100644 experiments/laser-cutterd/README.md create mode 100644 experiments/laser-cutterd/docker-compose.yml create mode 100644 experiments/library/.env.example create mode 100644 experiments/library/.gitignore create mode 100644 experiments/library/README.md create mode 100644 experiments/library/docker-compose.yml delete mode 100644 experiments/matrix/.rsync-exclude delete mode 100644 experiments/mediawiki/.rsync-exclude delete mode 100644 experiments/nextcloud/.rsync-exclude delete mode 100644 experiments/olah/.rsync-exclude delete mode 100644 experiments/portainer/.rsync-exclude create mode 100644 experiments/prometheus/.env.example create mode 100644 experiments/prometheus/.gitignore create mode 100644 experiments/prometheus/.rsync.exclude create mode 100644 experiments/prometheus/README.md create mode 100644 experiments/prometheus/config/prometheus.yml.example create mode 100644 experiments/prometheus/docker-compose.yml delete mode 100644 experiments/qdrant/.rsync-exclude delete mode 100644 experiments/rtl_433/.rsync-exclude delete mode 100644 experiments/rtlamr2mqtt/.rsync-exclude delete mode 100644 experiments/stable-diffusion-webui/.rsync-exclude delete mode 100644 experiments/telegraf/.rsync-exclude delete mode 100644 experiments/trimetd/.rsync-exclude create mode 100644 experiments/unifi-audit-daemon/.env.example create mode 100644 experiments/unifi-audit-daemon/.gitignore create mode 100644 experiments/unifi-audit-daemon/README.md create mode 100644 experiments/unifi-audit-daemon/docker-compose.yml create mode 100644 experiments/unifi-occupancy/.env.example create mode 100644 experiments/unifi-occupancy/.gitignore create mode 100644 experiments/unifi-occupancy/.rsync.exclude create mode 100644 experiments/unifi-occupancy/README.md create mode 100644 experiments/unifi-occupancy/config/config.yaml.example create mode 100644 experiments/unifi-occupancy/docker-compose.yml delete mode 100644 experiments/uptime-kuma/.rsync-exclude diff --git a/.claude/skills/hackstack-app/SKILL.md b/.claude/skills/hackstack-app/SKILL.md new file mode 100644 index 0000000..10ba3c0 --- /dev/null +++ b/.claude/skills/hackstack-app/SKILL.md @@ -0,0 +1,34 @@ +--- +name: hackstack-app +description: Add, change, move or review a Hackstack app (anything under apps/, experiments/ or deprecated/) - its docker-compose files, overlays, .env.example, config/ examples and README - following the repo's conventions. +--- + +# Hackstack app + +The conventions are in [AGENTS.md](../../../AGENTS.md) at the repo root. Read it first; this is the checklist for applying it. + +## Adding an app + +1. **Gather facts from upstream** before writing anything: the published image and its tags, the port it listens on, the uid it runs as, the tools in the image (for the healthcheck), every environment variable it reads, the config files it uses, and whether it needs a database, Redis, MQTT, mail or the Docker socket. If upstream has its own production compose file and `.env.example`, start from those. +2. **Pick the namespace**: `experiments/` unless told otherwise. +3. **Write `docker-compose.yml`** to the AGENTS.md pattern: `${IMAGE_VERSION:-...}`, `container_name`/`hostname` = app name, `restart: unless-stopped`, `env_file: .env`, relative bind mounts under `../../lib|log|run/` and `./config`, commented-out `ports:`, only the networks it needs, a healthcheck. + - Shared PostgreSQL/MariaDB, never a bundled one. Per-app Redis on a private network. + - No host networking unless nothing else works; macvlan overlay if it must appear on the LAN. +4. **Add overlays** for anything a deployment would choose differently (NFS, macvlan, GPU backend, published ports vs proxy networks), enabled through `COMPOSE_FILE` in `.env`. The user must never need to edit a compose file. +5. **Write `.env.example`** with every variable, secrets as `` placeholders, optional settings commented out, hosts as container names, no `BACKUP_DATABASE_URLS`. +6. **Add `config/*.example`** for config files and git-ignore the real ones. +7. **Add `.gitignore`** (`.env` and real config files) and, if there are live database files under `../../lib/`, `.rsync.exclude`. +8. **Write `README.md`** from `docs/app-readme-template.md`: what it is, required settings, database/data-directory/ownership setup, proxy target, overlays, anything unusual, usage. +9. **Check** with `docker compose config -q` (copy `.env.example` to `.env`, then delete it) for every overlay combination. +10. **Look for references**: does Prometheus scrape it (`experiments/prometheus/config/prometheus.yml.example`)? Does another app connect to it? + +## Moving or deprecating an app + +`git mv` the directory, then `git grep` for the app name and old path: `bin/install-*.sh`, `docs/`, other apps' READMEs and compose networks, and the Prometheus example config. Point out apps that depend on it (for example its network). + +## Never + +- Commit secrets, real `.env` files or real config files. +- Edit the top-level `.gitignore` or `.rsync.exclude` (generated by GitHub Actions). +- Tell the user to edit a compose file. +- Run, install or start the stack unless asked. diff --git a/.cursor/rules/docker-compose.mdc b/.cursor/rules/docker-compose.mdc index 8e01ff0..fd4b254 100644 --- a/.cursor/rules/docker-compose.mdc +++ b/.cursor/rules/docker-compose.mdc @@ -2,9 +2,11 @@ alwaysApply: true --- +Full conventions: AGENTS.md at the repo root. The person deploying an app must never have to edit a compose file; never commit secrets. + Don't use version in docker-compose files Always use bind mounts instead of Docker volumes unless the volume is for NFS -Put NFS mounts in docker-compose.nfs.yml; enable with COMPOSE_FILE=docker-compose.yml:docker-compose.nfs.yml in .env (document in .env.example) +Put NFS mounts in docker-compose.nfs.yml; enable with COMPOSE_FILE in .env (document in .env.example) Put LAN macvlan in docker-compose.macvlan.yml; enable with COMPOSE_FILE=docker-compose.yml:docker-compose.macvlan.yml; IP/MAC/parent NIC only via .env (see docs/macvlan.md) Use the initial service name as the hostname and container name restart: unless-stopped @@ -17,7 +19,7 @@ Persistent runtime state should go in ../../lib Log files should go in ../../log Transient runtime state (like .pid files) should go in ../../run Warning if no HEALTHCHECK -Warning if host mode - warn that containers should not run in host unless absolutely necessary +Warning if host mode - warn that containers should not run in host unless absolutely necessary; use a docker-compose.macvlan.yml overlay when the app must appear on the LAN Warning if not host mode and does not declare any networks - should have a db network if it needs a database, proxy if it needs reverse proxy Error if container has its own copy of Postgresql or Mariadb or Mysql - it should use the shared one Whenever possible configuration files should live in a config directory in the same place as docker-compose.yml and .env - must be config not other names diff --git a/.github/workflows/concatenate_rsync_exclude.yml b/.github/workflows/concatenate_rsync_exclude.yml index 6fc85a0..ca9d965 100644 --- a/.github/workflows/concatenate_rsync_exclude.yml +++ b/.github/workflows/concatenate_rsync_exclude.yml @@ -1,11 +1,12 @@ -name: Update .rsync.exlude +name: Update .rsync.exclude on: push: paths: - - "**/.rsync.exclude" + - "apps/**/.rsync.exclude" + - "experiments/**/.rsync.exclude" - ".rsync.exclude.initial" - - ".github/actions/concatenate_rsync_exclude.yml" + - ".github/workflows/concatenate_rsync_exclude.yml" workflow_dispatch: permissions: @@ -19,16 +20,28 @@ jobs: - name: Check out repository uses: actions/checkout@v7 - - name: Concatenate .rsync.exclude files with directory paths + - name: Concatenate .rsync.exclude files run: | # Start with the .rsync.exclude.initial file cp .rsync.exclude.initial .rsync.exclude - - # Find all .rsync.exclude files one level down, process each with its path prefix - find . -mindepth 2 -maxdepth 2 -name ".rsync.exclude" | while read -r rsync_excludes; do - dir_path=$(dirname "$rsync_excludes" | sed 's|^\./||') - echo -e "\n# Patterns from $dir_path/.rsync.exclude" >> .rsync.exclude - cat "$rsync_excludes" >> .rsync.exclude + + # Per-app files already hold paths relative to the backup root + # (e.g. lib//app.db), so they're copied as-is. + for parent_dir in apps experiments; do + if [ ! -d "$parent_dir" ]; then + continue + fi + + find "$parent_dir" -mindepth 2 -maxdepth 2 -name ".rsync.exclude" | sort | \ + while read -r rsync_exclude; do + echo "" >> .rsync.exclude + echo "# [$parent_dir] $rsync_exclude" >> .rsync.exclude + cat "$rsync_exclude" >> .rsync.exclude + # Guard against a file without a trailing newline + if [ -n "$(tail -c1 "$rsync_exclude")" ]; then + echo "" >> .rsync.exclude + fi + done done - name: Check for changes @@ -46,5 +59,5 @@ jobs: git config --global user.name "github-actions[bot]" git config --global user.email "github-actions[bot]@users.noreply.github.com" git add .rsync.exclude - git commit -m "Update top-level .rsync.exclude with directory paths" + git commit -m "Update top-level .rsync.exclude from per-app files" git push origin HEAD:${GITHUB_REF_NAME} diff --git a/.rsync.exclude.initial b/.rsync.exclude.initial index 9f4e2c4..948bd44 100644 --- a/.rsync.exclude.initial +++ b/.rsync.exclude.initial @@ -1,5 +1,6 @@ # Do not edit .rsync.exclude -# File is automatically built from .rsync.exclude.inital and */.rsync.exclude +# Built by .github/workflows/concatenate_rsync_exclude.yml from +# .rsync.exclude.initial and apps/*/.rsync.exclude, experiments/*/.rsync.exclude lost+found/ containerd/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..58a68ed --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,185 @@ +# Working on Hackstack + +Rules for AI agents (and humans) adding or changing apps in this repository. Read this before touching anything under `apps/`, `experiments/` or `deprecated/`. + +Hackstack is the set of Docker Compose apps PDX Hackerspace runs on its servers. It's installed at `/opt/docker`, so each app lives at `/opt/docker//` and its data at `/opt/lib/`, `/opt/log/` and `/opt/run/`. Background and rationale: [docs/contributing.md](docs/contributing.md), [docs/design.md](docs/design.md), [docs/macvlan.md](docs/macvlan.md). + +## The core rule: nobody edits a compose file to deploy an app + +Whoever runs an app configures it **only** through `.env` and files under `config/`. They must never have to edit `docker-compose.yml` or any other compose file, and should be able to `git pull` new versions without merge conflicts. + +So every choice a deployment needs to make lives in `.env`: + +- **Values** (hostnames, ports, credentials, tuning) are environment variables read through `env_file: .env` or `${VAR:-default}` interpolation. +- **Structural choices** (GPU vs CPU, NFS, macvlan, publishing ports, joining the proxy network) are separate overlay compose files, switched on with `COMPOSE_FILE` in `.env`. + +If you find yourself writing "uncomment this line in docker-compose.yml" in a README, make it an overlay or a variable instead. The only exception left in the repo is commented-out `ports:` kept as documentation. + +## Layout + +``` +apps// # in production use +experiments// # being tried out; same conventions, nothing special about installing them +deprecated// # retired; kept for reference, not maintained + docker-compose.yml + docker-compose..yml # optional overlays (see below) + .env.example # committed; every variable, secrets as placeholders + .env # real values; never committed + config/ # config files the app reads; *.example committed, real files ignored + README.md + .gitignore # app-relative paths, e.g. `.env`, `config/app.yml` + .rsync.exclude # optional; live database files to leave out of file backups +``` + +- The directory name is the app name. Use it for the main service's `container_name` and `hostname`, and for its data directories. +- Moving an app between namespaces is a plain `git mv`; also remove it from `bin/install-*.sh` and fix any docs that point at the old path. +- **Never edit the top-level `.gitignore` or `.rsync.exclude`.** GitHub Actions regenerates them from the per-app files. + +## docker-compose.yml + +```yaml +services: + myapp: + image: vendor/myapp:${IMAGE_VERSION:-latest} + container_name: myapp + hostname: myapp + restart: unless-stopped + env_file: + - .env + volumes: + - ./config:/config:ro + - ../../lib/myapp:/data + - ../../log/myapp:/var/log/myapp +# ports: +# - 8080:8080 + networks: + - proxy + - db + healthcheck: + test: ["CMD-SHELL", "wget -q --spider http://127.0.0.1:8080/health || exit 1"] + interval: 30s + timeout: 5s + retries: 3 + start_period: 30s + +networks: + proxy: + external: true + name: nginx-proxy-net + db: + external: true + name: postgres-net +``` + +- **No `version:` key.** +- **Image tags** come from a variable with a default: `${IMAGE_VERSION:-latest}`. Extra images get their own variable (`REDIS_IMAGE_VERSION`, `MONGO_IMAGE_VERSION`). Pin a major version instead of `latest` when upstream breaks things across majors or doesn't publish `latest`. +- **Every service** has `container_name`, `hostname`, `restart: unless-stopped` and, where at all possible, a `healthcheck` that uses a tool the image actually contains (check for `curl`/`wget`/`python` before using it). +- **No constants in compose files.** Environment comes from `env_file: .env`. An `environment:` block is only acceptable for mapping one `.env` variable onto another name (`MONGO_INITDB_ROOT_PASSWORD: ${KOMODO_DATABASE_PASSWORD}`) or for a default the image needs. +- **Locally built or pinned images** that Watchtower shouldn't update get the label `com.centurylinklabs.watchtower.enable=false`. + +### Storage + +- **Bind mounts with relative paths only.** No absolute host paths, no named Docker volumes (except NFS volumes in `docker-compose.nfs.yml`). + - `./config` - configuration the user edits + - `../../lib/` - persistent state; backed up automatically + - `../../log/` - logs; not backed up + - `../../run/` - caches, sockets, pid files; not backed up +- Multi-service apps use subdirectories: `../../lib//redis`, `../../lib//storage`. +- If the image runs as a fixed non-root uid, the README says which and gives the `mkdir`/`chown` commands. +- Rare exception: a path that must be identical inside and outside the container (Komodo's periphery root, for example) is an absolute path from `.env` with a sensible default. + +### Networking + +- **Don't publish ports.** Web UIs are reached through nginx-proxy-manager on `nginx-proxy-net` by container name. Leave the `ports:` block commented out as documentation of the port the app listens on. +- Publish ports only when the protocol can't go through the proxy (MQTT, DNS, NUT, SSH for git). Mark it with `# hackstack: ports required`. +- Join only the networks an app needs. Shared networks are all `external: true`: + + | Alias | Network | For | + |-------|---------|-----| + | `proxy` | `nginx-proxy-net` | reachable through the reverse proxy | + | `db` | `postgres-net` | shared PostgreSQL (host `postgresql`) | + | `mariadb` | `mariadb-net` | shared MariaDB (host `mariadb`) | + | `mqtt` | `mosquitto-net` | MQTT broker (host `mosquitto`) | + | `mail` | `postfix-net` | outbound mail relay (host `postfix`) | + | `hass` | `hass-net` | Home Assistant integrations | + | `llama` | `llama-net` | local LLM servers and their clients | + | `prometheus` | `prometheus-net` | Prometheus and its exporters | + | `mdns` | `mdns-net` | mDNS relayed from the LAN | + + A private network for an app's own sidecars (Redis, its own database) is named `-net` or `-redis-net` and isn't external. +- **Host networking (`network_mode: host`) only when nothing else works**, for example a device that replies to a fixed UDP port on the host. Comment why next to it (`# hackstack: host networking required - ...`), and explain the consequences in the README (it reaches other services through their published host ports, and its own ports bind on the host). +- **When an app needs to look like a device on the LAN** (mDNS, broadcasts, AirPlay, Matter, DHCP/PXE, a stable LAN IP), use macvlan rather than host mode: keep bridge networking in `docker-compose.yml` and add a `docker-compose.macvlan.yml` overlay that attaches the external `lan_macvlan` network with `IPV4_ADDRESS` and `LAN_MAC_ADDRESS` from `.env`. See [docs/macvlan.md](docs/macvlan.md) and `apps/esphome` for the pattern. + +### Databases and Redis + +- **Use the shared PostgreSQL or MariaDB.** Never bundle a Postgres or MariaDB/MySQL service. Create the database with `../../apps/postgresql/bin/mkdb.sh ` (or the MariaDB equivalent), which creates `_db` / `_user`, prints the password and appends `BACKUP_DATABASE_URLS` to `.env`. +- Prefer PostgreSQL when the app supports both. When an app can only use SQLite, that's fine; document `BACKUP_DATABASE_URLS=sqlite:////opt/lib//...` for the real `.env`. +- **Redis is per app**: its own service, on its own private network, data in `../../lib//redis`. +- An app that needs a database the shared services can't provide (MongoDB for Komodo, for example) bundles it on a private network, and the README says why. + +## Overlays and COMPOSE_FILE + +Anything a deployment might want one way or the other is an overlay file next to `docker-compose.yml`, enabled from `.env`. Compose reads `COMPOSE_FILE` from `.env`, so a plain `docker compose up -d` picks it up. Tell users never to pass `-f docker-compose.yml`, which skips the overlays. + +| Overlay | Purpose | +|---------|---------| +| `docker-compose.nfs.yml` | Large data on an NFS export instead of `../../lib` (named volume with `driver_opts.type: nfs`, `*_NFS_HOST`/`*_NFS_PATH`/`NFS_MOUNT_OPTS` from `.env`, prefer `hard`) | +| `docker-compose.macvlan.yml` | Attach to `lan_macvlan` with a static LAN IP and MAC | +| `docker-compose..yml` | GPU backends (`nvidia`, `jetson`, `strix`, `arc`, ...) on a hardware-neutral base | +| `docker-compose.networks.yml` | Join the Hackstack networks (proxy, LLM, ...) | +| `docker-compose.ports.yml` | Publish the port on the host for servers with no reverse proxy (`PUBLISHED_ADDRESS`, `PUBLISHED_PORT`) | + +For a single overlay, `.env.example` has a commented line such as `# COMPOSE_FILE=docker-compose.yml:docker-compose.nfs.yml`. + +When an app has several independent choices, `.env.example` assembles `COMPOSE_FILE` from one variable per choice, so the user picks each one separately (see `apps/vllm`, `apps/llama-cpp`, `experiments/comfyui`): + +```bash +COMPOSE_HARDWARE=:docker-compose.nvidia.yml +COMPOSE_ACCESS=:docker-compose.networks.yml +COMPOSE_STORAGE= +COMPOSE_FILE=docker-compose.yml${COMPOSE_STORAGE}${COMPOSE_HARDWARE}${COMPOSE_ACCESS} +``` + +Put overlays that use `!override` before ones that add to the same key. After adding overlays, check each combination with `docker compose config -q`. + +## .env and .env.example + +- **Secrets are never committed.** Not in `.env.example`, not in compose files, not in `config/*.example`, not in READMEs or commit messages. `.env` and real config files are git-ignored per app. +- Every variable the compose file or app uses appears in `.env.example`, grouped under comment headers, with a one-line explanation where it isn't obvious. +- Secrets get a placeholder: ``, ``, or empty, plus how to generate one (`openssl rand -hex 32`). +- Optional features are commented out with their default value shown. +- Include `IMAGE_VERSION` (and any other image tag variables) and `TZ=America/Los_Angeles` when the app uses a timezone. +- Use container names for hosts on shared networks: `postgresql`, `mariadb`, `mosquitto`, `postfix`, `-redis`. +- **Never define `BACKUP_DATABASE_URLS` in `.env.example`**; `mkdb.sh` appends it. Keep the standard comment about it at the end of the file. +- Anything upstream's README documents should be configurable here, with a link to upstream's full reference. + +## config/ + +- Configuration files the app reads go in `config/` next to the compose file, never another directory name. Mount them read-only where the app allows. +- Commit an example (`config/.example`, or `.default` where the app already uses that) and git-ignore the real file in the app's `.gitignore`. +- Prefer environment variables in `.env` over config files when the app supports both. Keep config examples short and commented; don't paste upstream's whole default file unless it's needed. +- Credentials an app needs as files go under a git-ignored subdirectory such as `config/secrets/`. + +## README.md + +Start from [docs/app-readme-template.md](docs/app-readme-template.md). Every README has: + +- A title of the app name, with ` (experiment)` for experiments, and a sentence or two on what it does, linking upstream. +- For multi-service apps, a table of the services. +- **Configuration**: `cp .env.example .env`, a table of the variables that must be set, database creation (`mkdb.sh`), config files to copy, data directories to create and `chown`, and the proxy target (`:`). +- A section for each overlay the app ships and how to enable it in `.env`. +- Anything unusual and why (host networking, a bundled database, the Docker socket, published ports, no authentication). +- **Usage**: `docker compose up -d`, `docker compose down`, `docker compose logs -f`. + +Write plainly. Don't tell the user to edit compose files. + +## Backups + +- `../../lib/` is backed up file by file. Live database files there can't be copied safely while the app runs, so list them in the app's `.rsync.exclude` (paths relative to `/opt`, e.g. `lib/myapp/app.db`) and back them up with `BACKUP_DATABASE_URLS` or the app's own dump feature instead. +- Logs (`../../log`) and caches (`../../run`) aren't backed up. + +## Checking your work + +- `docker compose config -q` with `.env.example` copied to `.env` (delete the copy afterwards), for every overlay combination you touched. +- `.github/scripts/validate_compose.py` encodes the compose rules and runs in CI. +- `grep` the repo for the app's name and old paths when you add, move or rename one: `bin/install-*.sh`, `docs/`, other apps' READMEs and `experiments/prometheus/config/prometheus.yml.example`. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/apps/access-control-webhook/.rsync-exclude b/apps/access-control-webhook/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/adminer/.rsync-exclude b/apps/adminer/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/airconnect/.rsync-exclude b/apps/airconnect/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/authentik/.rsync-exclude b/apps/authentik/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/autogenerate-hosts/.rsync-exclude b/apps/autogenerate-hosts/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/backrest/.rsync-exclude b/apps/backrest/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/bfg-repo-cleaner/.rsync-exclude b/apps/bfg-repo-cleaner/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/caddy-home-assistant-liar/.rsync-exclude b/apps/caddy-home-assistant-liar/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/calibre-web/.rsync-exclude b/apps/calibre-web/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/cloudflare-ddns/.rsync-exclude b/apps/cloudflare-ddns/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/cups/.rsync-exclude b/apps/cups/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/cyberchef/.rsync-exclude b/apps/cyberchef/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/db-backup/.rsync-exclude b/apps/db-backup/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/dnsmasq/.rsync-exclude b/apps/dnsmasq/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/dozzle/.rsync-exclude b/apps/dozzle/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/esphome/.rsync-exclude b/apps/esphome/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/event-manager/.rsync-exclude b/apps/event-manager/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/geowiki/.rsync-exclude b/apps/geowiki/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/glances/.rsync-exclude b/apps/glances/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/glitchtip/.rsync-exclude b/apps/glitchtip/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/home-assistant/.rsync-exclude b/apps/home-assistant/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/invidious/.rsync-exclude b/apps/invidious/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/jellyfin/.rsync-exclude b/apps/jellyfin/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/llama-cpp/.env.example b/apps/llama-cpp/.env.example index bb26fee..44e6747 100644 --- a/apps/llama-cpp/.env.example +++ b/apps/llama-cpp/.env.example @@ -1,19 +1,40 @@ -# ==== hardware: pick exactly one COMPOSE_FILE line =========================== -# See README "Choosing compose files". Add :docker-compose.nfs.yml to the end of -# any line to keep models on NFS. +# ==== compose files =========================================================== +# COMPOSE_FILE is assembled from the three settings below; set those and leave +# COMPOSE_FILE itself alone. See README "Choosing compose files". +# --- hardware: pick exactly one COMPOSE_HARDWARE line --- # CPU only -COMPOSE_FILE=docker-compose.yml +COMPOSE_HARDWARE= # NVIDIA discrete GPUs, CUDA 12.8 (driver >= 570) -# COMPOSE_FILE=docker-compose.yml:docker-compose.nvidia.yml +# COMPOSE_HARDWARE=:docker-compose.nvidia.yml # NVIDIA DGX Spark (GB10), CUDA 13 -# COMPOSE_FILE=docker-compose.yml:docker-compose.nvidia.yml:docker-compose.spark.yml +# COMPOSE_HARDWARE=:docker-compose.nvidia.yml:docker-compose.spark.yml # NVIDIA Jetson Thor (uses the nvidia runtime instead of GPU reservations) -# COMPOSE_FILE=docker-compose.yml:docker-compose.jetson.yml +# COMPOSE_HARDWARE=:docker-compose.jetson.yml # AMD Strix Halo / Strix Point (Vulkan), x86_64 only -# COMPOSE_FILE=docker-compose.yml:docker-compose.strix.yml +# COMPOSE_HARDWARE=:docker-compose.strix.yml # Intel Arc (SYCL), x86_64 only -# COMPOSE_FILE=docker-compose.yml:docker-compose.arc.yml +# COMPOSE_HARDWARE=:docker-compose.arc.yml + +# --- access: how clients reach it --- +# Hackstack: join llama-net and nginx-proxy-net; reach it through the reverse proxy +COMPOSE_ACCESS=:docker-compose.networks.yml +# Standalone: publish port 8080 on the host, no reverse proxy +# COMPOSE_ACCESS=:docker-compose.ports.yml +# Both +# COMPOSE_ACCESS=:docker-compose.networks.yml:docker-compose.ports.yml +# Neither (only reachable from inside the container) +# COMPOSE_ACCESS= +# With docker-compose.ports.yml: host port, and the host address to bind +# (e.g. a LAN IP, or 127.0.0.1 for this machine only) +# PUBLISHED_PORT=8080 +# PUBLISHED_ADDRESS=0.0.0.0 + +# --- storage: GGUF models on NFS (see the NFS section at the end) --- +COMPOSE_STORAGE= +# COMPOSE_STORAGE=:docker-compose.nfs.yml + +COMPOSE_FILE=docker-compose.yml${COMPOSE_STORAGE}${COMPOSE_HARDWARE}${COMPOSE_ACCESS} # Full image tag. Leave unset: each compose file picks its own default # server (CPU), server-cuda, server-cuda13, server-vulkan, server-rocm, server-intel @@ -151,7 +172,7 @@ LLAMA_ARG_CTX_SIZE=4096 # 0 = the model's trained context # Multi-socket servers: # LLAMA_ARG_NUMA=distribute -# --- Optional: GGUF models on NFS (append :docker-compose.nfs.yml to COMPOSE_FILE) --- +# --- Optional: GGUF models on NFS (set COMPOSE_STORAGE above) --- # LLAMA_CPP_NFS_HOST= # LLAMA_CPP_NFS_PATH= # NFS_MOUNT_OPTS=nfsvers=4,hard diff --git a/apps/llama-cpp/.rsync-exclude b/apps/llama-cpp/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/llama-cpp/README.md b/apps/llama-cpp/README.md index 60b27ec..7e4b9ab 100644 --- a/apps/llama-cpp/README.md +++ b/apps/llama-cpp/README.md @@ -2,23 +2,25 @@ OpenAI-compatible local LLM inference server based on [llama.cpp](https://github.com/ggml-org/llama.cpp). Runs GGUF-format models -on CPU or GPU and exposes them as an OpenAI API endpoint on `llama-net`, +on CPU or GPU and exposes them as an OpenAI API endpoint on `llama-net` (or on +a published host port; see [Reaching the service](#reaching-the-service)), making it usable by [openwebui](../openwebui/) and [home-assistant](../home-assistant/) alongside [ollama](../ollama/). ## Choosing compose files -`docker-compose.yml` is hardware-neutral and runs the CPU image by itself. Pick -the hardware override with `COMPOSE_FILE` in `.env` (the `.env.example` lists every line): +`docker-compose.yml` is hardware-neutral and runs the CPU image by itself. Compose assembles `COMPOSE_FILE` in `.env` from three settings: `COMPOSE_HARDWARE` (below), `COMPOSE_ACCESS` (see [Reaching the service](#reaching-the-service)) and `COMPOSE_STORAGE` (NFS). Set those and leave the `COMPOSE_FILE` line alone; plain `docker compose up -d` then uses all three. -| Hardware | `COMPOSE_FILE` | Image tag | +Pick the hardware with `COMPOSE_HARDWARE` (the `.env.example` lists every line): + +| Hardware | `COMPOSE_HARDWARE` | Image tag | |----------|----------------|-----------| -| NVIDIA discrete GPUs (driver >= 570) | `docker-compose.yml:docker-compose.nvidia.yml` | `server-cuda` (CUDA 12.8) | -| NVIDIA DGX Spark (GB10) | `docker-compose.yml:docker-compose.nvidia.yml:docker-compose.spark.yml` | `server-cuda13` | -| NVIDIA Jetson Thor | `docker-compose.yml:docker-compose.jetson.yml` | `server-cuda13`, `nvidia` runtime | -| AMD Strix Halo / Strix Point | `docker-compose.yml:docker-compose.strix.yml` | `server-vulkan` | -| Intel Arc | `docker-compose.yml:docker-compose.arc.yml` | `server-intel` (SYCL) | -| CPU only | `docker-compose.yml` | `server` | +| NVIDIA discrete GPUs (driver >= 570) | `:docker-compose.nvidia.yml` | `server-cuda` (CUDA 12.8) | +| NVIDIA DGX Spark (GB10) | `:docker-compose.nvidia.yml:docker-compose.spark.yml` | `server-cuda13` | +| NVIDIA Jetson Thor | `:docker-compose.jetson.yml` | `server-cuda13`, `nvidia` runtime | +| AMD Strix Halo / Strix Point | `:docker-compose.strix.yml` | `server-vulkan` | +| Intel Arc | `:docker-compose.arc.yml` | `server-intel` (SYCL) | +| CPU only | *(empty)* | `server` | Notes: @@ -68,17 +70,30 @@ cp .env.example .env | `LLAMA_ARG_PORT` | Port inside the container | `8080` | | `IMAGE_VERSION` | Full image tag, overrides the compose file's default (see above) | per file | +## Reaching the service + +How clients reach llama-cpp is chosen with `COMPOSE_ACCESS` in `.env`, independently of the hardware: + +| `COMPOSE_ACCESS` | Effect | +|------------------|--------| +| `:docker-compose.networks.yml` | Joins `llama-net` and `nginx-proxy-net`. Other containers and the reverse proxy reach it as `llama-cpp:8080`. The default, for Hackstack servers. | +| `:docker-compose.ports.yml` | Publishes port 8080 on the host, for servers with no reverse proxy. `PUBLISHED_PORT` changes the host port and `PUBLISHED_ADDRESS` the address it binds (a LAN IP, or `127.0.0.1` for this machine only). | +| `:docker-compose.networks.yml:docker-compose.ports.yml` | Both. | +| *(empty)* | Neither; reachable only from inside the container. | + +The published port maps to `LLAMA_ARG_PORT` inside the container. + +`docker-compose.yml` itself has no networks and its `ports` are commented out, so nothing needs editing in any compose file. + ## Storage on NFS (optional) Large data defaults to bind mounts under `../../lib/` in `docker-compose.yml`. To use a NAS export instead, set in **`.env`** (see **`.env.example`**): ```bash -COMPOSE_FILE=docker-compose.yml:docker-compose.nvidia.yml:docker-compose.nfs.yml +COMPOSE_STORAGE=:docker-compose.nfs.yml ``` -(use your hardware line, with `docker-compose.nfs.yml` last) - -plus the `*_NFS_HOST`, `*_NFS_PATH`, and `NFS_MOUNT_OPTS` variables documented in `.env.example`. Compose reads `COMPOSE_FILE` from `.env`, so plain `docker compose up -d` picks up the override. +plus the `*_NFS_HOST`, `*_NFS_PATH`, and `NFS_MOUNT_OPTS` variables documented in `.env.example`. Prefer **`hard`** NFS mounts, not `soft`. Docker creates named NFS volumes on first start; if the server or export path is wrong, fix `.env` and remove the project volume before retrying (`docker volume ls`, then `docker volume rm …`). @@ -108,7 +123,7 @@ docker compose logs -f curl http://llama-cpp:8080/v1/models ``` -From outside the container network, use the host IP or reverse-proxy hostname. +From outside the container network, use the reverse-proxy hostname, or `http://:8080` with `docker-compose.ports.yml`. ## API compatibility diff --git a/apps/llama-cpp/docker-compose.arc.yml b/apps/llama-cpp/docker-compose.arc.yml index a97da34..b547dac 100644 --- a/apps/llama-cpp/docker-compose.arc.yml +++ b/apps/llama-cpp/docker-compose.arc.yml @@ -1,7 +1,7 @@ # Intel Arc (Battlemage B580 / Arc Pro B-series, Alchemist A-series) on Linux, # x86_64 only. Uses the SYCL (oneAPI) build; IMAGE_VERSION=server-vulkan also # works with this file. Needs the xe (or i915) kernel driver. -# COMPOSE_FILE=docker-compose.yml:docker-compose.arc.yml +# COMPOSE_HARDWARE=:docker-compose.arc.yml services: llama-cpp: restart: unless-stopped diff --git a/apps/llama-cpp/docker-compose.jetson.yml b/apps/llama-cpp/docker-compose.jetson.yml index d388c2a..0228623 100644 --- a/apps/llama-cpp/docker-compose.jetson.yml +++ b/apps/llama-cpp/docker-compose.jetson.yml @@ -1,7 +1,7 @@ # NVIDIA Jetson Thor (JetPack 7, arm64, CUDA 13). Use instead of docker-compose.nvidia.yml, # not on top of it: Jetson's container toolkit runs in CSV mode, which rejects device # reservations (the --gpus equivalent) and only works through the nvidia runtime. -# COMPOSE_FILE=docker-compose.yml:docker-compose.jetson.yml +# COMPOSE_HARDWARE=:docker-compose.jetson.yml services: llama-cpp: restart: unless-stopped diff --git a/apps/llama-cpp/docker-compose.networks.yml b/apps/llama-cpp/docker-compose.networks.yml new file mode 100644 index 0000000..8da7ec9 --- /dev/null +++ b/apps/llama-cpp/docker-compose.networks.yml @@ -0,0 +1,16 @@ +# Optional: attach to the Hackstack networks so the reverse proxy and other +# containers (openwebui, home-assistant, ...) reach it as llama-cpp:8080. +# Enabled through COMPOSE_ACCESS in .env (see .env.example). +services: + llama-cpp: + networks: + - llama + - proxy + +networks: + llama: + external: true + name: llama-net + proxy: + external: true + name: nginx-proxy-net diff --git a/apps/llama-cpp/docker-compose.nfs.yml b/apps/llama-cpp/docker-compose.nfs.yml index 3cb3c49..6e80161 100644 --- a/apps/llama-cpp/docker-compose.nfs.yml +++ b/apps/llama-cpp/docker-compose.nfs.yml @@ -1,6 +1,5 @@ # Optional override: GGUF models on NFS. -# Add it last in COMPOSE_FILE, e.g. -# COMPOSE_FILE=docker-compose.yml:docker-compose.nvidia.yml:docker-compose.nfs.yml +# Enabled through COMPOSE_STORAGE in .env. services: llama-cpp: diff --git a/apps/llama-cpp/docker-compose.nvidia.yml b/apps/llama-cpp/docker-compose.nvidia.yml index 6afd125..4a884bc 100644 --- a/apps/llama-cpp/docker-compose.nvidia.yml +++ b/apps/llama-cpp/docker-compose.nvidia.yml @@ -1,7 +1,7 @@ # NVIDIA discrete GPUs on Linux (x86_64 or arm64), CUDA 12.8 (driver >= 570). # For driver >= 580 you can set IMAGE_VERSION=server-cuda13 instead. # DGX Spark: also add docker-compose.spark.yml. Jetson Thor: use docker-compose.jetson.yml. -# COMPOSE_FILE=docker-compose.yml:docker-compose.nvidia.yml +# COMPOSE_HARDWARE=:docker-compose.nvidia.yml services: llama-cpp: restart: unless-stopped diff --git a/apps/llama-cpp/docker-compose.ports.yml b/apps/llama-cpp/docker-compose.ports.yml new file mode 100644 index 0000000..8bdde1f --- /dev/null +++ b/apps/llama-cpp/docker-compose.ports.yml @@ -0,0 +1,6 @@ +# Optional: publish the port on the host, for servers without a reverse proxy. +# Enabled through COMPOSE_ACCESS in .env (see .env.example). +services: + llama-cpp: + ports: + - "${PUBLISHED_ADDRESS:-0.0.0.0}:${PUBLISHED_PORT:-8080}:${LLAMA_ARG_PORT:-8080}" diff --git a/apps/llama-cpp/docker-compose.spark.yml b/apps/llama-cpp/docker-compose.spark.yml index 48f9ed4..68d825e 100644 --- a/apps/llama-cpp/docker-compose.spark.yml +++ b/apps/llama-cpp/docker-compose.spark.yml @@ -1,5 +1,5 @@ # NVIDIA DGX Spark (GB10, arm64, sm_121): the CUDA 13 build. Layer on nvidia.yml: -# COMPOSE_FILE=docker-compose.yml:docker-compose.nvidia.yml:docker-compose.spark.yml +# COMPOSE_HARDWARE=:docker-compose.nvidia.yml:docker-compose.spark.yml services: llama-cpp: restart: unless-stopped diff --git a/apps/llama-cpp/docker-compose.strix.yml b/apps/llama-cpp/docker-compose.strix.yml index f1706b0..2d44181 100644 --- a/apps/llama-cpp/docker-compose.strix.yml +++ b/apps/llama-cpp/docker-compose.strix.yml @@ -2,7 +2,7 @@ # on Linux, x86_64 only. Uses the Vulkan (RADV) build, which is the fastest and # least fussy llama.cpp backend on these APUs; the host only needs the amdgpu # kernel driver. IMAGE_VERSION=server-rocm also works with this file. -# COMPOSE_FILE=docker-compose.yml:docker-compose.strix.yml +# COMPOSE_HARDWARE=:docker-compose.strix.yml services: llama-cpp: restart: unless-stopped diff --git a/apps/llama-cpp/docker-compose.yml b/apps/llama-cpp/docker-compose.yml index 5536bb4..26bf551 100644 --- a/apps/llama-cpp/docker-compose.yml +++ b/apps/llama-cpp/docker-compose.yml @@ -1,10 +1,13 @@ # Hardware-neutral base. On its own this runs the CPU-only image; layer one of -# the hardware overrides on top via COMPOSE_FILE in .env (see README): +# the hardware overrides on top via COMPOSE_HARDWARE in .env (see README): # docker-compose.nvidia.yml NVIDIA discrete GPUs, CUDA 12.8 (driver >= 570) # docker-compose.spark.yml DGX Spark (GB10), CUDA 13, on top of nvidia.yml # docker-compose.jetson.yml NVIDIA Jetson Thor (nvidia runtime, instead of nvidia.yml) # docker-compose.strix.yml AMD Strix Halo / Strix Point APUs (Vulkan), x86_64 only # docker-compose.arc.yml Intel Arc (SYCL), x86_64 only +# and how clients reach it: +# docker-compose.networks.yml join llama-net and nginx-proxy-net (Hackstack) +# docker-compose.ports.yml publish the port on the host (no reverse proxy) services: llama-cpp: image: ghcr.io/ggml-org/llama.cpp:${IMAGE_VERSION:-server} @@ -27,14 +30,3 @@ services: start_period: 30s # ports: # - 8080:8080 - networks: - - llama - - proxy - -networks: - llama: - external: true - name: llama-net - proxy: - external: true - name: nginx-proxy-net diff --git a/apps/mariadb/.rsync-exclude b/apps/mariadb/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/matomo/.rsync-exclude b/apps/matomo/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/matter/.rsync-exclude b/apps/matter/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/mdns-repeater/.rsync-exclude b/apps/mdns-repeater/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/member-zone/.rsync-exclude b/apps/member-zone/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/mosquitto-management-center/.rsync-exclude b/apps/mosquitto-management-center/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/mosquitto/.rsync-exclude b/apps/mosquitto/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/mqtt-explorer/.rsync-exclude b/apps/mqtt-explorer/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/music-assistant/.rsync-exclude b/apps/music-assistant/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/netboot/.rsync-exclude b/apps/netboot/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/nginx-proxy-manager/.rsync-exclude b/apps/nginx-proxy-manager/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/ollama/.rsync-exclude b/apps/ollama/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/openwebui/.rsync-exclude b/apps/openwebui/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/partdb/.rsync-exclude b/apps/partdb/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/peanut/.rsync-exclude b/apps/peanut/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/piper/.rsync-exclude b/apps/piper/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/planka/.rsync-exclude b/apps/planka/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/postfix/.rsync-exclude b/apps/postfix/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/postgresql/.rsync-exclude b/apps/postgresql/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/rsyslog/.rsync-exclude b/apps/rsyslog/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/sensors2mqtt/.rsync-exclude b/apps/sensors2mqtt/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/shairport-metadata-display/.rsync-exclude b/apps/shairport-metadata-display/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/shairport-sync/.rsync-exclude b/apps/shairport-sync/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/statping/.rsync-exclude b/apps/statping/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/upsd/.rsync-exclude b/apps/upsd/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/vaultwarden/.rsync-exclude b/apps/vaultwarden/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/vllm/.env.example b/apps/vllm/.env.example index ff3f390..c4306a0 100644 --- a/apps/vllm/.env.example +++ b/apps/vllm/.env.example @@ -1,19 +1,40 @@ -# ==== hardware: pick exactly one COMPOSE_FILE line =========================== -# See README "Choosing compose files". Add :docker-compose.nfs.yml to the end of -# any line to keep the Hugging Face cache on NFS (Intel Arc: see arc.yml). +# ==== compose files =========================================================== +# COMPOSE_FILE is assembled from the three settings below; set those and leave +# COMPOSE_FILE itself alone. See README "Choosing compose files". +# --- hardware: pick exactly one COMPOSE_HARDWARE line --- # NVIDIA discrete GPUs and DGX Spark, CUDA 13 (driver >= 580) -COMPOSE_FILE=docker-compose.yml:docker-compose.nvidia.yml +COMPOSE_HARDWARE=:docker-compose.nvidia.yml # NVIDIA DGX Spark with the community GB10 build -# COMPOSE_FILE=docker-compose.yml:docker-compose.nvidia.yml:docker-compose.spark.yml +# COMPOSE_HARDWARE=:docker-compose.nvidia.yml:docker-compose.spark.yml # NVIDIA Jetson Thor (uses the nvidia runtime instead of GPU reservations) -# COMPOSE_FILE=docker-compose.yml:docker-compose.jetson.yml +# COMPOSE_HARDWARE=:docker-compose.jetson.yml # AMD Strix Halo / Strix Point (ROCm), x86_64 only -# COMPOSE_FILE=docker-compose.yml:docker-compose.strix.yml +# COMPOSE_HARDWARE=:docker-compose.strix.yml # Intel Arc (XPU), x86_64 only -# COMPOSE_FILE=docker-compose.yml:docker-compose.arc.yml +# COMPOSE_HARDWARE=:docker-compose.arc.yml # CPU only (x86_64 with AVX-512 recommended, or arm64); slow, mainly for testing -# COMPOSE_FILE=docker-compose.yml +# COMPOSE_HARDWARE= + +# --- access: how clients reach it --- +# Hackstack: join llama-net and nginx-proxy-net; reach it through the reverse proxy +COMPOSE_ACCESS=:docker-compose.networks.yml +# Standalone: publish port 8000 on the host, no reverse proxy +# COMPOSE_ACCESS=:docker-compose.ports.yml +# Both +# COMPOSE_ACCESS=:docker-compose.networks.yml:docker-compose.ports.yml +# Neither (only reachable from inside the container) +# COMPOSE_ACCESS= +# With docker-compose.ports.yml: host port, and the host address to bind +# (e.g. a LAN IP, or 127.0.0.1 for this machine only) +# PUBLISHED_PORT=8000 +# PUBLISHED_ADDRESS=0.0.0.0 + +# --- storage: Hugging Face cache on NFS (see the NFS section at the end) --- +COMPOSE_STORAGE= +# COMPOSE_STORAGE=:docker-compose.nfs.yml + +COMPOSE_FILE=docker-compose.yml${COMPOSE_STORAGE}${COMPOSE_HARDWARE}${COMPOSE_ACCESS} # ==== model =================================================================== # Required: Hugging Face model id, or a path to weights visible inside the container @@ -128,7 +149,7 @@ VLLM_MODEL=meta-llama/Llama-3.2-3B-Instruct # float16 is unstable on CPU; bfloat16 is the recommended dtype # VLLM_ARGS=--dtype bfloat16 --max-model-len 4096 --max-num-seqs 4 -# --- Optional: Hugging Face cache on NFS (append :docker-compose.nfs.yml to COMPOSE_FILE) --- +# --- Optional: Hugging Face cache on NFS (set COMPOSE_STORAGE above) --- # VLLM_NFS_HOST= # VLLM_NFS_PATH= # NFS_MOUNT_OPTS=nfsvers=4,hard diff --git a/apps/vllm/README.md b/apps/vllm/README.md index 15a9fb6..6cd9586 100644 --- a/apps/vllm/README.md +++ b/apps/vllm/README.md @@ -2,7 +2,7 @@ OpenAI-compatible LLM serving using [vLLM](https://docs.vllm.ai/) (`vllm serve`). Models are loaded from [Hugging Face](https://huggingface.co/) (or local paths you mount) with weights cached under `../../lib/vllm/huggingface` on the host, mapped to `/root/.cache/huggingface` in the container. -The service is attached to `llama-net` (and `nginx-proxy-net`) on port **8000** inside the container, similar to [llama-cpp](../llama-cpp/) and [ollama](../ollama/) for use with [openwebui](../openwebui/) and other clients. +It serves on port **8000**, either on `llama-net` and `nginx-proxy-net` or published on the host (see [Reaching the service](#reaching-the-service)), similar to [llama-cpp](../llama-cpp/) and [ollama](../ollama/) for use with [openwebui](../openwebui/) and other clients. ## Configuration @@ -23,17 +23,18 @@ cp .env.example .env ## Choosing compose files -`docker-compose.yml` is hardware-neutral and runs the CPU image by itself. Pick -the hardware override with `COMPOSE_FILE` in `.env` (the `.env.example` lists every line): +`docker-compose.yml` is hardware-neutral and runs the CPU image by itself. Compose assembles `COMPOSE_FILE` in `.env` from three settings: `COMPOSE_HARDWARE` (below), `COMPOSE_ACCESS` (see [Reaching the service](#reaching-the-service)) and `COMPOSE_STORAGE` (NFS). Set those and leave the `COMPOSE_FILE` line alone; plain `docker compose up -d` then uses all three. -| Hardware | `COMPOSE_FILE` | Image | +Pick the hardware with `COMPOSE_HARDWARE` (the `.env.example` lists every line): + +| Hardware | `COMPOSE_HARDWARE` | Image | |----------|----------------|-------| -| NVIDIA discrete GPUs, DGX Spark (GB10) | `docker-compose.yml:docker-compose.nvidia.yml` | `vllm/vllm-openai` (CUDA 13) | -| DGX Spark, community GB10 build | `docker-compose.yml:docker-compose.nvidia.yml:docker-compose.spark.yml` | `ghcr.io/spark-arena/dgx-vllm-eugr-nightly` | -| NVIDIA Jetson Thor | `docker-compose.yml:docker-compose.jetson.yml` | `vllm/vllm-openai`, `nvidia` runtime | -| AMD Strix Halo / Strix Point | `docker-compose.yml:docker-compose.strix.yml` | `vllm/vllm-openai-rocm` | -| Intel Arc | `docker-compose.yml:docker-compose.arc.yml` | `vllm/vllm-openai-xpu` | -| CPU only | `docker-compose.yml` | `vllm/vllm-openai-cpu` | +| NVIDIA discrete GPUs, DGX Spark (GB10) | `:docker-compose.nvidia.yml` | `vllm/vllm-openai` (CUDA 13) | +| DGX Spark, community GB10 build | `:docker-compose.nvidia.yml:docker-compose.spark.yml` | `ghcr.io/spark-arena/dgx-vllm-eugr-nightly` | +| NVIDIA Jetson Thor | `:docker-compose.jetson.yml` | `vllm/vllm-openai`, `nvidia` runtime | +| AMD Strix Halo / Strix Point | `:docker-compose.strix.yml` | `vllm/vllm-openai-rocm` | +| Intel Arc | `:docker-compose.arc.yml` | `vllm/vllm-openai-xpu` | +| CPU only | *(empty)* | `vllm/vllm-openai-cpu` | `.env.example` has tuned, commented-out settings for each platform, including a `VLLM_ARGS` line per platform; uncomment the block for your hardware (only one `VLLM_ARGS` line). @@ -44,9 +45,22 @@ Notes: - **Spark and Thor** share CPU and GPU memory, so lower `--gpu-memory-utilization` in `VLLM_ARGS` to leave room for the OS and other services. - **Jetson Thor**: the stock arm64 CUDA 13 image includes sm_110 kernels. The toolkit runs in CSV mode there and rejects GPU reservations, so `jetson.yml` uses `runtime: nvidia` and replaces `nvidia.yml` rather than layering on it. - **Strix**: vLLM supports Ryzen AI Max (gfx1151) and Ryzen AI 300 (gfx1150) on ROCm >= 7.0.2, which the official ROCm image bundles. Expect fewer optimized kernels than on Instinct or Radeon cards. -- **Intel Arc**: Battlemage (B580, Arc Pro B-series) is what Intel tests; Alchemist may work but is slow. Needs Intel compute runtime >= 26.18 on the host. Upstream's example runs the container privileged; uncomment `privileged: true` in `arc.yml` if no XPU device is found. With NFS, put `docker-compose.nfs.yml` before `arc.yml` so the `/dev/dri/by-path` mount survives. +- **Intel Arc**: Battlemage (B580, Arc Pro B-series) is what Intel tests; Alchemist may work but is slow. Needs Intel compute runtime >= 26.18 on the host. Upstream's example runs the container privileged; uncomment `privileged: true` in `arc.yml` if no XPU device is found. - **CPU**: works on x86_64 (AVX-512 recommended, AVX2 limited) and arm64, but is slow; it is mainly useful for testing. Size the KV cache with `VLLM_CPU_KVCACHE_SPACE` (GB). For real CPU inference in this stack, use [llama-cpp](../llama-cpp/) or [ollama](../ollama/). +## Reaching the service + +How clients reach vllm is chosen with `COMPOSE_ACCESS` in `.env`, independently of the hardware: + +| `COMPOSE_ACCESS` | Effect | +|------------------|--------| +| `:docker-compose.networks.yml` | Joins `llama-net` and `nginx-proxy-net`. Other containers and the reverse proxy reach it as `vllm:8000`. The default, for Hackstack servers. | +| `:docker-compose.ports.yml` | Publishes port 8000 on the host, for servers with no reverse proxy. `PUBLISHED_PORT` changes the host port and `PUBLISHED_ADDRESS` the address it binds (a LAN IP, or `127.0.0.1` for this machine only). | +| `:docker-compose.networks.yml:docker-compose.ports.yml` | Both. | +| *(empty)* | Neither; reachable only from inside the container. | + +`docker-compose.yml` itself has no networks and its `ports` are commented out, so nothing needs editing in any compose file. + ## Starting and stopping ```bash @@ -58,13 +72,13 @@ Logs: `docker compose logs -f` ## Health and API -The healthcheck calls `http://127.0.0.1:8000/v1/models`. Expose port 8000 or use a reverse proxy on `nginx-proxy-net` to reach the service. Example: +The healthcheck calls `http://127.0.0.1:8000/v1/models`. From another container on `llama-net` or the proxy network: ```bash curl -sS http://vllm:8000/v1/models ``` -(From another container on `llama-net` or the proxy network.) +With `docker-compose.ports.yml`, use `http://:8000/v1/models` instead. ## Notes @@ -76,11 +90,9 @@ curl -sS http://vllm:8000/v1/models Large data defaults to bind mounts under `../../lib/` in `docker-compose.yml`. To use a NAS export instead, set in **`.env`** (see **`.env.example`**): ```bash -COMPOSE_FILE=docker-compose.yml:docker-compose.nvidia.yml:docker-compose.nfs.yml +COMPOSE_STORAGE=:docker-compose.nfs.yml ``` -(use your hardware line, with `docker-compose.nfs.yml` last, except on Intel Arc) - -plus the `*_NFS_HOST`, `*_NFS_PATH`, and `NFS_MOUNT_OPTS` variables documented in `.env.example`. Compose reads `COMPOSE_FILE` from `.env`, so plain `docker compose up -d` picks up the override. +plus the `*_NFS_HOST`, `*_NFS_PATH`, and `NFS_MOUNT_OPTS` variables documented in `.env.example`. `COMPOSE_FILE` puts the NFS file before the hardware file, so the Intel Arc `/dev/dri/by-path` mount survives its volume override. Prefer **`hard`** NFS mounts, not `soft`. Docker creates named NFS volumes on first start; if the server or export path is wrong, fix `.env` and remove the project volume before retrying (`docker volume ls`, then `docker volume rm …`). diff --git a/apps/vllm/docker-compose.arc.yml b/apps/vllm/docker-compose.arc.yml index 0d707e0..d4aae56 100644 --- a/apps/vllm/docker-compose.arc.yml +++ b/apps/vllm/docker-compose.arc.yml @@ -1,9 +1,7 @@ # Intel Arc on Linux, x86_64 only, via vLLM's XPU backend. Battlemage (B580, # Arc Pro B-series) is what Intel tests; Alchemist (A-series) may work but is slow. # Needs the xe kernel driver and Intel compute runtime >= 26.18 on the host. -# With NFS, put docker-compose.nfs.yml before this file so the by-path mount survives: -# COMPOSE_FILE=docker-compose.yml:docker-compose.arc.yml -# COMPOSE_FILE=docker-compose.yml:docker-compose.nfs.yml:docker-compose.arc.yml +# COMPOSE_HARDWARE=:docker-compose.arc.yml services: vllm: restart: unless-stopped diff --git a/apps/vllm/docker-compose.jetson.yml b/apps/vllm/docker-compose.jetson.yml index 63de77e..19edcd6 100644 --- a/apps/vllm/docker-compose.jetson.yml +++ b/apps/vllm/docker-compose.jetson.yml @@ -2,7 +2,7 @@ # includes Thor kernels. Use instead of docker-compose.nvidia.yml, not on top of it: # Jetson's container toolkit runs in CSV mode, which rejects device reservations # (the --gpus equivalent) and only works through the nvidia runtime. -# COMPOSE_FILE=docker-compose.yml:docker-compose.jetson.yml +# COMPOSE_HARDWARE=:docker-compose.jetson.yml services: vllm: restart: unless-stopped diff --git a/apps/vllm/docker-compose.networks.yml b/apps/vllm/docker-compose.networks.yml new file mode 100644 index 0000000..510eeb0 --- /dev/null +++ b/apps/vllm/docker-compose.networks.yml @@ -0,0 +1,16 @@ +# Optional: attach to the Hackstack networks so the reverse proxy and other +# containers (openwebui, home-assistant, ...) reach it as vllm:8000. +# Enabled through COMPOSE_ACCESS in .env (see .env.example). +services: + vllm: + networks: + - llama + - proxy + +networks: + llama: + external: true + name: llama-net + proxy: + external: true + name: nginx-proxy-net diff --git a/apps/vllm/docker-compose.nfs.yml b/apps/vllm/docker-compose.nfs.yml index 62064a9..fb40246 100644 --- a/apps/vllm/docker-compose.nfs.yml +++ b/apps/vllm/docker-compose.nfs.yml @@ -1,6 +1,6 @@ # Optional override: Hugging Face model cache on NFS; vLLM cache stays local. -# Add it last in COMPOSE_FILE, e.g. -# COMPOSE_FILE=docker-compose.yml:docker-compose.nvidia.yml:docker-compose.nfs.yml +# Enabled through COMPOSE_STORAGE in .env, which puts it before the hardware file +# so arc.yml's by-path mount survives the volume override. services: vllm: diff --git a/apps/vllm/docker-compose.nvidia.yml b/apps/vllm/docker-compose.nvidia.yml index 43d275e..059a9f1 100644 --- a/apps/vllm/docker-compose.nvidia.yml +++ b/apps/vllm/docker-compose.nvidia.yml @@ -2,7 +2,7 @@ # Not for Jetson Thor; use docker-compose.jetson.yml there. # Needs the NVIDIA Container Toolkit on the host and driver >= 580 for CUDA 13; # for an older driver (>= 575) pin a CUDA 12.9 build, e.g. IMAGE_VERSION=v0.32.0-cu129. -# COMPOSE_FILE=docker-compose.yml:docker-compose.nvidia.yml +# COMPOSE_HARDWARE=:docker-compose.nvidia.yml services: vllm: restart: unless-stopped diff --git a/apps/vllm/docker-compose.ports.yml b/apps/vllm/docker-compose.ports.yml new file mode 100644 index 0000000..41b2359 --- /dev/null +++ b/apps/vllm/docker-compose.ports.yml @@ -0,0 +1,6 @@ +# Optional: publish the port on the host, for servers without a reverse proxy. +# Enabled through COMPOSE_ACCESS in .env (see .env.example). +services: + vllm: + ports: + - "${PUBLISHED_ADDRESS:-0.0.0.0}:${PUBLISHED_PORT:-8000}:8000" diff --git a/apps/vllm/docker-compose.spark.yml b/apps/vllm/docker-compose.spark.yml index 1ae9424..69cfbc3 100644 --- a/apps/vllm/docker-compose.spark.yml +++ b/apps/vllm/docker-compose.spark.yml @@ -1,7 +1,7 @@ # NVIDIA DGX Spark (GB10): optional community build tuned for GB10 (NVFP4, MoE # kernels). The stock vllm/vllm-openai image from nvidia.yml also runs on Spark; # use this when you want the Spark-specific kernels. Layer on nvidia.yml: -# COMPOSE_FILE=docker-compose.yml:docker-compose.nvidia.yml:docker-compose.spark.yml +# COMPOSE_HARDWARE=:docker-compose.nvidia.yml:docker-compose.spark.yml services: vllm: restart: unless-stopped diff --git a/apps/vllm/docker-compose.strix.yml b/apps/vllm/docker-compose.strix.yml index b9ba9fd..68fbdb8 100644 --- a/apps/vllm/docker-compose.strix.yml +++ b/apps/vllm/docker-compose.strix.yml @@ -1,7 +1,7 @@ # AMD Strix Halo (Ryzen AI Max, gfx1151) and Strix Point (Ryzen AI 300, gfx1150) # on Linux, x86_64 only. The official ROCm image ships gfx1150/gfx1151 kernels # (ROCm >= 7.0.2); the host only needs the amdgpu kernel driver. -# COMPOSE_FILE=docker-compose.yml:docker-compose.strix.yml +# COMPOSE_HARDWARE=:docker-compose.strix.yml services: vllm: restart: unless-stopped diff --git a/apps/vllm/docker-compose.yml b/apps/vllm/docker-compose.yml index f930307..ec2ba9d 100644 --- a/apps/vllm/docker-compose.yml +++ b/apps/vllm/docker-compose.yml @@ -1,10 +1,13 @@ # Hardware-neutral base. On its own this runs the CPU-only image; layer one of -# the hardware overrides on top via COMPOSE_FILE in .env (see README): +# the hardware overrides on top via COMPOSE_HARDWARE in .env (see README): # docker-compose.nvidia.yml NVIDIA discrete GPUs and DGX Spark, CUDA 13 (driver >= 580) # docker-compose.spark.yml DGX Spark community build, on top of nvidia.yml (optional) # docker-compose.jetson.yml NVIDIA Jetson Thor (nvidia runtime, instead of nvidia.yml) # docker-compose.strix.yml AMD Strix Halo / Strix Point APUs (ROCm), x86_64 only # docker-compose.arc.yml Intel Arc (XPU), x86_64 only +# and how clients reach it: +# docker-compose.networks.yml join llama-net and nginx-proxy-net (Hackstack) +# docker-compose.ports.yml publish the port on the host (no reverse proxy) services: vllm: image: vllm/vllm-openai-cpu:${IMAGE_VERSION:-latest} @@ -19,22 +22,11 @@ services: entrypoint: ["/bin/sh", "/vllm-entrypoint.sh"] env_file: - .env - ports: - - 8000:8000 +# ports: +# - 8000:8000 healthcheck: test: ["CMD-SHELL", "curl -fSs http://127.0.0.1:8000/v1/models >/dev/null || exit 1"] interval: 30s timeout: 10s retries: 3 start_period: 300s -# networks: -# - llama -# - proxy - -networks: - llama: - external: true - name: llama-net - proxy: - external: true - name: nginx-proxy-net diff --git a/apps/watchtower/.rsync-exclude b/apps/watchtower/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/weather/.rsync-exclude b/apps/weather/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/whisper/.rsync-exclude b/apps/whisper/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/wiki/.rsync-exclude b/apps/wiki/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/z-wavejs/.rsync-exclude b/apps/z-wavejs/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/apps/zigbee2mqtt/.rsync-exclude b/apps/zigbee2mqtt/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/bin/install-chaos.sh b/bin/install-chaos.sh index 3e47537..54b915f 100755 --- a/bin/install-chaos.sh +++ b/bin/install-chaos.sh @@ -48,7 +48,6 @@ esac # member-manager needs: proxy, db, mail # partdb needs: proxy, db # planka needs: proxy, db -# statping needs: proxy, db # vaultwarden needs: proxy, db # matomo creates: matomo-net needs: proxy, mariadb # mosquitto-management-center needs: proxy, mqtt @@ -91,7 +90,6 @@ invidious member-manager partdb planka -statping vaultwarden matomo mosquitto-management-center diff --git a/experiments/camera2prusa/.env.example b/deprecated/camera2prusa/.env.example similarity index 100% rename from experiments/camera2prusa/.env.example rename to deprecated/camera2prusa/.env.example diff --git a/experiments/camera2prusa/README.md b/deprecated/camera2prusa/README.md similarity index 100% rename from experiments/camera2prusa/README.md rename to deprecated/camera2prusa/README.md diff --git a/experiments/camera2prusa/docker-compose.yml b/deprecated/camera2prusa/docker-compose.yml similarity index 100% rename from experiments/camera2prusa/docker-compose.yml rename to deprecated/camera2prusa/docker-compose.yml diff --git a/experiments/chronograf/.env.example b/deprecated/chronograf/.env.example similarity index 100% rename from experiments/chronograf/.env.example rename to deprecated/chronograf/.env.example diff --git a/experiments/chronograf/README.md b/deprecated/chronograf/README.md similarity index 100% rename from experiments/chronograf/README.md rename to deprecated/chronograf/README.md diff --git a/experiments/chronograf/docker-compose.yml b/deprecated/chronograf/docker-compose.yml similarity index 100% rename from experiments/chronograf/docker-compose.yml rename to deprecated/chronograf/docker-compose.yml diff --git a/deprecated/frigate/.rsync-exclude b/deprecated/frigate/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/experiments/homebox/.env.example b/deprecated/homebox/.env.example similarity index 100% rename from experiments/homebox/.env.example rename to deprecated/homebox/.env.example diff --git a/experiments/homebox/.gitignore b/deprecated/homebox/.gitignore similarity index 100% rename from experiments/homebox/.gitignore rename to deprecated/homebox/.gitignore diff --git a/experiments/homebox/README.md b/deprecated/homebox/README.md similarity index 100% rename from experiments/homebox/README.md rename to deprecated/homebox/README.md diff --git a/experiments/homebox/config/config.yml.default b/deprecated/homebox/config/config.yml.default similarity index 100% rename from experiments/homebox/config/config.yml.default rename to deprecated/homebox/config/config.yml.default diff --git a/experiments/homebox/docker-compose.yml b/deprecated/homebox/docker-compose.yml similarity index 100% rename from experiments/homebox/docker-compose.yml rename to deprecated/homebox/docker-compose.yml diff --git a/experiments/influxdb/.env.example b/deprecated/influxdb/.env.example similarity index 100% rename from experiments/influxdb/.env.example rename to deprecated/influxdb/.env.example diff --git a/experiments/influxdb/.gitignore b/deprecated/influxdb/.gitignore similarity index 100% rename from experiments/influxdb/.gitignore rename to deprecated/influxdb/.gitignore diff --git a/experiments/influxdb/.rsync.exclude b/deprecated/influxdb/.rsync.exclude similarity index 100% rename from experiments/influxdb/.rsync.exclude rename to deprecated/influxdb/.rsync.exclude diff --git a/experiments/influxdb/README.md b/deprecated/influxdb/README.md similarity index 100% rename from experiments/influxdb/README.md rename to deprecated/influxdb/README.md diff --git a/experiments/influxdb/config/.gitkeep b/deprecated/influxdb/config/.gitkeep similarity index 100% rename from experiments/influxdb/config/.gitkeep rename to deprecated/influxdb/config/.gitkeep diff --git a/experiments/influxdb/docker-compose.yml b/deprecated/influxdb/docker-compose.yml similarity index 100% rename from experiments/influxdb/docker-compose.yml rename to deprecated/influxdb/docker-compose.yml diff --git a/deprecated/mopidy/.rsync-exclude b/deprecated/mopidy/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/deprecated/openwakeword/.rsync-exclude b/deprecated/openwakeword/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/experiments/osticket/.env.example b/deprecated/osticket/.env.example similarity index 100% rename from experiments/osticket/.env.example rename to deprecated/osticket/.env.example diff --git a/experiments/osticket/README.md b/deprecated/osticket/README.md similarity index 100% rename from experiments/osticket/README.md rename to deprecated/osticket/README.md diff --git a/experiments/osticket/docker-compose.yml b/deprecated/osticket/docker-compose.yml similarity index 100% rename from experiments/osticket/docker-compose.yml rename to deprecated/osticket/docker-compose.yml diff --git a/experiments/portainer/.env.example b/deprecated/portainer/.env.example similarity index 100% rename from experiments/portainer/.env.example rename to deprecated/portainer/.env.example diff --git a/experiments/portainer/README.md b/deprecated/portainer/README.md similarity index 100% rename from experiments/portainer/README.md rename to deprecated/portainer/README.md diff --git a/experiments/portainer/docker-compose.yml b/deprecated/portainer/docker-compose.yml similarity index 100% rename from experiments/portainer/docker-compose.yml rename to deprecated/portainer/docker-compose.yml diff --git a/deprecated/snapclient/.rsync-exclude b/deprecated/snapclient/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/deprecated/snapserver/.rsync-exclude b/deprecated/snapserver/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/experiments/stable-diffusion-webui/.env.example b/deprecated/stable-diffusion-webui/.env.example similarity index 100% rename from experiments/stable-diffusion-webui/.env.example rename to deprecated/stable-diffusion-webui/.env.example diff --git a/experiments/stable-diffusion-webui/README.md b/deprecated/stable-diffusion-webui/README.md similarity index 100% rename from experiments/stable-diffusion-webui/README.md rename to deprecated/stable-diffusion-webui/README.md diff --git a/experiments/stable-diffusion-webui/docker-compose.nfs.yml b/deprecated/stable-diffusion-webui/docker-compose.nfs.yml similarity index 100% rename from experiments/stable-diffusion-webui/docker-compose.nfs.yml rename to deprecated/stable-diffusion-webui/docker-compose.nfs.yml diff --git a/experiments/stable-diffusion-webui/docker-compose.yml b/deprecated/stable-diffusion-webui/docker-compose.yml similarity index 100% rename from experiments/stable-diffusion-webui/docker-compose.yml rename to deprecated/stable-diffusion-webui/docker-compose.yml diff --git a/apps/statping/.env.example b/deprecated/statping/.env.example similarity index 100% rename from apps/statping/.env.example rename to deprecated/statping/.env.example diff --git a/apps/statping/README.md b/deprecated/statping/README.md similarity index 100% rename from apps/statping/README.md rename to deprecated/statping/README.md diff --git a/apps/statping/docker-compose.yml b/deprecated/statping/docker-compose.yml similarity index 100% rename from apps/statping/docker-compose.yml rename to deprecated/statping/docker-compose.yml diff --git a/experiments/telegraf/.env.example b/deprecated/telegraf/.env.example similarity index 100% rename from experiments/telegraf/.env.example rename to deprecated/telegraf/.env.example diff --git a/experiments/telegraf/.gitignore b/deprecated/telegraf/.gitignore similarity index 100% rename from experiments/telegraf/.gitignore rename to deprecated/telegraf/.gitignore diff --git a/experiments/telegraf/README.md b/deprecated/telegraf/README.md similarity index 100% rename from experiments/telegraf/README.md rename to deprecated/telegraf/README.md diff --git a/experiments/telegraf/config/telegraf.conf.example b/deprecated/telegraf/config/telegraf.conf.example similarity index 100% rename from experiments/telegraf/config/telegraf.conf.example rename to deprecated/telegraf/config/telegraf.conf.example diff --git a/experiments/telegraf/docker-compose.yml b/deprecated/telegraf/docker-compose.yml similarity index 100% rename from experiments/telegraf/docker-compose.yml rename to deprecated/telegraf/docker-compose.yml diff --git a/docs/apps-compose-healthchecks.md b/docs/apps-compose-healthchecks.md index 33878ca..a56d76c 100644 --- a/docs/apps-compose-healthchecks.md +++ b/docs/apps-compose-healthchecks.md @@ -28,7 +28,6 @@ This document complements the healthchecks defined under `apps/*/docker-compose. | **partdb** | HTTP `:80` | | | **weather** | `wget --spider` nginx `:80` | | | **llama-cpp** | HTTP `/health` or `/v1/models` | Matches common `llama-server` layouts. | -| **statping** | HTTP `:8080` | | | **peanut** | Image default: `node healthcheck.mjs` → `/api/ping` on `WEB_PORT` | Do not override with `wget`; the Node image has no wget. | | **geowiki** | HTTP `:3000` | Uses `PORT` from `.env` (default 3000). | | **access-control-webhook** | `wget --spider` `:9000` | | diff --git a/docs/contributing.md b/docs/contributing.md index c64c3b4..2dee390 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -155,6 +155,8 @@ Persistent runtime files stored in `../../lib/APPNAME` are automatically backed Unfortunately backing up live database storage doesn't work as the files may easily be in an inconsistent state. +List an app's live database files in its own `.rsync.exclude`, one path per line relative to `/opt` (for example `lib/myapp/app.db`), so the file backup skips them; back them up with `BACKUP_DATABASE_URLS` below or the app's own dump feature instead. A GitHub Action collects the `apps/*/.rsync.exclude` and `experiments/*/.rsync.exclude` files into the top-level `.rsync.exclude`, which you shouldn't edit by hand. + The `db-backup` program looks for a `.env` file in each application directory. If it finds one, it looks for a variable called `BACKUP_DATABASE_URLS`. This variable should contain a comma-separated list of quoted database URLs. It does a simple database dump for each database URL it finds, keeping the five most recent backups. This doesn't work well for very large databases; in that case we recommend rolling a custom backup solution that's appropriate for the specific database. In our case, our server is named `chaos`; backups are done to `/backups/chaos/databases` and look something like this: diff --git a/docs/core.md b/docs/core.md index b3a2bf2..ab725e0 100644 --- a/docs/core.md +++ b/docs/core.md @@ -53,8 +53,6 @@ Repeats mDNS traffic between a network interface and a Docker network. Allows co Nginx Proxy Manager is a simple web-based UI that manages reverse proxies using Nginx. It can automatically -### portainer - ### postgresql Postgresql database diff --git a/docs/design.md b/docs/design.md index 0eef3c9..fb98f07 100644 --- a/docs/design.md +++ b/docs/design.md @@ -121,7 +121,7 @@ networks: | `mariadb` | `mariadb-net` | `mariadb` | MariaDB database access | | `mqtt` | `mosquitto-net` | `mosquitto` | MQTT broker access | | `hass` | `hass-net` | `home-assistant` | Home Assistant integration | -| `influxdb` | `influxdb-net` | `influxdb` | InfluxDB time series database | +| `prometheus` | `prometheus-net` | `prometheus` | Prometheus metrics and exporters | | `llama` | `llama-net` | `ollama` | Local LLM inference | | `frigate` | `frigate-net` | `frigate` | Frigate NVR/camera access | | `mdns` | `mdns-net` | `mdns-repeater` | mDNS across network segments | @@ -134,7 +134,7 @@ networks: - Reads/writes to MariaDB → add `mariadb` - Publishes or subscribes to MQTT topics → add `mqtt` - Integrates with Home Assistant → add `hass` -- Reads/writes to InfluxDB → add `influxdb` +- Queries Prometheus or needs to be scraped by it without a proxy route → add `prometheus` - Uses local AI/LLM → add `llama` - Needs camera feeds from Frigate → add `frigate` - Needs to advertise itself via mDNS → add `mdns` diff --git a/experiments/avahi-mdns/.rsync-exclude b/experiments/avahi-mdns/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/experiments/camera2prusa/.rsync-exclude b/experiments/camera2prusa/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/experiments/chronograf/.rsync-exclude b/experiments/chronograf/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/experiments/comfyui/.env.example b/experiments/comfyui/.env.example index f5b8462..ee92016 100644 --- a/experiments/comfyui/.env.example +++ b/experiments/comfyui/.env.example @@ -1,21 +1,43 @@ -# ==== hardware: pick exactly one COMPOSE_FILE line =========================== -# See README "Choosing compose files". Add :docker-compose.nfs.yml to the end of -# any line to keep /data on NFS. +# ==== compose files =========================================================== +# COMPOSE_FILE is assembled from the three settings below; set those and leave +# COMPOSE_FILE itself alone. See README "Choosing compose files". +# --- hardware: pick exactly one COMPOSE_HARDWARE line --- # NVIDIA, CUDA 13 (driver >= 580): discrete GPUs, DGX Spark -COMPOSE_FILE=docker-compose.yml:docker-compose.nvidia.yml +COMPOSE_HARDWARE=:docker-compose.nvidia.yml # NVIDIA Jetson Thor (uses the nvidia runtime instead of GPU reservations) -# COMPOSE_FILE=docker-compose.yml:docker-compose.jetson.yml +# COMPOSE_HARDWARE=:docker-compose.jetson.yml # NVIDIA, CUDA 12.8 (driver >= 570) -# COMPOSE_FILE=docker-compose.yml:docker-compose.nvidia.yml:docker-compose.nvidia-cu128.yml +# COMPOSE_HARDWARE=:docker-compose.nvidia.yml:docker-compose.nvidia-cu128.yml # NVIDIA Blackwell with SageAttention (DGX Spark GB10, RTX 50, B200; not Jetson Thor) -# COMPOSE_FILE=docker-compose.yml:docker-compose.nvidia.yml:docker-compose.nvidia-sage.yml +# COMPOSE_HARDWARE=:docker-compose.nvidia.yml:docker-compose.nvidia-sage.yml # AMD Strix Halo / Ryzen AI Max (gfx1151), x86_64 only -# COMPOSE_FILE=docker-compose.yml:docker-compose.rocm.yml +# COMPOSE_HARDWARE=:docker-compose.rocm.yml # Intel Arc (B580, Arc Pro B70, A-series), x86_64 only -# COMPOSE_FILE=docker-compose.yml:docker-compose.xpu.yml +# COMPOSE_HARDWARE=:docker-compose.xpu.yml # CPU only (no GPU, or Docker Desktop on macOS) -# COMPOSE_FILE=docker-compose.yml +# COMPOSE_HARDWARE= + +# --- access: how clients reach it --- +# Hackstack: join nginx-proxy-net and llama-net; reach it through the reverse proxy +COMPOSE_ACCESS=:docker-compose.networks.yml +# Standalone: publish port 8188 on the host, no reverse proxy +# ComfyUI has no authentication: only publish the port on a trusted network. +# COMPOSE_ACCESS=:docker-compose.ports.yml +# Both +# COMPOSE_ACCESS=:docker-compose.networks.yml:docker-compose.ports.yml +# Neither (only reachable from inside the container) +# COMPOSE_ACCESS= +# With docker-compose.ports.yml: host port, and the host address to bind +# (e.g. a LAN IP, or 127.0.0.1 for this machine only) +# PUBLISHED_PORT=8188 +# PUBLISHED_ADDRESS=0.0.0.0 + +# --- storage: /data on NFS (see the NFS section at the end) --- +COMPOSE_STORAGE= +# COMPOSE_STORAGE=:docker-compose.nfs.yml + +COMPOSE_FILE=docker-compose.yml${COMPOSE_STORAGE}${COMPOSE_HARDWARE}${COMPOSE_ACCESS} # ComfyUI release (e.g. 0.38.0) or latest. The compose file adds the hardware # suffix (-cpu, -cu128, -sage, -rocm-gfx1151, -xpu), so don't include it here. @@ -65,13 +87,13 @@ NVIDIA_DRIVER_CAPABILITIES=all # set COMFYUI_ATTENTION=pytorch to turn it off. # --- DGX Spark (GB10, 128 GB unified memory) ---------------------------------- -# Use the -sage COMPOSE_FILE line above. +# Use the -sage COMPOSE_HARDWARE line above. # COMFYUI_VRAM_MODE=highvram # offloading to "CPU RAM" is a pointless copy on unified memory # COMFYUI_RESERVE_VRAM=30 # GB left for the OS and a co-resident vLLM (~18 GB for Qwen3.8-27B NVFP4 + KV cache) # COMFYUI_FAST=fp8_matrix_mult # faster FP8 models on Blackwell; benchmark before keeping # --- Jetson Thor (128 GB unified memory) -------------------------------------- -# Use the Jetson COMPOSE_FILE line above. On the host: sudo nvpmodel -m 0 && sudo jetson_clocks +# Use the Jetson COMPOSE_HARDWARE line above. On the host: sudo nvpmodel -m 0 && sudo jetson_clocks # COMFYUI_VRAM_MODE=highvram # COMFYUI_RESERVE_VRAM=16 # COMFYUI_FAST=fp8_matrix_mult @@ -113,7 +135,7 @@ HF_DEBUG=0 # COMFIER_URL=https://slop.pdxhackerspace.org # COMFIER_API_KEY= -# ==== optional: /data on NFS (append :docker-compose.nfs.yml to COMPOSE_FILE) = +# ==== optional: /data on NFS (set COMPOSE_STORAGE above) = # COMFYUI_NFS_HOST= # COMFYUI_NFS_PATH= # NFS_MOUNT_OPTS=nfsvers=4,hard diff --git a/experiments/comfyui/README.md b/experiments/comfyui/README.md index 1e52423..e8fb413 100644 --- a/experiments/comfyui/README.md +++ b/experiments/comfyui/README.md @@ -4,7 +4,7 @@ Everything persistent (models, custom nodes, inputs, outputs, user settings, kernel caches) lives in `../../lib/comfyui`, mounted at `/data`. -ComfyUI has no authentication, and ComfyUI-Manager can install arbitrary custom nodes. Don't publish port 8188; reach it only through an authenticating reverse proxy on `nginx-proxy-net`. +ComfyUI has no authentication, and ComfyUI-Manager can install arbitrary custom nodes. On a shared server, reach it only through an authenticating reverse proxy on `nginx-proxy-net`. Publish port 8188 directly only on a trusted internal network (see [Reaching the service](#reaching-the-service)). ## Configuration @@ -17,7 +17,7 @@ mkdir -p ../../lib/comfyui Then in `.env`: -1. Uncomment exactly one `COMPOSE_FILE` line for your hardware (see below). The NVIDIA CUDA 13 line is active by default. +1. Uncomment exactly one `COMPOSE_HARDWARE` line for your hardware (see below). The NVIDIA CUDA 13 line is active by default. Pick `COMPOSE_ACCESS` too: reverse proxy (default) or published port. 2. Set `PUID` / `PGID` to the owner of `../../lib/comfyui`. 3. Uncomment the tuning block for your hardware, if there is one (DGX Spark, Jetson Thor, Strix Halo, Intel Arc). 4. Optionally set `HF_TOKEN` for gated Hugging Face models. @@ -28,17 +28,17 @@ The entrypoint turns `COMFYUI_*` variables into ComfyUI command-line flags. `.en ## Choosing compose files -`docker-compose.yml` is the hardware-neutral base (volumes, networks, health check). Used on its own, it runs the CPU-only image. Each hardware file layers on top of it, swapping in the matching image and passing the GPU through. Compose reads `COMPOSE_FILE` from `.env`, so plain `docker compose up -d` uses whatever you chose. +`docker-compose.yml` is the hardware-neutral base (volumes, health check). Used on its own, it runs the CPU-only image. Each hardware file layers on top of it, swapping in the matching image and passing the GPU through. Compose assembles `COMPOSE_FILE` in `.env` from three settings: `COMPOSE_HARDWARE` (below), `COMPOSE_ACCESS` (see [Reaching the service](#reaching-the-service)) and `COMPOSE_STORAGE` (NFS). Set those and leave the `COMPOSE_FILE` line alone; plain `docker compose up -d` then uses all three. -| Hardware | Image tag | `COMPOSE_FILE` | +| Hardware | Image tag | `COMPOSE_HARDWARE` | |----------|-----------|----------------| -| NVIDIA, driver ≥ 580 (x86_64 or arm64) | `latest` | `docker-compose.yml:docker-compose.nvidia.yml` | -| NVIDIA Jetson Thor | `latest` | `docker-compose.yml:docker-compose.jetson.yml` | -| NVIDIA, driver 570–579 | `latest-cu128` | `docker-compose.yml:docker-compose.nvidia.yml:docker-compose.nvidia-cu128.yml` | -| NVIDIA Blackwell: DGX Spark (GB10), RTX 50, B200 | `latest-sage` | `docker-compose.yml:docker-compose.nvidia.yml:docker-compose.nvidia-sage.yml` | -| AMD Strix Halo / Ryzen AI Max (gfx1151), x86_64 | `latest-rocm-gfx1151` | `docker-compose.yml:docker-compose.rocm.yml` | -| Intel Arc (B580, Arc Pro B70, A-series), x86_64 | `latest-xpu` | `docker-compose.yml:docker-compose.xpu.yml` | -| No GPU, or Docker Desktop on macOS | `latest-cpu` | `docker-compose.yml` | +| NVIDIA, driver ≥ 580 (x86_64 or arm64) | `latest` | `:docker-compose.nvidia.yml` | +| NVIDIA Jetson Thor | `latest` | `:docker-compose.jetson.yml` | +| NVIDIA, driver 570–579 | `latest-cu128` | `:docker-compose.nvidia.yml:docker-compose.nvidia-cu128.yml` | +| NVIDIA Blackwell: DGX Spark (GB10), RTX 50, B200 | `latest-sage` | `:docker-compose.nvidia.yml:docker-compose.nvidia-sage.yml` | +| AMD Strix Halo / Ryzen AI Max (gfx1151), x86_64 | `latest-rocm-gfx1151` | `:docker-compose.rocm.yml` | +| Intel Arc (B580, Arc Pro B70, A-series), x86_64 | `latest-xpu` | `:docker-compose.xpu.yml` | +| No GPU, or Docker Desktop on macOS | `latest-cpu` | *(empty)* | To pick a row: @@ -48,7 +48,7 @@ To pick a row: - **Intel:** check `lspci -nnk -d 8086: | grep -A3 -E 'VGA|Display'` shows `Kernel driver in use: xe` (or `i915` for Alchemist). - **macOS:** Docker can't pass the Apple GPU through, so this runs on CPU only. For real speed, run ComfyUI natively instead (`brew install --cask comfy`). -To keep `/data` on NFS, append `:docker-compose.nfs.yml` to whichever line you chose (see below). +To keep `/data` on NFS, set `COMPOSE_STORAGE` (see below). Check the merged result before starting: @@ -78,20 +78,30 @@ With several Arc cards, ComfyUI uses only the first; set `COMFYUI_ONEAPI_DEVICE_ To share one copy of large weights with another container, bind-mount that storage under `/data/shared-models` and set `COMFYUI_EXTRA_MODEL_PATHS_CONFIG=/config/extra_model_paths.yaml` in `.env`. `config/extra_model_paths.yaml` describes the expected layout. -## Networks +## Reaching the service -- **`nginx-proxy-net`**: reverse proxy to port **8188** -- **`llama-net`**: same LLM network as `apps/vllm` +How clients reach comfyui is chosen with `COMPOSE_ACCESS` in `.env`, independently of the hardware: + +| `COMPOSE_ACCESS` | Effect | +|------------------|--------| +| `:docker-compose.networks.yml` | Joins `nginx-proxy-net` (reverse proxy) and `llama-net` (same LLM network as `apps/vllm`). Other containers and the reverse proxy reach it as `comfyui:8188`. The default, for Hackstack servers. | +| `:docker-compose.ports.yml` | Publishes port 8188 on the host, for servers with no reverse proxy. `PUBLISHED_PORT` changes the host port and `PUBLISHED_ADDRESS` the address it binds (a LAN IP, or `127.0.0.1` for this machine only). | +| `:docker-compose.networks.yml:docker-compose.ports.yml` | Both. | +| *(empty)* | Neither; reachable only from inside the container. | + +ComfyUI has no authentication: anyone who can reach a published port can run workflows and install custom nodes. + +`docker-compose.yml` itself has no networks and its `ports` are commented out, so nothing needs editing in any compose file. ## Storage on NFS (optional) -To keep `/data` on a NAS export instead of `../../lib/comfyui`, append `:docker-compose.nfs.yml` to `COMPOSE_FILE` and set `COMFYUI_NFS_HOST`, `COMFYUI_NFS_PATH` and `NFS_MOUNT_OPTS` (see `.env.example`). +To keep `/data` on a NAS export instead of `../../lib/comfyui`, set `COMPOSE_STORAGE=:docker-compose.nfs.yml` and set `COMFYUI_NFS_HOST`, `COMFYUI_NFS_PATH` and `NFS_MOUNT_OPTS` (see `.env.example`). Prefer **`hard`** NFS mounts, not `soft`. Docker creates named NFS volumes on first start; if the server or export path is wrong, fix `.env` and remove the project volume before retrying (`docker volume ls`, then `docker volume rm …`). ## Usage -Run these from this directory so Compose picks up `COMPOSE_FILE` from `.env`. Don't pass `-f docker-compose.yml`; that skips the hardware override. +Run these from this directory so Compose picks up `COMPOSE_FILE` from `.env`. Don't pass `-f docker-compose.yml`; that skips the hardware, access and storage overrides. ```bash docker compose up -d @@ -101,4 +111,4 @@ docker compose down The first start takes a while; the health check allows two minutes before it counts failures. Wait for it to report `healthy` (`docker compose ps`). -`docker compose down` stops the container but leaves everything in `../../lib/comfyui`. If you switch hardware backends, run `docker compose down` before changing `COMPOSE_FILE`, then `docker compose up -d`. +`docker compose down` stops the container but leaves everything in `../../lib/comfyui`. If you switch hardware backends, run `docker compose down` before changing `COMPOSE_HARDWARE`, then `docker compose up -d`. diff --git a/experiments/comfyui/docker-compose.jetson.yml b/experiments/comfyui/docker-compose.jetson.yml index f7ba3fb..f477a61 100644 --- a/experiments/comfyui/docker-compose.jetson.yml +++ b/experiments/comfyui/docker-compose.jetson.yml @@ -1,7 +1,7 @@ # NVIDIA Jetson Thor. Use instead of docker-compose.nvidia.yml, not on top of it: # Jetson's container toolkit runs in CSV mode, which rejects device reservations # (the --gpus equivalent) and only works through the nvidia runtime. -# COMPOSE_FILE=docker-compose.yml:docker-compose.jetson.yml +# COMPOSE_HARDWARE=:docker-compose.jetson.yml services: comfyui: image: ghcr.io/romkey/comfyui-docker:${IMAGE_VERSION:-latest} diff --git a/experiments/comfyui/docker-compose.networks.yml b/experiments/comfyui/docker-compose.networks.yml new file mode 100644 index 0000000..d403637 --- /dev/null +++ b/experiments/comfyui/docker-compose.networks.yml @@ -0,0 +1,16 @@ +# Optional: attach to the Hackstack networks so the reverse proxy and other +# containers (openwebui, home-assistant, ...) reach it as comfyui:8188. +# Enabled through COMPOSE_ACCESS in .env (see .env.example). +services: + comfyui: + networks: + - llama + - proxy + +networks: + llama: + external: true + name: llama-net + proxy: + external: true + name: nginx-proxy-net diff --git a/experiments/comfyui/docker-compose.nfs.yml b/experiments/comfyui/docker-compose.nfs.yml index 2753159..02074ff 100644 --- a/experiments/comfyui/docker-compose.nfs.yml +++ b/experiments/comfyui/docker-compose.nfs.yml @@ -1,5 +1,5 @@ -# Optional override: ComfyUI runtime and models on NFS. Add it last in COMPOSE_FILE, e.g. -# COMPOSE_FILE=docker-compose.yml:docker-compose.nvidia.yml:docker-compose.nfs.yml +# Optional override: ComfyUI runtime and models on NFS. +# Enabled through COMPOSE_STORAGE in .env. services: comfyui: diff --git a/experiments/comfyui/docker-compose.nvidia-cu128.yml b/experiments/comfyui/docker-compose.nvidia-cu128.yml index 0df9849..0a98241 100644 --- a/experiments/comfyui/docker-compose.nvidia-cu128.yml +++ b/experiments/comfyui/docker-compose.nvidia-cu128.yml @@ -1,5 +1,5 @@ # NVIDIA with an older driver (>= 570): CUDA 12.8 build. Layer on nvidia.yml: -# COMPOSE_FILE=docker-compose.yml:docker-compose.nvidia.yml:docker-compose.nvidia-cu128.yml +# COMPOSE_HARDWARE=:docker-compose.nvidia.yml:docker-compose.nvidia-cu128.yml services: comfyui: image: ghcr.io/romkey/comfyui-docker:${IMAGE_VERSION:-latest}-cu128 diff --git a/experiments/comfyui/docker-compose.nvidia-sage.yml b/experiments/comfyui/docker-compose.nvidia-sage.yml index ce71abd..3178a80 100644 --- a/experiments/comfyui/docker-compose.nvidia-sage.yml +++ b/experiments/comfyui/docker-compose.nvidia-sage.yml @@ -1,6 +1,6 @@ # NVIDIA Blackwell (DGX Spark GB10, RTX 50, B200): CUDA 13 + SageAttention. # Not for Jetson Thor (sm_110 is unsupported by SageAttention). Layer on nvidia.yml: -# COMPOSE_FILE=docker-compose.yml:docker-compose.nvidia.yml:docker-compose.nvidia-sage.yml +# COMPOSE_HARDWARE=:docker-compose.nvidia.yml:docker-compose.nvidia-sage.yml services: comfyui: image: ghcr.io/romkey/comfyui-docker:${IMAGE_VERSION:-latest}-sage diff --git a/experiments/comfyui/docker-compose.nvidia.yml b/experiments/comfyui/docker-compose.nvidia.yml index 5824183..0648cb0 100644 --- a/experiments/comfyui/docker-compose.nvidia.yml +++ b/experiments/comfyui/docker-compose.nvidia.yml @@ -1,7 +1,7 @@ # NVIDIA GPUs on Linux (x86_64 or arm64: discrete cards, DGX Spark). # Not for Jetson Thor; use docker-compose.jetson.yml there. # Needs the NVIDIA Container Toolkit on the host and driver >= 580 for CUDA 13. -# COMPOSE_FILE=docker-compose.yml:docker-compose.nvidia.yml +# COMPOSE_HARDWARE=:docker-compose.nvidia.yml services: comfyui: image: ghcr.io/romkey/comfyui-docker:${IMAGE_VERSION:-latest} diff --git a/experiments/comfyui/docker-compose.ports.yml b/experiments/comfyui/docker-compose.ports.yml new file mode 100644 index 0000000..1ce1664 --- /dev/null +++ b/experiments/comfyui/docker-compose.ports.yml @@ -0,0 +1,6 @@ +# Optional: publish the port on the host, for servers without a reverse proxy. +# Enabled through COMPOSE_ACCESS in .env (see .env.example). +services: + comfyui: + ports: + - "${PUBLISHED_ADDRESS:-0.0.0.0}:${PUBLISHED_PORT:-8188}:8188" diff --git a/experiments/comfyui/docker-compose.rocm.yml b/experiments/comfyui/docker-compose.rocm.yml index 8952354..1b8ed07 100644 --- a/experiments/comfyui/docker-compose.rocm.yml +++ b/experiments/comfyui/docker-compose.rocm.yml @@ -1,6 +1,6 @@ # AMD Strix Halo (Ryzen AI Max, gfx1151) on Linux, x86_64 only. The image bundles # ROCm; the host only needs the amdgpu kernel driver. -# COMPOSE_FILE=docker-compose.yml:docker-compose.rocm.yml +# COMPOSE_HARDWARE=:docker-compose.rocm.yml services: comfyui: image: ghcr.io/romkey/comfyui-docker:${IMAGE_VERSION:-latest}-rocm-gfx1151 diff --git a/experiments/comfyui/docker-compose.xpu.yml b/experiments/comfyui/docker-compose.xpu.yml index de537f4..4941500 100644 --- a/experiments/comfyui/docker-compose.xpu.yml +++ b/experiments/comfyui/docker-compose.xpu.yml @@ -1,6 +1,6 @@ # Intel Arc (Battlemage B580 / Arc Pro B70, Alchemist A-series) on Linux, x86_64 only. # Needs the xe (or i915) kernel driver; the image bundles Intel's compute runtime. -# COMPOSE_FILE=docker-compose.yml:docker-compose.xpu.yml +# COMPOSE_HARDWARE=:docker-compose.xpu.yml services: comfyui: image: ghcr.io/romkey/comfyui-docker:${IMAGE_VERSION:-latest}-xpu diff --git a/experiments/comfyui/docker-compose.yml b/experiments/comfyui/docker-compose.yml index 8689404..7c76479 100644 --- a/experiments/comfyui/docker-compose.yml +++ b/experiments/comfyui/docker-compose.yml @@ -1,11 +1,14 @@ # Hardware-neutral base. On its own this runs the CPU-only image; layer one of -# the hardware overrides on top via COMPOSE_FILE in .env (see README): +# the hardware overrides on top via COMPOSE_HARDWARE in .env (see README): # docker-compose.nvidia.yml NVIDIA, CUDA 13 (driver >= 580) # docker-compose.nvidia-cu128.yml NVIDIA, CUDA 12.8 (driver >= 570), on top of nvidia.yml # docker-compose.nvidia-sage.yml NVIDIA Blackwell + SageAttention, on top of nvidia.yml # docker-compose.jetson.yml NVIDIA Jetson Thor (nvidia runtime, instead of nvidia.yml) # docker-compose.rocm.yml AMD Strix Halo (gfx1151), x86_64 only # docker-compose.xpu.yml Intel Arc, x86_64 only +# and how clients reach it: +# docker-compose.networks.yml join nginx-proxy-net and llama-net (Hackstack) +# docker-compose.ports.yml publish the port on the host (no reverse proxy) services: comfyui: image: ghcr.io/romkey/comfyui-docker:${IMAGE_VERSION:-latest}-cpu @@ -26,14 +29,3 @@ services: retries: 3 start_period: 120s ipc: host - networks: - - proxy - - llama - -networks: - proxy: - external: true - name: nginx-proxy-net - llama: - external: true - name: llama-net diff --git a/experiments/forgejo/.rsync-exclude b/experiments/forgejo/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/experiments/grafana/.env.example b/experiments/grafana/.env.example index 861266b..cb16f0a 100644 --- a/experiments/grafana/.env.example +++ b/experiments/grafana/.env.example @@ -1,4 +1,49 @@ IMAGE_VERSION=latest +TZ=America/Los_Angeles + +# Settings below override config/grafana.ini as GF_
_. +# See https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/ + +# --- Server / reverse proxy --- +GF_SERVER_ROOT_URL=https://grafana.example.com + +# --- Admin account (only applied when the admin user is first created) --- +GF_SECURITY_ADMIN_USER=admin +GF_SECURITY_ADMIN_PASSWORD= +GF_USERS_ALLOW_SIGN_UP=false +GF_ANALYTICS_REPORTING_ENABLED=false + +# --- Database (shared PostgreSQL; create it first - see README) --- +GF_DATABASE_TYPE=postgres +GF_DATABASE_HOST=postgresql:5432 +GF_DATABASE_NAME=grafana_db +GF_DATABASE_USER=grafana_user +GF_DATABASE_PASSWORD= +GF_DATABASE_SSL_MODE=disable + +# --- Optional: log in with authentik (OIDC) - see README --- +# Redirect URI to register in authentik: /login/generic_oauth +# GF_AUTH_GENERIC_OAUTH_ENABLED=true +# GF_AUTH_GENERIC_OAUTH_NAME=authentik +# GF_AUTH_GENERIC_OAUTH_CLIENT_ID= +# GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET= +# GF_AUTH_GENERIC_OAUTH_SCOPES=openid profile email +# GF_AUTH_GENERIC_OAUTH_AUTH_URL=https://auth.example.com/application/o/authorize/ +# GF_AUTH_GENERIC_OAUTH_TOKEN_URL=https://auth.example.com/application/o/token/ +# GF_AUTH_GENERIC_OAUTH_API_URL=https://auth.example.com/application/o/userinfo/ +# GF_AUTH_SIGNOUT_REDIRECT_URL=https://auth.example.com/application/o/grafana/end-session/ +# GF_AUTH_GENERIC_OAUTH_LOGIN_ATTRIBUTE_PATH=preferred_username +# GF_AUTH_GENERIC_OAUTH_NAME_ATTRIBUTE_PATH=name +# GF_AUTH_GENERIC_OAUTH_EMAIL_ATTRIBUTE_PATH=email +# Map authentik groups to Grafana roles; everyone else gets Viewer +# GF_AUTH_GENERIC_OAUTH_ROLE_ATTRIBUTE_PATH=contains(groups, 'Grafana Admins') && 'Admin' || contains(groups, 'Grafana Editors') && 'Editor' || 'Viewer' +# Create Grafana accounts on first OIDC login (separate from GF_USERS_ALLOW_SIGN_UP) +# GF_AUTH_GENERIC_OAUTH_ALLOW_SIGN_UP=true +# Skip the Grafana login page and go straight to authentik +# GF_AUTH_OAUTH_AUTO_LOGIN=false +# Hide the username/password form once OIDC works (keep the admin login until then) +# GF_AUTH_DISABLE_LOGIN_FORM=false + # BACKUP_DATABASE_URLS — apps/postgresql/bin/mkdb.sh or apps/mariadb/bin/mkdb.sh appends this to .env when you # create the app database (unless .env already defines it). For SQLite or other URLs, set it only in your # real .env. Do not define BACKUP_DATABASE_URLS in .env.example. diff --git a/experiments/grafana/.rsync-exclude b/experiments/grafana/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/experiments/grafana/.rsync.exclude b/experiments/grafana/.rsync.exclude deleted file mode 100644 index f922ba7..0000000 --- a/experiments/grafana/.rsync.exclude +++ /dev/null @@ -1 +0,0 @@ -lib/grafana/grafana.db diff --git a/experiments/grafana/README.md b/experiments/grafana/README.md index 1845c64..59b6041 100644 --- a/experiments/grafana/README.md +++ b/experiments/grafana/README.md @@ -1,12 +1,59 @@ # grafana (experiment) -Metrics visualization and dashboards +[Grafana](https://grafana.com/) metrics visualization and dashboards. It uses the shared PostgreSQL (`postgresql` on `postgres-net`) for its own data and joins `prometheus-net` to query **`experiments/prometheus`** (data source URL `http://prometheus:9090`). ## Configuration +### Database + +Create the database with the shared cluster helper: + +```bash +../../apps/postgresql/bin/mkdb.sh grafana +``` + +That creates `grafana_db` owned by `grafana_user` and prints a password. Put it in `.env` as `GF_DATABASE_PASSWORD`. + +### Environment Variables + +Copy `.env.example` to `.env` and configure: + +```bash +cp .env.example .env +# Edit .env with your settings +``` + +| Variable | Notes | +|----------|-------| +| `GF_SERVER_ROOT_URL` | Public URL served by nginx-proxy-manager | +| `GF_SECURITY_ADMIN_PASSWORD` | Initial admin password (only used when the admin user is first created) | +| `GF_DATABASE_PASSWORD` | Password from `mkdb.sh` | + +Any `grafana.ini` setting can be set as `GF_
_`. + +### Login with authentik (optional) + +1. In authentik, create an **OAuth2/OpenID Provider** with redirect URI `https:///login/generic_oauth` and an **Application** with slug `grafana`. +2. Optionally create groups `Grafana Admins` and `Grafana Editors`; other users get the Viewer role. +3. Uncomment the `GF_AUTH_GENERIC_OAUTH_*` block in `.env`, fill in the client ID and secret, and replace `auth.example.com` with your authentik host. +4. `GF_SERVER_ROOT_URL` must be the public URL, or the redirect URI Grafana sends won't match. + +Once OIDC login works you can set `GF_AUTH_DISABLE_LOGIN_FORM=true` to hide the password form. + ### Configuration Files -Configuration files are stored in the `config/` directory. +Copy `config/grafana.ini.example` to `config/grafana.ini`. The `config/` directory is mounted at `/etc/grafana`; put datasource and dashboard provisioning files in `config/provisioning/`. + +### Data directories + +Grafana runs as uid 472: + +```bash +mkdir -p ../../lib/grafana ../../log/grafana +sudo chown 472:0 ../../lib/grafana ../../log/grafana +``` + +Point nginx-proxy-manager at `grafana:3000`. ## Usage diff --git a/experiments/grafana/config/grafana.ini.example b/experiments/grafana/config/grafana.ini.example index e69de29..1304c2e 100644 --- a/experiments/grafana/config/grafana.ini.example +++ b/experiments/grafana/config/grafana.ini.example @@ -0,0 +1,11 @@ +; Grafana configuration. Copy to grafana.ini. +; +; Most settings are set in .env as GF_
_ environment variables, +; which override anything here. Full reference and defaults: +; https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/ +; +; This directory is mounted at /etc/grafana. Put provisioning files +; (datasources, dashboards) under config/provisioning/. + +[paths] +provisioning = /etc/grafana/provisioning diff --git a/experiments/grafana/docker-compose.yml b/experiments/grafana/docker-compose.yml index ed59464..4cd9e13 100644 --- a/experiments/grafana/docker-compose.yml +++ b/experiments/grafana/docker-compose.yml @@ -1,6 +1,6 @@ services: grafana: - image: grafana/grafana-enterprise:${IMAGE_VERSION:-latest} + image: grafana/grafana:${IMAGE_VERSION:-latest} container_name: grafana hostname: grafana restart: unless-stopped @@ -8,11 +8,14 @@ services: - ../../lib/grafana:/var/lib/grafana - ../../log/grafana:/var/log/grafana - ./config:/etc/grafana + env_file: + - .env # ports: # - 3000:3000 networks: - proxy - - influxdb + - db + - prometheus healthcheck: test: ["CMD-SHELL", "wget -q --spider http://127.0.0.1:3000/api/health || exit 1"] interval: 30s @@ -24,6 +27,9 @@ networks: proxy: external: true name: nginx-proxy-net - influxdb: + db: external: true - name: influxdb-net + name: postgres-net + prometheus: + external: true + name: prometheus-net diff --git a/experiments/homebox/.rsync-exclude b/experiments/homebox/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/experiments/influxdb/.rsync-exclude b/experiments/influxdb/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/experiments/komodo/.env.example b/experiments/komodo/.env.example new file mode 100644 index 0000000..9293799 --- /dev/null +++ b/experiments/komodo/.env.example @@ -0,0 +1,38 @@ +IMAGE_VERSION=2 +MONGO_IMAGE_VERSION=latest +TZ=America/Los_Angeles + +# MongoDB - root user is created on first start +MONGO_INITDB_ROOT_USERNAME=komodo +MONGO_INITDB_ROOT_PASSWORD= + +# Komodo Core - full list: https://github.com/moghtech/komodo/blob/main/config/core.config.toml +KOMODO_DATABASE_ADDRESS=komodo-mongo:27017 +KOMODO_DATABASE_USERNAME=komodo +KOMODO_DATABASE_PASSWORD= + +KOMODO_HOST=https://komodo.example.com +KOMODO_TITLE=Komodo +KOMODO_PERIPHERY_PUBLIC_KEY=file:/config/keys/periphery.pub + +KOMODO_LOCAL_AUTH=true +KOMODO_INIT_ADMIN_USERNAME=admin +KOMODO_INIT_ADMIN_PASSWORD= +KOMODO_FIRST_SERVER_NAME=Local +KOMODO_DISABLE_USER_REGISTRATION=true + +KOMODO_WEBHOOK_SECRET= +KOMODO_JWT_SECRET= + +# Optional OIDC login (e.g. authentik) +KOMODO_OIDC_ENABLED=false +# KOMODO_OIDC_PROVIDER=https://auth.example.com/application/o/komodo +# KOMODO_OIDC_CLIENT_ID= +# KOMODO_OIDC_CLIENT_SECRET= + +# Komodo Periphery - full list: https://github.com/moghtech/komodo/blob/main/config/periphery.config.toml +PERIPHERY_CORE_ADDRESS=ws://komodo-core:9120 +PERIPHERY_CONNECT_AS=Local +PERIPHERY_CORE_PUBLIC_KEYS=file:/config/keys/core.pub +PERIPHERY_ROOT_DIRECTORY=/etc/komodo +PERIPHERY_INCLUDE_DISK_MOUNTS=/etc/hostname diff --git a/experiments/komodo/.rsync.exclude b/experiments/komodo/.rsync.exclude new file mode 100644 index 0000000..4a429e8 --- /dev/null +++ b/experiments/komodo/.rsync.exclude @@ -0,0 +1 @@ +lib/komodo/mongo diff --git a/experiments/komodo/README.md b/experiments/komodo/README.md new file mode 100644 index 0000000..1ee88df --- /dev/null +++ b/experiments/komodo/README.md @@ -0,0 +1,43 @@ +# komodo (experiment) + +[Komodo](https://komo.do) is a web UI for building and deploying software and managing Docker containers and compose stacks across one or more servers. + +This stack runs Komodo Core (the web UI/API), Komodo Periphery (the agent that talks to the local Docker daemon), and its own MongoDB, which Komodo requires. + +## Configuration + +Copy `.env.example` to `.env` and configure: + +```bash +cp .env.example .env +# Edit .env with your settings +``` + +- `MONGO_INITDB_ROOT_PASSWORD` and `KOMODO_DATABASE_PASSWORD` must match. +- Set `KOMODO_INIT_ADMIN_PASSWORD`, `KOMODO_WEBHOOK_SECRET` and `KOMODO_JWT_SECRET`. +- `PERIPHERY_CONNECT_AS` must match `KOMODO_FIRST_SERVER_NAME`. +- `PERIPHERY_ROOT_DIRECTORY` is where Komodo keeps the stacks, repos and builds it manages. It's mounted at the same path inside the container, so it must be an absolute host path. + +Point nginx-proxy-manager at `komodo-core:9120`. + +Periphery has the Docker socket mounted and can control every container on the host. + +## Usage + +### Starting the service + +```bash +docker compose up -d +``` + +### Stopping the service + +```bash +docker compose down +``` + +### Viewing logs + +```bash +docker compose logs -f +``` diff --git a/experiments/komodo/docker-compose.yml b/experiments/komodo/docker-compose.yml new file mode 100644 index 0000000..f787385 --- /dev/null +++ b/experiments/komodo/docker-compose.yml @@ -0,0 +1,68 @@ +services: + mongo: + image: mongo:${MONGO_IMAGE_VERSION:-latest} + container_name: komodo-mongo + hostname: komodo-mongo + restart: unless-stopped + command: --quiet --wiredTigerCacheSizeGB 0.25 + labels: + komodo.skip: "" + volumes: + - ../../lib/komodo/mongo/db:/data/db + - ../../lib/komodo/mongo/configdb:/data/configdb + env_file: + - .env + networks: + - komodo + healthcheck: + test: ["CMD", "mongosh", "--quiet", "--eval", "db.adminCommand('ping').ok"] + interval: 30s + timeout: 10s + retries: 3 + start_period: 30s + + core: + image: ghcr.io/moghtech/komodo-core:${IMAGE_VERSION:-2} + container_name: komodo-core + hostname: komodo-core + init: true + restart: unless-stopped + volumes: + - ../../lib/komodo/keys:/config/keys + - ../../lib/komodo/backups:/backups + env_file: + - .env +# ports: +# - 9120:9120 + networks: + - proxy + - komodo + depends_on: + mongo: + condition: service_healthy + + periphery: + image: ghcr.io/moghtech/komodo-periphery:${IMAGE_VERSION:-2} + container_name: komodo-periphery + hostname: komodo-periphery + init: true + restart: unless-stopped + volumes: + - ../../lib/komodo/keys:/config/keys + - /var/run/docker.sock:/var/run/docker.sock + - /proc:/proc + # must be the same path inside and outside the container + - ${PERIPHERY_ROOT_DIRECTORY:-/etc/komodo}:${PERIPHERY_ROOT_DIRECTORY:-/etc/komodo} + env_file: + - .env + networks: + - komodo + depends_on: + - core + +networks: + proxy: + name: nginx-proxy-net + external: true + komodo: + name: komodo-net diff --git a/experiments/laser-cutterd/.env.example b/experiments/laser-cutterd/.env.example new file mode 100644 index 0000000..8a4a282 --- /dev/null +++ b/experiments/laser-cutterd/.env.example @@ -0,0 +1,69 @@ +IMAGE_VERSION=latest + +# --- The laser controller -------------------------------------------------- + +# The Ruida controller's IP address or host name (required). +RUIDA_HOST=192.0.2.50 + +# UDP port the controller listens on. +# RUIDA_PORT=50200 + +# UDP port the controller sends its replies to, on this host. Only one +# program per host can use it: not LightBurn/RDWorks on the same machine. +# RUIDA_LOCAL_PORT=40200 + +# Byte-scrambling key: 0x88 for RDC644x/654x/633x/320 boards, 0x11 for 634XG. +# RUIDA_MAGIC=0x88 + +# Seconds to wait for each reply, and how many times to resend. +# RUIDA_TIMEOUT=1.0 +# RUIDA_RETRIES=2 + +# Log every datagram to and from the controller (decoded and raw). Noisy; +# for debugging. Independent of LOG_LEVEL. +# RUIDA_TRACE=false + +# Seconds between polls of status and position, and between reads of the +# lifetime counters and settings. +# POLL_INTERVAL=2 +# SLOW_POLL_INTERVAL=300 + +# --- MQTT ------------------------------------------------------------------ + +# The broker. Leave unset to run without MQTT (HTTP /status only). +# Host networking: reach mosquitto through the port it publishes on the host. +MQTT_HOST=127.0.0.1 +# MQTT_PORT=1883 +# MQTT_USERNAME=laser-cutterd +# MQTT_PASSWORD=REPLACE_ME +# Connect with TLS (verifying the broker's certificate). Usually with port 8883. +# MQTT_TLS=false +# Defaults to laser-cutterd-. +# MQTT_CLIENT_ID=laser-cutterd-laser_cutter +# Topics are //state and so on. +# MQTT_TOPIC_PREFIX=laser-cutterd + +# --- Home Assistant -------------------------------------------------------- + +# Publish MQTT discovery so Home Assistant creates the device by itself. +# HA_DISCOVERY=true +# HA_DISCOVERY_PREFIX=homeassistant + +# How the laser appears in Home Assistant. DEVICE_ID: lowercase letters, +# digits and underscores; it's in every topic and entity id. +# DEVICE_ID=laser_cutter +# DEVICE_NAME=Laser Cutter +# DEVICE_MANUFACTURER=Redsail +# DEVICE_MODEL=X700 + +# --- The daemon ------------------------------------------------------------ + +# Address and port for GET /healthz and /status. With host networking these +# bind on the host itself: 127.0.0.1 keeps them private to it, 0.0.0.0 opens +# them to the LAN. +HOST=127.0.0.1 +# vllm also uses 8000 on the host. +PORT=8010 + +# DEBUG, INFO, WARNING, ERROR or CRITICAL. +LOG_LEVEL=INFO diff --git a/experiments/laser-cutterd/.gitignore b/experiments/laser-cutterd/.gitignore new file mode 100644 index 0000000..4c49bd7 --- /dev/null +++ b/experiments/laser-cutterd/.gitignore @@ -0,0 +1 @@ +.env diff --git a/experiments/laser-cutterd/README.md b/experiments/laser-cutterd/README.md new file mode 100644 index 0000000..0b8c607 --- /dev/null +++ b/experiments/laser-cutterd/README.md @@ -0,0 +1,52 @@ +# laser-cutterd (experiment) + +[laser-cutterd](https://github.com/romkey/laser-cutterd) polls a Ruida laser controller over UDP and publishes its status, position and lifetime counters to MQTT, with Home Assistant discovery so the laser shows up as a device on its own. + +## Configuration + +### Environment Variables + +Copy `.env.example` to `.env` and configure: + +```bash +cp .env.example .env +# Edit .env with your settings +``` + +| Variable | Notes | +|----------|-------| +| `RUIDA_HOST` | The controller's IP address (required) | +| `RUIDA_MAGIC` | `0x88` for RDC644x/654x/633x/320 boards, `0x11` for 634XG | +| `MQTT_HOST` / `MQTT_USERNAME` / `MQTT_PASSWORD` | `apps/mosquitto` | +| `DEVICE_ID` / `DEVICE_NAME` / `DEVICE_MODEL` | How the laser appears in Home Assistant | +| `PORT` | HTTP port for `/healthz` and `/status` on the host (default here `8010`, since vllm uses `8000`) | + +See [docs/configuration.md](https://github.com/romkey/laser-cutterd/blob/main/docs/configuration.md) for everything else. + +### Host networking + +This service uses `network_mode: host`. The controller sends its replies to UDP port 40200 on this host, which Docker's NAT can't be relied on to deliver. As a result: + +- MQTT is reached through the port mosquitto publishes on the host, so `MQTT_HOST=127.0.0.1`. +- Only one program on this host can use UDP 40200, so LightBurn or RDWorks can't talk to the laser from this machine while it runs. +- The HTTP API binds on the host. `HOST=127.0.0.1` keeps it private; set `0.0.0.0` to reach `/status` from the LAN. + +## Usage + +### Starting the service + +```bash +docker compose up -d +``` + +### Stopping the service + +```bash +docker compose down +``` + +### Viewing logs + +```bash +docker compose logs -f +``` diff --git a/experiments/laser-cutterd/docker-compose.yml b/experiments/laser-cutterd/docker-compose.yml new file mode 100644 index 0000000..e8c12b5 --- /dev/null +++ b/experiments/laser-cutterd/docker-compose.yml @@ -0,0 +1,29 @@ +services: + laser-cutterd: + image: ghcr.io/romkey/laser-cutterd:${IMAGE_VERSION:-latest} + container_name: laser-cutterd + hostname: laser-cutterd + restart: unless-stopped + env_file: + - .env + # hackstack: host networking required - the Ruida controller replies to + # UDP 40200 on this host, which Docker's NAT can't be relied on to deliver. + # HTTP (/healthz, /status) is on PORT of the host itself. + network_mode: host + read_only: true + tmpfs: + - /tmp + cap_drop: + - ALL + security_opt: + - no-new-privileges:true + healthcheck: + test: + - CMD + - python + - -c + - import urllib.request; urllib.request.urlopen('http://127.0.0.1:${PORT:-8000}/healthz', timeout=3) + interval: 30s + timeout: 5s + retries: 3 + start_period: 10s diff --git a/experiments/library/.env.example b/experiments/library/.env.example new file mode 100644 index 0000000..b90f5f0 --- /dev/null +++ b/experiments/library/.env.example @@ -0,0 +1,75 @@ +IMAGE_VERSION=latest +REDIS_IMAGE_VERSION=8-alpine +TZ=America/Los_Angeles + +# ==== Rails =================================================================== +RAILS_ENV=production +RAILS_LOG_LEVEL=info +# Generate with: openssl rand -hex 64 +SECRET_KEY_BASE= +# RAILS_MASTER_KEY= + +# Public URL: used for OIDC redirects, links and the URLs written to NFC tags +APP_BASE_URL=https://library.example.com +APP_HOST=library.example.com +APP_PROTOCOL=https + +# ==== Database (shared PostgreSQL; create it first - see README) =============== +DATABASE_URL=postgres://library_user:@postgresql:5432/library_db + +# ==== Redis (library-redis container) ========================================= +REDIS_URL=redis://library-redis:6379/0 + +# ==== Local admin (created by db:seed) ======================================== +ADMIN_EMAIL= +ADMIN_PASSWORD= +# ADMIN_NAME= + +# ==== OIDC login (optional, e.g. authentik) =================================== +# Redirect URI to register: /auth/oidc/callback +# OIDC_ISSUER=https://auth.example.com/application/o/library/ +# OIDC_CLIENT_ID= +# OIDC_CLIENT_SECRET= +# OAuth scopes that grant the admin and editor roles (comma-separated) +# OIDC_ADMIN_SCOPES=is_admin +# OIDC_EDITOR_SCOPES=is_editor +# OIDC_DEBUG=false + +# ==== Guest browsing from the hackerspace network ============================== +# Visitors from these subnets can browse the catalog without signing in +# GUEST_SUBNET_CIDRS=192.168.1.0/24 +# The reverse proxy must be trusted for the client IP to be read from its headers +TRUSTED_PROXIES=10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,127.0.0.1 +# TRUST_FORWARDED_HEADERS=false +# CLIENT_IP_HEADER=CF-Connecting-IP +# NETWORK_ACCESS_DEBUG=false + +# ==== ISBN metadata =========================================================== +# Optional fallback when Open Library has no match +# GOOGLE_BOOKS_API_KEY= + +# ==== NFC tags ================================================================ +# NFC_IOS_SHORTCUT_NAME=Write Library Book Tag +# NFC_TAG_MAX_BYTES=496 + +# ==== Outbound email (apps/postfix on postfix-net) ============================ +SMTP_ADDRESS=postfix +SMTP_PORT=25 +SMTP_DOMAIN=pdxhackerspace.org +SMTP_FROM=library@pdxhackerspace.org +# SMTP_USERNAME= +# SMTP_PASSWORD= +# SMTP_AUTHENTICATION=plain +SMTP_ENABLE_STARTTLS_AUTO=false + +# ==== Slack (optional) ======================================================== +# SLACK_BOT_TOKEN= + +# ==== Sentry / GlitchTip (optional) =========================================== +# SENTRY_DSN= +# SENTRY_ENVIRONMENT=production +# SENTRY_TRACES_SAMPLE_RATE=0 + +# BACKUP_DATABASE_URLS — apps/postgresql/bin/mkdb.sh or apps/mariadb/bin/mkdb.sh appends this to .env when you +# create the app database (unless .env already defines it). For SQLite or other URLs, set it only in your +# real .env. Do not define BACKUP_DATABASE_URLS in .env.example. diff --git a/experiments/library/.gitignore b/experiments/library/.gitignore new file mode 100644 index 0000000..4c49bd7 --- /dev/null +++ b/experiments/library/.gitignore @@ -0,0 +1 @@ +.env diff --git a/experiments/library/README.md b/experiments/library/README.md new file mode 100644 index 0000000..d5dcb0a --- /dev/null +++ b/experiments/library/README.md @@ -0,0 +1,84 @@ +# library (experiment) + +[PDX Hackerspace Library](https://github.com/pdxhackerspace/library) is a Rails app for tracking the space's physical books and their loans, with ISBN metadata lookup, NFC tag writing and an optional catalog feed for search indexers. + +## Services + +| Service | Purpose | +|---------|---------| +| `web` (`library`) | Rails app on port 3000 | +| `sidekiq` (`library-sidekiq`) | Background jobs (metadata lookups, mail) | +| `redis` (`library-redis`) | Sidekiq queue and Rails cache, on its own `library-redis-net` | + +Both Rails containers run pending migrations on start. + +## Configuration + +### Database + +Create the database with the shared cluster helper: + +```bash +../../apps/postgresql/bin/mkdb.sh library +``` + +That creates `library_db` owned by `library_user` and prints a password. Put it in `DATABASE_URL` in `.env`. + +### Environment Variables + +Copy `.env.example` to `.env` and configure: + +```bash +cp .env.example .env +# Edit .env with your settings +``` + +| Variable | Notes | +|----------|-------| +| `SECRET_KEY_BASE` | `openssl rand -hex 64` | +| `DATABASE_URL` | Password from `mkdb.sh` | +| `APP_BASE_URL` / `APP_HOST` | Public URL served by nginx-proxy-manager | +| `ADMIN_EMAIL` / `ADMIN_PASSWORD` | Local admin, created by `db:seed` | +| `OIDC_*` | Optional authentik login; register `/auth/oidc/callback` as the redirect URI | +| `GUEST_SUBNET_CIDRS` | Optional: subnets that can browse without signing in | + +See the [project README](https://github.com/pdxhackerspace/library#readme) for the rest. + +### First run + +The local admin account is created by `db:seed`, which isn't run automatically in production: + +```bash +docker compose exec web ./bin/rails db:seed +``` + +### Data directories + +The containers run as the image's `rails` user (uid 1000): + +```bash +mkdir -p ../../lib/library/storage ../../lib/library/redis +sudo chown 1000:1000 ../../lib/library/storage +``` + +Point nginx-proxy-manager at `library:3000`. + +## Usage + +### Starting the service + +```bash +docker compose up -d +``` + +### Stopping the service + +```bash +docker compose down +``` + +### Viewing logs + +```bash +docker compose logs -f +``` diff --git a/experiments/library/docker-compose.yml b/experiments/library/docker-compose.yml new file mode 100644 index 0000000..3e82d41 --- /dev/null +++ b/experiments/library/docker-compose.yml @@ -0,0 +1,74 @@ +services: + redis: + image: redis:${REDIS_IMAGE_VERSION:-8-alpine} + container_name: library-redis + hostname: library-redis + restart: unless-stopped + command: redis-server --appendonly yes + volumes: + - ../../lib/library/redis:/data + networks: + - redis + healthcheck: + test: ["CMD", "redis-cli", "ping"] + interval: 10s + timeout: 5s + retries: 5 + + web: + image: ghcr.io/pdxhackerspace/library:${IMAGE_VERSION:-latest} + container_name: library + hostname: library + command: ./bin/rails server -b 0.0.0.0 -p 3000 + restart: unless-stopped + env_file: + - .env + volumes: + - ../../lib/library/storage:/rails/storage +# ports: +# - 3000:3000 + networks: + - db + - proxy + - redis + - mail + depends_on: + redis: + condition: service_healthy + healthcheck: + test: ["CMD-SHELL", "curl -fsS http://localhost:3000/up || exit 1"] + interval: 30s + timeout: 10s + retries: 3 + start_period: 60s + + sidekiq: + image: ghcr.io/pdxhackerspace/library:${IMAGE_VERSION:-latest} + container_name: library-sidekiq + hostname: library-sidekiq + command: bundle exec sidekiq + restart: unless-stopped + env_file: + - .env + volumes: + - ../../lib/library/storage:/rails/storage + networks: + - db + - redis + - mail + depends_on: + redis: + condition: service_healthy + +networks: + redis: + name: library-redis-net + proxy: + external: true + name: nginx-proxy-net + db: + external: true + name: postgres-net + mail: + external: true + name: postfix-net diff --git a/experiments/matrix/.rsync-exclude b/experiments/matrix/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/experiments/mediawiki/.rsync-exclude b/experiments/mediawiki/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/experiments/nextcloud/.rsync-exclude b/experiments/nextcloud/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/experiments/olah/.rsync-exclude b/experiments/olah/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/experiments/portainer/.rsync-exclude b/experiments/portainer/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/experiments/prometheus/.env.example b/experiments/prometheus/.env.example new file mode 100644 index 0000000..8ee3866 --- /dev/null +++ b/experiments/prometheus/.env.example @@ -0,0 +1,16 @@ +IMAGE_VERSION=latest +NODE_EXPORTER_IMAGE_VERSION=latest +CADVISOR_IMAGE_VERSION=latest +NUT_EXPORTER_IMAGE_VERSION=latest +# SNMP_EXPORTER_IMAGE_VERSION=latest +TZ=America/Los_Angeles + +# How long to keep metrics +PROMETHEUS_RETENTION=90d + +# nut-exporter - upsd publishes 3493 on the host +NUT_EXPORTER_SERVER=host.docker.internal +NUT_EXPORTER_SERVERPORT=3493 +# Only needed if upsd requires a login to read variables +# NUT_EXPORTER_USERNAME= +# NUT_EXPORTER_PASSWORD= diff --git a/experiments/prometheus/.gitignore b/experiments/prometheus/.gitignore new file mode 100644 index 0000000..b9728b9 --- /dev/null +++ b/experiments/prometheus/.gitignore @@ -0,0 +1,3 @@ +.env +config/prometheus.yml +config/secrets/ diff --git a/experiments/prometheus/.rsync.exclude b/experiments/prometheus/.rsync.exclude new file mode 100644 index 0000000..1cc4694 --- /dev/null +++ b/experiments/prometheus/.rsync.exclude @@ -0,0 +1 @@ +lib/prometheus diff --git a/experiments/prometheus/README.md b/experiments/prometheus/README.md new file mode 100644 index 0000000..ac5d605 --- /dev/null +++ b/experiments/prometheus/README.md @@ -0,0 +1,83 @@ +# prometheus (experiment) + +[Prometheus](https://prometheus.io/) collects and stores metrics; view them with **`experiments/grafana`**. + +## Services + +| Service | What it collects | +|---------|------------------| +| `prometheus` | Scrapes everything below and stores it in `../../lib/prometheus` | +| `node-exporter` | Host CPU, memory, disks, filesystems, network | +| `cadvisor` | Per-container CPU, memory, network and disk I/O | +| `nut-exporter` | UPS status from **`apps/upsd`** | +| `snmp-exporter` | Commented out; uncomment once there's network gear to poll | + +## Configuration + +### Environment Variables + +```bash +cp .env.example .env +``` + +- `PROMETHEUS_RETENTION` - how long to keep metrics (default `90d`) +- `NUT_EXPORTER_*` - where to find upsd. It publishes port 3493 on the host, so the default `host.docker.internal` works without joining any network. + +### Configuration Files + +```bash +cp config/prometheus.yml.example config/prometheus.yml +mkdir -p config/secrets +``` + +`prometheus.yml` scrapes the exporters in this stack out of the box. It also has a commented-out job for every Hackstack app with built-in Prometheus support: + +- apps: home-assistant, authentik, jellyfin, llama-cpp, vllm, litellm, watchtower +- experiments: forgejo, headscale, matrix (Synapse), qdrant, uptime-kuma, tailscale, copyparty + +Most of them need metrics turned on in the app first; the comment above each job says how. Jobs that need a token or password read it from `config/secrets/`, which is git-ignored. Prometheus runs as uid 65534, so those files must be readable by it. + +Home Assistant's Prometheus integration also covers MQTT sensors (zigbee2mqtt, ESPHome, Tasmota) that HA already knows about, so there's no separate MQTT exporter. + +After editing `prometheus.yml`, reload without restarting: + +```bash +docker compose exec prometheus kill -HUP 1 +``` + +### SNMP + +Uncomment `snmp-exporter` in `docker-compose.yml` and the `snmp-*` job in `prometheus.yml`, and list the devices to poll. The image ships profiles (`if_mib`, `apcups`, `synology`, and others) and a `public_v2` community. For other community strings or devices, build a custom `snmp.yml` with the [generator](https://github.com/prometheus/snmp_exporter/tree/main/generator) and mount it at `/etc/snmp_exporter/snmp.yml`. + +### Data directory + +```bash +mkdir -p ../../lib/prometheus +sudo chown 65534:65534 ../../lib/prometheus +``` + +### Grafana + +Grafana joins `prometheus-net`. Add a Prometheus data source with URL `http://prometheus:9090`. The [Node Exporter Full](https://grafana.com/grafana/dashboards/1860) and [cAdvisor](https://grafana.com/grafana/dashboards/19792) dashboards are good starting points. + +The Prometheus UI itself can be proxied at `prometheus:9090`. It has no authentication, so put it behind authentik or leave it unproxied. + +## Usage + +### Starting the service + +```bash +docker compose up -d +``` + +### Stopping the service + +```bash +docker compose down +``` + +### Viewing logs + +```bash +docker compose logs -f +``` diff --git a/experiments/prometheus/config/prometheus.yml.example b/experiments/prometheus/config/prometheus.yml.example new file mode 100644 index 0000000..5cd7f56 --- /dev/null +++ b/experiments/prometheus/config/prometheus.yml.example @@ -0,0 +1,191 @@ +# Prometheus configuration. Copy to prometheus.yml. +# +# Jobs for the stack's own exporters are enabled. Jobs for other Hackstack apps +# are commented out: each one needs metrics turned on in that app first (see the +# note above each job), then uncomment it and reload: +# docker compose exec prometheus kill -HUP 1 +# +# Tokens and passwords go in config/secrets/ (one per file, readable by +# uid 65534) and are mounted at /etc/prometheus/secrets/. +# +# Prometheus reaches apps by container name over nginx-proxy-net. + +global: + scrape_interval: 30s + evaluation_interval: 30s + +scrape_configs: + # --------------------------------------------------------------------------- + # This stack + # --------------------------------------------------------------------------- + - job_name: prometheus + static_configs: + - targets: ["localhost:9090"] + + # Host CPU, memory, disk, network, filesystems + - job_name: node + static_configs: + - targets: ["node-exporter:9100"] + + # Per-container CPU, memory, network, disk I/O + - job_name: cadvisor + static_configs: + - targets: ["cadvisor:8080"] + + # UPS status from apps/upsd (via nut-exporter) + - job_name: nut + metrics_path: /ups_metrics + static_configs: + - targets: ["nut-exporter:9199"] + # Uncomment to pick a UPS by name when upsd serves more than one + # params: + # ups: ["ups"] + + # --------------------------------------------------------------------------- + # apps/ + # --------------------------------------------------------------------------- + + # apps/home-assistant - all HA entities (including MQTT/zigbee2mqtt/ESPHome sensors). + # Add to configuration.yaml and restart HA: + # prometheus: + # namespace: hass + # Create a long-lived access token (Profile → Security) and save it as + # config/secrets/home-assistant-token. + # - job_name: home-assistant + # metrics_path: /api/prometheus + # authorization: + # credentials_file: /etc/prometheus/secrets/home-assistant-token + # static_configs: + # - targets: ["home-assistant:8123"] + + # apps/authentik - served on port 9300 by default, no auth. + # The worker also exposes :9300 but is only on postgres-net/postfix-net. + # - job_name: authentik + # static_configs: + # - targets: ["authentik-server:9300"] + + # apps/jellyfin - set true in its config/system.xml + # and restart. There is no UI toggle. + # - job_name: jellyfin + # static_configs: + # - targets: ["jellyfin:8096"] + + # apps/llama-cpp - add LLAMA_ARG_ENDPOINT_METRICS=1 to apps/llama-cpp/.env + # - job_name: llama-cpp + # static_configs: + # - targets: ["llama-cpp:8080"] + + # apps/vllm - /metrics is always on. Needs COMPOSE_ACCESS to include + # docker-compose.networks.yml; with only the published port, use + # host.docker.internal:8000 instead. + # - job_name: vllm + # static_configs: + # - targets: ["vllm:8000"] + + # apps/litellm - add to its config.yaml: + # litellm_settings: + # callbacks: ["prometheus"] + # Save the master key (or a virtual key) as config/secrets/litellm-key. + # - job_name: litellm + # authorization: + # credentials_file: /etc/prometheus/secrets/litellm-key + # static_configs: + # - targets: ["litellm:4000"] + + # apps/watchtower - add to apps/watchtower/.env: + # WATCHTOWER_HTTP_API_METRICS=true + # WATCHTOWER_HTTP_API_TOKEN= + # and join watchtower to prometheus-net (it has no shared network today). + # Save the token as config/secrets/watchtower-token. + # - job_name: watchtower + # metrics_path: /v1/metrics + # authorization: + # credentials_file: /etc/prometheus/secrets/watchtower-token + # static_configs: + # - targets: ["watchtower:8080"] + + # --------------------------------------------------------------------------- + # experiments/ + # --------------------------------------------------------------------------- + + # experiments/forgejo - add to its .env: + # FORGEJO__metrics__ENABLED=true + # FORGEJO__metrics__TOKEN= (optional but recommended) + # Save the token as config/secrets/forgejo-token. + # - job_name: forgejo + # authorization: + # credentials_file: /etc/prometheus/secrets/forgejo-token + # static_configs: + # - targets: ["forgejo:3000"] + + # experiments/headscale - in config/config.yaml change + # metrics_listen_addr: 127.0.0.1:9090 → 0.0.0.0:9090 + # Don't publish that port; it also serves /debug. + # - job_name: headscale + # static_configs: + # - targets: ["headscale:9090"] + + # experiments/matrix (Synapse) - in homeserver.yaml add: + # enable_metrics: true + # and a listener: + # - port: 9000 + # type: metrics + # bind_addresses: ["0.0.0.0"] + # - job_name: synapse + # metrics_path: /_synapse/metrics + # static_configs: + # - targets: ["synapse:9000"] + + # experiments/qdrant - /metrics is always on. If QDRANT__SERVICE__API_KEY is + # set, add an authorization block with that key. + # - job_name: qdrant + # static_configs: + # - targets: ["qdrant:6333"] + + # experiments/uptime-kuma - monitor up/down, response times, cert expiry. + # Create an API key (Settings → API Keys) and save it as + # config/secrets/uptime-kuma-api-key. The username is ignored. + # - job_name: uptime-kuma + # basic_auth: + # username: prometheus + # password_file: /etc/prometheus/secrets/uptime-kuma-api-key + # static_configs: + # - targets: ["uptime-kuma:3001"] + + # experiments/tailscale - add TS_ENABLE_METRICS=true to its .env. Served on + # TS_LOCAL_ADDR_PORT (0.0.0.0:9002), alongside the health check. + # - job_name: tailscale + # static_configs: + # - targets: ["tailscale:9002"] + + # experiments/copyparty - add `stats` to [global] in copyparty.conf. + # Needs an admin account; save its password as config/secrets/copyparty-password. + # - job_name: copyparty + # metrics_path: /.cpr/metrics + # basic_auth: + # username: admin + # password_file: /etc/prometheus/secrets/copyparty-password + # static_configs: + # - targets: ["copyparty:3923"] + + # --------------------------------------------------------------------------- + # SNMP (uncomment snmp-exporter in docker-compose.yml first) + # --------------------------------------------------------------------------- + # One job per profile ("module"). List the devices to poll under targets; + # Prometheus passes each one to snmp-exporter. + # - job_name: snmp-if-mib + # metrics_path: /snmp + # params: + # auth: [public_v2] + # module: [if_mib] + # static_configs: + # - targets: + # - 192.168.1.1 # router + # - 192.168.1.2 # switch + # relabel_configs: + # - source_labels: [__address__] + # target_label: __param_target + # - source_labels: [__param_target] + # target_label: instance + # - target_label: __address__ + # replacement: snmp-exporter:9116 diff --git a/experiments/prometheus/docker-compose.yml b/experiments/prometheus/docker-compose.yml new file mode 100644 index 0000000..053a1d3 --- /dev/null +++ b/experiments/prometheus/docker-compose.yml @@ -0,0 +1,102 @@ +services: + prometheus: + image: prom/prometheus:${IMAGE_VERSION:-latest} + container_name: prometheus + hostname: prometheus + restart: unless-stopped + command: + - --config.file=/etc/prometheus/prometheus.yml + - --storage.tsdb.path=/prometheus + - --storage.tsdb.retention.time=${PROMETHEUS_RETENTION:-90d} + volumes: + - ./config:/etc/prometheus:ro + - ../../lib/prometheus:/prometheus + env_file: + - .env + extra_hosts: + # lets jobs reach services that only publish ports on the host (e.g. upsd) + - host.docker.internal:host-gateway +# ports: +# - 9090:9090 + networks: + - prometheus + - proxy + healthcheck: + test: ["CMD-SHELL", "wget -q --spider http://127.0.0.1:9090/-/healthy || exit 1"] + interval: 30s + timeout: 5s + retries: 3 + start_period: 30s + + node-exporter: + image: prom/node-exporter:${NODE_EXPORTER_IMAGE_VERSION:-latest} + container_name: node-exporter + hostname: node-exporter + restart: unless-stopped + command: + - --path.rootfs=/host + pid: host + volumes: + - /:/host:ro,rslave + networks: + - prometheus + healthcheck: + test: ["CMD-SHELL", "wget -q --spider http://127.0.0.1:9100/metrics || exit 1"] + interval: 30s + timeout: 5s + retries: 3 + start_period: 10s + + cadvisor: + image: gcr.io/cadvisor/cadvisor:${CADVISOR_IMAGE_VERSION:-latest} + container_name: cadvisor + hostname: cadvisor + restart: unless-stopped + privileged: true + devices: + - /dev/kmsg + command: + - --docker_only=true + - --housekeeping_interval=30s + volumes: + - /:/rootfs:ro + - /var/run:/var/run:ro + - /sys:/sys:ro + - /var/lib/docker:/var/lib/docker:ro + - /dev/disk:/dev/disk:ro + networks: + - prometheus + healthcheck: + test: ["CMD-SHELL", "wget -q --spider http://127.0.0.1:8080/healthz || exit 1"] + interval: 30s + timeout: 5s + retries: 3 + start_period: 10s + + nut-exporter: + image: ghcr.io/druggeri/nut_exporter:${NUT_EXPORTER_IMAGE_VERSION:-latest} + container_name: nut-exporter + hostname: nut-exporter + restart: unless-stopped + env_file: + - .env + extra_hosts: + - host.docker.internal:host-gateway + networks: + - prometheus + +# Uncomment when there's network gear to poll; see README +# snmp-exporter: +# image: prom/snmp-exporter:${SNMP_EXPORTER_IMAGE_VERSION:-latest} +# container_name: snmp-exporter +# hostname: snmp-exporter +# restart: unless-stopped +# networks: +# - prometheus + +networks: + prometheus: + name: prometheus-net + proxy: + external: true + name: nginx-proxy-net diff --git a/experiments/qdrant/.rsync-exclude b/experiments/qdrant/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/experiments/rtl_433/.rsync-exclude b/experiments/rtl_433/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/experiments/rtlamr2mqtt/.rsync-exclude b/experiments/rtlamr2mqtt/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/experiments/stable-diffusion-webui/.rsync-exclude b/experiments/stable-diffusion-webui/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/experiments/telegraf/.rsync-exclude b/experiments/telegraf/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/experiments/trimetd/.rsync-exclude b/experiments/trimetd/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/experiments/unifi-audit-daemon/.env.example b/experiments/unifi-audit-daemon/.env.example new file mode 100644 index 0000000..8aacbb8 --- /dev/null +++ b/experiments/unifi-audit-daemon/.env.example @@ -0,0 +1,81 @@ +IMAGE_VERSION=latest + +# --- UniFi Protect ----------------------------------------------------------- + +# The UniFi OS console running Protect: an address or host name. +UNIFI_HOST=192.168.1.1 + +# HTTPS port on the console. +# UNIFI_PORT=443 + +# A local UniFi OS account (not a UI.com cloud account) that can view +# Protect. The private API signs in as this user. +UNIFI_USERNAME=audit-daemon +UNIFI_PASSWORD=REPLACE_ME + +# Consoles ship with a self-signed certificate; set false to accept it. +# UNIFI_VERIFY_SSL=true + +# --- Audit log --------------------------------------------------------------- + +# Where the audit log and sync state are kept: private, never serve it. +# The image sets /data. +# DATA_DIR=data + +# Seconds between syncs with Protect. +# SYNC_INTERVAL=60 + +# Seconds each sync re-reads before where the last one stopped, for events +# Protect files late. Duplicates are dropped. +# SYNC_OVERLAP=600 + +# Days of history to fetch on the very first sync. +# BACKFILL_DAYS=7 + +# Only record these event types (comma-separated); empty records all. +# EVENT_TYPES=access,videoExported,videoDeleted,nvrSettingsChanged,deviceAdopted,deviceUnadopted + +# --- Contact sheet ----------------------------------------------------------- + +# Where the contact sheets are kept, apart from the audit log, so this +# directory alone can be served. Must not contain DATA_DIR. The image sets +# /contact-sheets. +# CONTACT_SHEET_DIR=contact-sheets + +# Optional second token that can only read the contact sheets (list and +# images), to share with whoever views them. At least 16 characters, and +# different from API_TOKEN. +# CONTACT_SHEET_TOKEN=REPLACE_ME_WITH_ANOTHER_LONG_RANDOM_TOKEN + +# Local time to take the nightly contact sheet, HH:MM. +# CONTACT_SHEET_TIME=03:00 + +# Time zone for CONTACT_SHEET_TIME and the sheet's date. Without it a +# container runs on UTC. +TZ=America/Los_Angeles + +# Days of contact sheets to keep; 0 keeps them all. +# CONTACT_SHEET_RETENTION_DAYS=30 + +# Width in pixels of each camera's picture on the sheet. +# CONTACT_SHEET_TILE_WIDTH=640 + +# Cameras per row; 0 picks a near-square grid. +# CONTACT_SHEET_COLUMNS=0 + +# --- HTTP API ---------------------------------------------------------------- + +# Bearer token clients (Member Zone) must send. At least 16 characters; +# generate one with: python3 -c "import secrets; print(secrets.token_urlsafe(32))" +API_TOKEN=REPLACE_ME_WITH_A_LONG_RANDOM_TOKEN + +# Address to listen on. The Docker image sets 0.0.0.0; natively the +# default, 127.0.0.1, keeps the app private to this machine. +# HOST=127.0.0.1 + +# Port to listen on. +# Fixed at 8000 here; the health check in docker-compose.yml expects it. +PORT=8000 + +# DEBUG, INFO, WARNING, ERROR or CRITICAL. +LOG_LEVEL=INFO diff --git a/experiments/unifi-audit-daemon/.gitignore b/experiments/unifi-audit-daemon/.gitignore new file mode 100644 index 0000000..4c49bd7 --- /dev/null +++ b/experiments/unifi-audit-daemon/.gitignore @@ -0,0 +1 @@ +.env diff --git a/experiments/unifi-audit-daemon/README.md b/experiments/unifi-audit-daemon/README.md new file mode 100644 index 0000000..a25056f --- /dev/null +++ b/experiments/unifi-audit-daemon/README.md @@ -0,0 +1,63 @@ +# unifi-audit-daemon (experiment) + +[unifi-audit-daemon](https://github.com/romkey/unifi-audit-daemon) keeps a complete, append-only audit log of UniFi Protect events and takes a nightly contact sheet: one still from every camera on a single JPEG. It uses Protect's private API, which can list past events, so it catches up after downtime. It serves the log and the sheets over a small HTTP API, which [Member Zone](https://github.com/pdxhackerspace/member-zone) (`apps/member-zone`) pulls into its audit logs. + +## Configuration + +### Environment Variables + +Copy `.env.example` to `.env` and configure: + +```bash +cp .env.example .env +# Edit .env with your settings +``` + +| Variable | Notes | +|----------|-------| +| `UNIFI_HOST` | The UniFi OS console running Protect | +| `UNIFI_USERNAME` / `UNIFI_PASSWORD` | A local UniFi OS account (not a UI.com cloud account) that can view Protect | +| `UNIFI_VERIFY_SSL` | Set `false` if the console still has its self-signed certificate | +| `API_TOKEN` | Bearer token Member Zone sends; at least 16 characters | +| `CONTACT_SHEET_TOKEN` | Optional read-only token for the contact sheets only | + +Generate tokens with: + +```bash +python3 -c "import secrets; print(secrets.token_urlsafe(32))" +``` + +See [docs/configuration.md](https://github.com/romkey/unifi-audit-daemon/blob/main/docs/configuration.md) and [docs/api.md](https://github.com/romkey/unifi-audit-daemon/blob/main/docs/api.md) for everything else. + +### Data directories + +The container runs as uid 10001: + +```bash +mkdir -p ../../lib/unifi-audit-daemon/data ../../lib/unifi-audit-daemon/contact-sheets +sudo chown -R 10001:10001 ../../lib/unifi-audit-daemon +``` + +`data/` holds the audit log as JSON Lines files; it's never served and is backed up with the rest of `../../lib`. `contact-sheets/` holds the nightly sheets, kept separate so it can be shared on its own. + +Member Zone reaches the API at `http://unifi-audit-daemon:8000` over `nginx-proxy-net`. Only proxy it if you want the contact sheets viewable from outside. + +## Usage + +### Starting the service + +```bash +docker compose up -d +``` + +### Stopping the service + +```bash +docker compose down +``` + +### Viewing logs + +```bash +docker compose logs -f +``` diff --git a/experiments/unifi-audit-daemon/docker-compose.yml b/experiments/unifi-audit-daemon/docker-compose.yml new file mode 100644 index 0000000..e193610 --- /dev/null +++ b/experiments/unifi-audit-daemon/docker-compose.yml @@ -0,0 +1,39 @@ +services: + unifi-audit-daemon: + image: ghcr.io/romkey/unifi-audit-daemon:${IMAGE_VERSION:-latest} + container_name: unifi-audit-daemon + hostname: unifi-audit-daemon + restart: unless-stopped + env_file: + - .env + read_only: true + tmpfs: + - /tmp + cap_drop: + - ALL + security_opt: + - no-new-privileges:true + volumes: + # The audit log and sync state: private, never serve it + - ../../lib/unifi-audit-daemon/data:/data + # Nightly contact sheets, kept apart so they can be shared on their own + - ../../lib/unifi-audit-daemon/contact-sheets:/contact-sheets +# ports: +# - 8000:8000 + networks: + - proxy + healthcheck: + test: + - CMD + - python + - -c + - import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/healthz', timeout=3) + interval: 30s + timeout: 5s + retries: 3 + start_period: 10s + +networks: + proxy: + external: true + name: nginx-proxy-net diff --git a/experiments/unifi-occupancy/.env.example b/experiments/unifi-occupancy/.env.example new file mode 100644 index 0000000..a1a327c --- /dev/null +++ b/experiments/unifi-occupancy/.env.example @@ -0,0 +1,89 @@ +IMAGE_VERSION=latest +TZ=America/Los_Angeles + +# --------------------------------------------------------------------------- +# UniFi Protect +# --------------------------------------------------------------------------- +# Hostname or IP of the UniFi OS console (UDM / UNVR / Cloud Key). +UNIFI_HOST=192.168.1.1 +# Create under UniFi OS -> Settings -> Admins & Users -> your user -> API Keys. +UNIFI_API_KEY=changeme +#UNIFI_PORT=443 +# UniFi ships a self-signed certificate; set true only if you installed a real one. +#UNIFI_VERIFY_SSL=false +# Seconds between full camera polls. +#UNIFI_POLL_INTERVAL=5 +#UNIFI_REQUEST_TIMEOUT=10 +# Subscribe to the live event websocket in addition to polling. +#UNIFI_USE_WEBSOCKET=true + +# --------------------------------------------------------------------------- +# MQTT +# --------------------------------------------------------------------------- +MQTT_HOST=mosquitto +#MQTT_PORT=1883 +#MQTT_USERNAME= +#MQTT_PASSWORD= +#MQTT_CLIENT_ID=unifi-occupancy +#MQTT_TOPIC_PREFIX=unifi-occupancy +#MQTT_TLS=false +#MQTT_KEEPALIVE=60 +#MQTT_RETAIN=true +#MQTT_QOS=0 + +# --------------------------------------------------------------------------- +# Home Assistant autodiscovery +# --------------------------------------------------------------------------- +#HA_DISCOVERY_ENABLED=true +#HA_DISCOVERY_PREFIX=homeassistant +#HA_NODE_ID=unifi_occupancy + +# --------------------------------------------------------------------------- +# Behaviour +# --------------------------------------------------------------------------- +# How long a detection stays ON after the last event reporting it. +#DETECTION_HOLD_SECONDS=30 +#LOG_LEVEL=INFO + +# --------------------------------------------------------------------------- +# Camera health check (optional, off by default, and the one feature that +# reads pictures) +# --------------------------------------------------------------------------- +# Once an hour, take one snapshot per camera and ask a vision model whether the +# camera still sees anything useful -- is it blocked, smeared, fogged, out of +# focus, pointed at a wall? The verdict is published on +# unifi-occupancy//health as {"health": "good"} or +# {"health": "bad", "explanation": "..."}. +# +# Leaving this unset keeps the service as it was: no snapshot endpoint is ever +# called, and nothing leaves the process but booleans. +#CAMERA_HEALTH_ENABLED=false +# Any OpenAI-compatible /chat/completions endpoint: OpenAI, OpenRouter, or a +# local Ollama / llama.cpp / vLLM / LM Studio server. +#CAMERA_HEALTH_API_BASE_URL=https://api.openai.com/v1 +# Local models on llama-net (uncomment the llama network in docker-compose.yml): +#CAMERA_HEALTH_API_BASE_URL=http://ollama:11434/v1 +# Optional -- local servers usually want no key at all. +#CAMERA_HEALTH_API_KEY= +# Must be a model that can see images. +#CAMERA_HEALTH_MODEL=gpt-4o-mini +#CAMERA_HEALTH_INTERVAL_MINUTES=60 +# Seconds between one camera's check and the next, so a sweep is a trickle. +#CAMERA_HEALTH_STAGGER_SECONDS=5 +#CAMERA_HEALTH_REQUEST_TIMEOUT=60 +# Full-resolution snapshots: a better look, a bigger upload, a larger bill. +#CAMERA_HEALTH_HIGH_QUALITY_SNAPSHOT=false +#CAMERA_HEALTH_MAX_EXPLANATION_CHARS=200 +# The question itself. The built-in prompt is the one below; override it to +# tighten it up for your cameras, or to answer in another language. Whatever it +# says, it should ask for {"health": "good"} or {"health": "bad", +# "explanation": "..."} -- a bare "good"/"bad" is understood too. +#CAMERA_HEALTH_PROMPT=You are inspecting a single still frame from a fixed security camera to decide whether the camera itself is still producing a usable picture. You are not judging whether anything interesting is happening in the scene. Answer bad if the view is obstructed or blocked (a wall, a vehicle, foliage, a cover, tape, a hand), out of focus, blurred or smeared, dirty, fogged by condensation or spiderweb, washed out by glare or an infrared reflection off a nearby surface, almost entirely black or entirely white, visibly corrupted (banding, tearing, a green or magenta cast), or aimed somewhere useless such as straight at the sky, the ground or a ceiling. Answer good if the frame shows a usable view of whatever it is pointed at, even if it is dull, empty, grainy, rainy, snowy or lit only by infrared at night. Night-time darkness on its own is not a fault; an image with no discernible structure at all is. Reply with JSON and nothing else: {"health": "good"} or {"health": "bad", "explanation": ""}. + +# --------------------------------------------------------------------------- +# Daily occupancy sheets +# --------------------------------------------------------------------------- +# Camera groups, times of day and where the sheets go live in a YAML file; +# see config.example.yaml. If the file does not exist, no history is recorded +# and no sheets are written. +#CONFIG_FILE=/config/config.yaml diff --git a/experiments/unifi-occupancy/.gitignore b/experiments/unifi-occupancy/.gitignore new file mode 100644 index 0000000..6171c1a --- /dev/null +++ b/experiments/unifi-occupancy/.gitignore @@ -0,0 +1,2 @@ +.env +config/config.yaml diff --git a/experiments/unifi-occupancy/.rsync.exclude b/experiments/unifi-occupancy/.rsync.exclude new file mode 100644 index 0000000..b55af8d --- /dev/null +++ b/experiments/unifi-occupancy/.rsync.exclude @@ -0,0 +1,3 @@ +lib/unifi-occupancy/data/occupancy.sqlite3 +lib/unifi-occupancy/data/occupancy.sqlite3-wal +lib/unifi-occupancy/data/occupancy.sqlite3-shm diff --git a/experiments/unifi-occupancy/README.md b/experiments/unifi-occupancy/README.md new file mode 100644 index 0000000..e8208de --- /dev/null +++ b/experiments/unifi-occupancy/README.md @@ -0,0 +1,63 @@ +# unifi-occupancy (experiment) + +[unifi-occupancy](https://github.com/romkey/unifi-occupancy) publishes UniFi Protect detection state (motion, person, vehicle, animal and so on) per camera to MQTT, with Home Assistant discovery. It only passes along on/off detection state, never pictures. Optionally it writes daily HTML occupancy sheets and runs an hourly camera health check against a vision model. + +## Configuration + +### Environment Variables + +Copy `.env.example` to `.env` and configure: + +```bash +cp .env.example .env +# Edit .env with your settings +``` + +| Variable | Notes | +|----------|-------| +| `UNIFI_HOST` | The UniFi OS console (UDM / UNVR / Cloud Key) | +| `UNIFI_API_KEY` | UniFi OS → Settings → Admins & Users → your user → API Keys | +| `MQTT_HOST` / `MQTT_USERNAME` / `MQTT_PASSWORD` | `apps/mosquitto`, reached on `mosquitto-net` | + +See the [project README](https://github.com/romkey/unifi-occupancy#configuration) for everything else. + +### Camera health check (optional) + +Set `CAMERA_HEALTH_ENABLED=true` and point `CAMERA_HEALTH_API_BASE_URL` at any OpenAI-compatible endpoint with a vision model. For a local model, uncomment the `llama` network in `docker-compose.yml`. + +### Occupancy sheets (optional) + +```bash +cp config/config.yaml.example config/config.yaml +``` + +The sheets are only written when `config/config.yaml` exists. They go to `../../lib/unifi-occupancy/www` as static HTML; the service doesn't serve them itself, so point a web server at that directory to view them. + +### Data directories + +The container runs as uid 10001: + +```bash +mkdir -p ../../lib/unifi-occupancy/www ../../lib/unifi-occupancy/data +sudo chown -R 10001:10001 ../../lib/unifi-occupancy +``` + +## Usage + +### Starting the service + +```bash +docker compose up -d +``` + +### Stopping the service + +```bash +docker compose down +``` + +### Viewing logs + +```bash +docker compose logs -f +``` diff --git a/experiments/unifi-occupancy/config/config.yaml.example b/experiments/unifi-occupancy/config/config.yaml.example new file mode 100644 index 0000000..e23d0ae --- /dev/null +++ b/experiments/unifi-occupancy/config/config.yaml.example @@ -0,0 +1,68 @@ +# --------------------------------------------------------------------------- +# unifi-occupancy: camera groups and daily occupancy sheets +# +# Copy to config/config.yaml (mounted at /config/config.yaml in the +# container) and edit. Protect and MQTT are configured in .env, not here. +# +# This file existing is what switches the sheets on. Without it the service +# behaves exactly as it always has: MQTT only, nothing written to disk. +# --------------------------------------------------------------------------- + +# IANA zone name. Days, midnights and the periods below are all local to it. +# Defaults to $TZ, or UTC. +timezone: America/Los_Angeles + +reports: + # Set false to keep the config file but stop writing sheets. + enabled: true + + # Where the HTML goes. index.html and one YYYY-MM-DD.html per day. + output_dir: /var/www/html + + # The detection history. Must be on a writable volume. + database: /var/lib/unifi-occupancy/occupancy.sqlite3 + + # Heading on every page. + title: Occupancy + + # How often the current day's sheet is rewritten. 60 means on the hour; the + # last write of a day always lands on local midnight, which is what starts + # the next day's sheet. + refresh_minutes: 60 + + # Width of one bucket on the density strip. 10 gives 144 buckets a day. + bucket_minutes: 10 + + # Days of detection history to keep. 0 keeps everything -- a busy household + # is on the order of a megabyte a month. Pruning never removes a sheet or + # its counts, only the per-event detail behind them. + retention_days: 0 + +# Times of day, shaded as bands behind every timeline. Any number of them, +# with any names; each runs until the next one starts, and the last wraps +# around midnight. Quote the times. +periods: + - name: Night + start: "00:00" + - name: Morning + start: "06:00" + - name: Afternoon + start: "12:00" + - name: Evening + start: "18:00" + +# Cameras that cover one area, reported together. Name them as they are named +# in Protect; a slug (front_door) or a Protect id works too. Any camera not +# listed here gets a section of its own. Delete this whole block to treat +# every camera separately. +groups: + - name: Front of house + cameras: + - Front Door + - Driveway + - Porch + + - name: Back yard + cameras: + - Back Yard + - Garage diff --git a/experiments/unifi-occupancy/docker-compose.yml b/experiments/unifi-occupancy/docker-compose.yml new file mode 100644 index 0000000..20c8b1c --- /dev/null +++ b/experiments/unifi-occupancy/docker-compose.yml @@ -0,0 +1,34 @@ +services: + unifi-occupancy: + image: ghcr.io/romkey/unifi-occupancy:${IMAGE_VERSION:-latest} + container_name: unifi-occupancy + hostname: unifi-occupancy + restart: unless-stopped + env_file: + - .env + read_only: true + tmpfs: + - /tmp + cap_drop: + - ALL + security_opt: + - no-new-privileges:true + volumes: + # Camera groups and periods. The daily occupancy sheets are only written + # when config/config.yaml exists. + - ./config:/config:ro + # The generated HTML sheets + - ../../lib/unifi-occupancy/www:/var/www/html + # The detection history the sheets are built from + - ../../lib/unifi-occupancy/data:/var/lib/unifi-occupancy + networks: + - mqtt +# - llama + +networks: + mqtt: + external: true + name: mosquitto-net +# llama: +# external: true +# name: llama-net diff --git a/experiments/uptime-kuma/.rsync-exclude b/experiments/uptime-kuma/.rsync-exclude deleted file mode 100644 index e69de29..0000000 diff --git a/experiments/uptime-kuma/README.md b/experiments/uptime-kuma/README.md index be22708..721cf75 100644 --- a/experiments/uptime-kuma/README.md +++ b/experiments/uptime-kuma/README.md @@ -2,7 +2,7 @@ [Uptime Kuma](https://github.com/louislam/uptime-kuma) is a self-hosted uptime monitor and status page. It probes HTTP(S), TCP, ping, DNS, MQTT and Docker container targets on a schedule, keeps history, and sends notifications (email, Matrix, MQTT, ntfy, webhooks, and many more) when something goes down. -This overlaps with **`apps/statping`**; it is here as an experiment so the two can be compared before either becomes part of the core stack. +It replaces **`deprecated/statping`**. ## Prerequisites @@ -26,7 +26,7 @@ Everything else (monitors, notifications, status pages, the admin account) is co ### Database -**PostgreSQL is not an option here.** Uptime Kuma supports only SQLite and MariaDB/MySQL; anything else is rejected at startup with `Unknown Database type`. MariaDB support is what shipped in 2.0, and Postgres was deferred to a future major release because it needs parts of the query layer rewritten — see [PR #3748](https://github.com/louislam/uptime-kuma/pull/3748) (closed) and [issue #959](https://github.com/louislam/uptime-kuma/issues/959) (open, no target release). If a Postgres-backed monitor is a requirement, **`apps/statping`** already uses `postgres-net`. +**PostgreSQL is not an option here.** Uptime Kuma supports only SQLite and MariaDB/MySQL; anything else is rejected at startup with `Unknown Database type`. MariaDB support is what shipped in 2.0, and Postgres was deferred to a future major release because it needs parts of the query layer rewritten — see [PR #3748](https://github.com/louislam/uptime-kuma/pull/3748) (closed) and [issue #959](https://github.com/louislam/uptime-kuma/issues/959) (open, no target release). The (now deprecated) **`deprecated/statping`** used `postgres-net`. By default Uptime Kuma keeps everything in SQLite under **`../../lib/uptime-kuma`**, which is fine for a few dozen monitors and needs no setup. @@ -55,7 +55,7 @@ If the UI loads but the dashboard stays disconnected, the websocket origin check ## Networks - **`nginx-proxy-net`** — browser access via proxy -- optional, commented out — `mariadb-net`, `postgres-net`, `mosquitto-net`, `hass-net`, `influxdb-net` for monitoring those services by container name +- optional, commented out — `mariadb-net`, `postgres-net`, `mosquitto-net`, `hass-net` for monitoring those services by container name ## Usage diff --git a/experiments/uptime-kuma/docker-compose.yml b/experiments/uptime-kuma/docker-compose.yml index 357b3e1..32f00c5 100644 --- a/experiments/uptime-kuma/docker-compose.yml +++ b/experiments/uptime-kuma/docker-compose.yml @@ -26,7 +26,6 @@ services: - postgres - mosquitto - hass - # - influxdb networks: proxy: @@ -44,6 +43,3 @@ networks: hass: external: true name: hass-net -# influxdb: -# external: true -# name: influxdb-net From 647d7ca4b03efae84f739bb07ca49877108a6c3a Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 16 Nov 2026 17:45:08 +0000 Subject: [PATCH 2/4] Update top-level .rsync.exclude from per-app files --- .rsync.exclude | 47 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 46 insertions(+), 1 deletion(-) diff --git a/.rsync.exclude b/.rsync.exclude index 9f4e2c4..bdbf7d3 100644 --- a/.rsync.exclude +++ b/.rsync.exclude @@ -1,8 +1,53 @@ # Do not edit .rsync.exclude -# File is automatically built from .rsync.exclude.inital and */.rsync.exclude +# Built by .github/workflows/concatenate_rsync_exclude.yml from +# .rsync.exclude.initial and apps/*/.rsync.exclude, experiments/*/.rsync.exclude lost+found/ containerd/ docker/ run/ **/*.log + +# [apps] apps/calibre-web/.rsync.exclude +lib/calibre-web/metadatab.db + +# [apps] apps/esphome/.rsync.exclude +lib/esphome/.esphome + +# [apps] apps/home-assistant/.rsync.exclude +lib/home-assistant/backups + +# [apps] apps/jellyfin/.rsync.exclude +lib/jellyfin/data/jellyfin.db +lib/jellyfin/data/jellyfin.db-shm +lib/jellyfin/data/jellyfin.db-wal +lib/jellyfin/data/library.db +lib/jellyfin/data/library.db-shm +lib/jellyfin/data/library.db-wal + +# [apps] apps/mariadb/.rsync.exclude +lib/mariadb + +# [apps] apps/mosquitto/.rsync.exclude +lib/mosquitto/mosquitto.db + +# [apps] apps/music-assistant/.rsync.exclude +lib/music-assistant/cache.db +lib/music-assistant/library.db + +# [apps] apps/nginx-proxy-manager/.rsync.exclude +lib/nginx-proxy-manager/database.sqlite + +# [apps] apps/postgresql/.rsync.exclude +lib/postgresql + +# [experiments] experiments/komodo/.rsync.exclude +lib/komodo/mongo + +# [experiments] experiments/prometheus/.rsync.exclude +lib/prometheus + +# [experiments] experiments/unifi-occupancy/.rsync.exclude +lib/unifi-occupancy/data/occupancy.sqlite3 +lib/unifi-occupancy/data/occupancy.sqlite3-wal +lib/unifi-occupancy/data/occupancy.sqlite3-shm From 92ee5c883887b0f58198bd12f0c49f75c55e4f3a Mon Sep 17 00:00:00 2001 From: John Romkey <58883+romkey@users.noreply.github.com> Date: Mon, 16 Nov 2026 09:47:15 -0800 Subject: [PATCH 3/4] validate_compose: understand overlays, Compose merge tags and app-prefixed names - Parse !override and !reset instead of failing with a YAML error. - Don't require restart, healthcheck or networks in docker-compose..yml overlays; those come from the base file they're merged onto. - Accept and - as container_name/hostname, the naming AGENTS.md documents for multi-service apps. - Allow Komodo's bundled MongoDB (no shared MongoDB exists). - Mark the ports overlays with `# hackstack: ports required`. Co-Authored-By: Claude Opus 5.5 --- .github/scripts/validate_compose.py | 49 +++++++++++++++++--- apps/llama-cpp/docker-compose.ports.yml | 1 + apps/vllm/docker-compose.ports.yml | 1 + experiments/comfyui/docker-compose.ports.yml | 1 + 4 files changed, 46 insertions(+), 6 deletions(-) diff --git a/.github/scripts/validate_compose.py b/.github/scripts/validate_compose.py index 7b55dfa..076af88 100644 --- a/.github/scripts/validate_compose.py +++ b/.github/scripts/validate_compose.py @@ -14,6 +14,31 @@ from typing import Optional +class ComposeLoader(yaml.SafeLoader): + """SafeLoader that accepts Compose's merge tags (!override, !reset).""" + + +def _compose_tag(loader, tag_suffix, node): + if isinstance(node, yaml.MappingNode): + return loader.construct_mapping(node, deep=True) + if isinstance(node, yaml.SequenceNode): + return loader.construct_sequence(node, deep=True) + return loader.construct_scalar(node) + + +ComposeLoader.add_multi_constructor('!override', _compose_tag) +ComposeLoader.add_multi_constructor('!reset', _compose_tag) + + +def is_overlay(file_path: Path) -> bool: + """docker-compose..yml files are overlays merged onto docker-compose.yml. + + Their services are fragments, so checks for keys the base file supplies + (restart, healthcheck, networks, names) don't apply to them. + """ + return file_path.name != 'docker-compose.yml' + + @dataclass class ValidationResult: """Represents a validation finding.""" @@ -65,6 +90,11 @@ def has_errors(self): r'mongo', ] +# Apps that bundle a database the shared services can't provide: (app dir, image pattern) +EMBEDDED_DB_EXCEPTIONS = { + ('komodo', 'mongo'), # Komodo Core requires MongoDB; there is no shared MongoDB +} + # Exceptions for certain rules RESTART_EXCEPTIONS = {'bfg-repo-cleaner', 'mailq', 'postfix-base'} # CLI tools and YAML anchors that shouldn't restart # Published ports require `# hackstack: ports required` in the compose file (see Rule 12). @@ -149,7 +179,7 @@ def validate_compose_file(file_path: Path, report: ValidationReport): # Parse YAML try: - data = yaml.safe_load(raw_content) + data = yaml.load(raw_content, Loader=ComposeLoader) except yaml.YAMLError as e: report.error("yaml-syntax", f"Invalid YAML: {e}", file_str) return @@ -229,8 +259,11 @@ def validate_service(service_name: str, config: dict, file_path: Path, file_str = str(file_path) service_dir = file_path.parent.name - - # Rule 3: Service name should match hostname and container_name + overlay = is_overlay(file_path) + + # Rule 3: Service name should match hostname and container_name. + # The app's directory name, and - for its other services, + # are also accepted (see AGENTS.md). hostname = config.get('hostname') container_name = config.get('container_name') @@ -245,6 +278,8 @@ def name_allowed(field: str, actual: str, expected: str) -> bool: return True if allowed_prefix and (actual.startswith(allowed_prefix) or actual == allowed_prefix): return True + if actual in (service_dir, f'{service_dir}-{service_name}'): + return True return actual == expected if hostname and not name_allowed('hostname', hostname, service_name): @@ -259,7 +294,7 @@ def name_allowed(field: str, actual: str, expected: str) -> bool: # Rule 4: restart: unless-stopped restart = config.get('restart') - if service_name not in RESTART_EXCEPTIONS: + if service_name not in RESTART_EXCEPTIONS and not overlay: if restart is None: report.error("restart-policy", "Missing 'restart: unless-stopped'", @@ -355,7 +390,7 @@ def name_allowed(field: str, actual: str, expected: str) -> bool: check_volume_path(host_path, file_str, service_name, report) # Rule 17: Healthcheck warning - if 'healthcheck' not in config: + if 'healthcheck' not in config and not overlay: report.warning("no-healthcheck", "Consider adding a healthcheck", file_str, service_name) @@ -369,7 +404,7 @@ def name_allowed(field: str, actual: str, expected: str) -> bool: # Rule 19: No networks declared (and not host mode) networks = config.get('networks') - if network_mode != 'host' and not networks: + if network_mode != 'host' and not networks and not overlay: report.warning("no-networks", "No networks declared - consider adding proxy/db networks as needed", file_str, service_name) @@ -381,6 +416,8 @@ def name_allowed(field: str, actual: str, expected: str) -> bool: # Skip if this IS the shared database service if service_dir in ('postgresql', 'mariadb', 'redis'): continue + if (service_dir, db_pattern) in EMBEDDED_DB_EXCEPTIONS: + continue # Check if image contains forbidden DB if re.search(rf'\b{db_pattern}\b', image_lower): # Exception for redis used as cache within a stack (like authentik) diff --git a/apps/llama-cpp/docker-compose.ports.yml b/apps/llama-cpp/docker-compose.ports.yml index 8bdde1f..ce24f58 100644 --- a/apps/llama-cpp/docker-compose.ports.yml +++ b/apps/llama-cpp/docker-compose.ports.yml @@ -2,5 +2,6 @@ # Enabled through COMPOSE_ACCESS in .env (see .env.example). services: llama-cpp: + # hackstack: ports required - this overlay exists to publish the port ports: - "${PUBLISHED_ADDRESS:-0.0.0.0}:${PUBLISHED_PORT:-8080}:${LLAMA_ARG_PORT:-8080}" diff --git a/apps/vllm/docker-compose.ports.yml b/apps/vllm/docker-compose.ports.yml index 41b2359..a39a37d 100644 --- a/apps/vllm/docker-compose.ports.yml +++ b/apps/vllm/docker-compose.ports.yml @@ -2,5 +2,6 @@ # Enabled through COMPOSE_ACCESS in .env (see .env.example). services: vllm: + # hackstack: ports required - this overlay exists to publish the port ports: - "${PUBLISHED_ADDRESS:-0.0.0.0}:${PUBLISHED_PORT:-8000}:8000" diff --git a/experiments/comfyui/docker-compose.ports.yml b/experiments/comfyui/docker-compose.ports.yml index 1ce1664..5fa8f52 100644 --- a/experiments/comfyui/docker-compose.ports.yml +++ b/experiments/comfyui/docker-compose.ports.yml @@ -2,5 +2,6 @@ # Enabled through COMPOSE_ACCESS in .env (see .env.example). services: comfyui: + # hackstack: ports required - this overlay exists to publish the port ports: - "${PUBLISHED_ADDRESS:-0.0.0.0}:${PUBLISHED_PORT:-8188}:8188" From 93efc3ab5cdbea60d9cd9ae4b13eaf95098811fe Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 16 Nov 2026 17:47:30 +0000 Subject: [PATCH 4/4] Update top-level .gitignore with directory paths --- .gitignore | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/.gitignore b/.gitignore index b3b963e..74dca28 100644 --- a/.gitignore +++ b/.gitignore @@ -123,12 +123,11 @@ experiments/headscale/config/config.yaml experiments/headscale/config/headplane.yaml experiments/headscale/config/acl.hujson -# [experiments] experiments/homebox/.gitignore -experiments/homebox/.env -experiments/homebox/config/config.yml +# [experiments] experiments/laser-cutterd/.gitignore +experiments/laser-cutterd/.env -# [experiments] experiments/influxdb/.gitignore -experiments/influxdb/config/influx-configs +# [experiments] experiments/library/.gitignore +experiments/library/.env # [experiments] experiments/llama-router/.gitignore experiments/llama-router/.env @@ -143,6 +142,11 @@ experiments/nextcloud/.env experiments/olah/.env experiments/olah/config/configs.toml +# [experiments] experiments/prometheus/.gitignore +experiments/prometheus/.env +experiments/prometheus/config/prometheus.yml +experiments/prometheus/config/secrets/ + # [experiments] experiments/rtlamr2mqtt/.gitignore experiments/rtlamr2mqtt/.env experiments/rtlamr2mqtt/config/rtlamr2mqtt.yaml @@ -150,13 +154,17 @@ experiments/rtlamr2mqtt/config/rtlamr2mqtt.yaml # [experiments] experiments/tailscale/.gitignore experiments/tailscale/.env -# [experiments] experiments/telegraf/.gitignore -experiments/telegraf/config/telegraf.conf - # [experiments] experiments/tranquil/.gitignore experiments/tranquil/.env experiments/tranquil/config/config.toml +# [experiments] experiments/unifi-audit-daemon/.gitignore +experiments/unifi-audit-daemon/.env + +# [experiments] experiments/unifi-occupancy/.gitignore +experiments/unifi-occupancy/.env +experiments/unifi-occupancy/config/config.yaml + # [experiments] experiments/unified-audio-players/.gitignore experiments/unified-audio-players/.env