Skip to content

Add Komodo, Prometheus and other experiments; deprecate unused apps; document conventions - #20

Merged
romkey merged 4 commits into
mainfrom
claude/komodo-experiments-support-183cf2
Nov 17, 2026
Merged

romkey merged 4 commits into
mainfrom
claude/komodo-experiments-support-183cf2

Conversation

@romkey

@romkey romkey commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

What changed

New experiments

  • komodo: core, periphery and a bundled MongoDB. Komodo needs MongoDB, which the shared database services don't provide, so it bundles its own.
  • prometheus: node-exporter, cadvisor, nut-exporter and an optional snmp-exporter. The example prometheus.yml has a commented-out job for every app in apps/ and experiments/ that can export metrics.
  • laser-cutterd: uses host networking because the Ruida controller replies to a fixed UDP port on the host. The README explains why.
  • unifi-occupancy, unifi-audit-daemon and library (pdxhackerspace/library).

Changed

  • experiments/grafana: switched to the open-source image. It now uses the shared Postgres and joins prometheus-net, and .env.example has Authentik OAuth settings.
  • apps/vllm, apps/llama-cpp, experiments/comfyui: networks and ports moved out of the base compose file into new overlays, docker-compose.networks.yml and docker-compose.ports.yml.
    • You choose between them with COMPOSE_ACCESS in .env.
    • COMPOSE_FILE is now built from per-choice variables (hardware, storage, access).
    • Ports stay commented out in the base file.
  • experiments/uptime-kuma: the commented-out influxdb network is removed.

Deprecated (moved to deprecated/): statping, camera2prusa, homebox, influxdb, osticket, portainer, stable-diffusion-webui, telegraf and chronograf. Prometheus and Grafana replace telegraf and chronograf.

Backups

  • Removed 80 empty .rsync-exclude (dash) files.
  • Fixed concatenate_rsync_exclude.yml:
    • It never found the per-app files because it only looked one directory deep. It now collects apps/*/.rsync.exclude and experiments/*/.rsync.exclude.
    • Its trigger path was wrong.
    • It now handles files without a trailing newline.
  • Documented the convention in docs/contributing.md.

Conventions

  • Added AGENTS.md (CLAUDE.md points to it) and a hackstack-app skill. They cover the compose, .env, config/ and README conventions:
    • nobody edits a compose file to deploy an app
    • no secrets in git
    • host networking only as a last resort
    • macvlan for LAN-visible apps

Notes for reviewers

  • Existing .env files for vllm, llama-cpp and comfyui need the new COMPOSE_HARDWARE / COMPOSE_ACCESS / COMPOSE_STORAGE block from .env.example. vllm's default changes from a published port to the proxy networks.
  • Checked with docker compose config for every overlay combination of vllm, llama-cpp and comfyui (152 combinations), and with promtool check config for the example Prometheus config.
  • Not checked: none of the new experiments has been run against real hardware or services.
  • The top-level .rsync.exclude will be regenerated by the workflow after merge.
  • Watchtower must join prometheus-net before Prometheus can scrape it. That isn't done here.

🤖 Generated with Claude Code


Note

Medium Risk
Large convention and compose refactor changes default LLM exposure and requires operator .env migration; new stacks add Docker-socket (Komodo) and host-network services with real deployment impact.

Overview
Adds AGENTS.md (and CLAUDE.md / hackstack-app skill) as the canonical rules: deploy only via .env and config/, overlays for structural choices, per-app .rsync.exclude, and shared DB conventions. .github/scripts/validate_compose.py now parses Compose merge tags, skips base-only rules on overlay files, allows Komodo’s bundled MongoDB, and relaxes hostname/name checks for multi-service apps.

Backup aggregation is fixed: the workflow now collects apps/** and experiments/** per-app .rsync.exclude files (correct trigger path, trailing-newline handling) and the root .rsync.exclude is rebuilt from real DB paths.

vllm, llama-cpp, and comfyui stop baking in proxy networks or published ports in the base compose file. New docker-compose.networks.yml and docker-compose.ports.yml overlays are selected with COMPOSE_ACCESS; hardware and NFS stay on COMPOSE_HARDWARE / COMPOSE_STORAGE, with COMPOSE_FILE assembled in .env.example. Default vllm access moves from a published port to Hackstack networks—existing .env files need updating.

New experiments: Prometheus (exporters, prometheus-net, example scrape jobs), Grafana (OSS image, shared Postgres, prometheus-net, richer .env.example), Komodo (core/periphery + MongoDB), library, laser-cutterd (host networking for Ruida UDP), unifi-occupancy / unifi-audit-daemon. uptime-kuma docs drop InfluxDB and point at deprecated/statping; statping is removed from bin/install-chaos.sh. Docs gain prometheus in the network reference and backup .rsync.exclude guidance.

Reviewed by Cursor Bugbot for commit 92ee5c8. Bugbot is set up for automated code reviews on this repo. Configure here.

romkey and others added 4 commits November 16, 2026 09:44
…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 <noreply@anthropic.com>
…fixed names

- Parse !override and !reset instead of failing with a YAML error.
- Don't require restart, healthcheck or networks in docker-compose.<name>.yml
  overlays; those come from the base file they're merged onto.
- Accept <app> and <app>-<service> 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 <noreply@anthropic.com>
@romkey
romkey merged commit c7564ed into main Nov 17, 2026
7 checks passed
@romkey
romkey deleted the claude/komodo-experiments-support-183cf2 branch November 17, 2026 00:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant