implemented compose by url, parse, local yaml.

README.md

@@ -257,6 +257,34 @@ instead of exposing individual host ports.
 See `host_vars/edge.yml.example`, `host_vars/downstream.yml.example`, and
 `docs/topology.md`. The full Docker service list is in `docs/service-catalog.md`.
 
+## Compose Updates
+
+Compose-backed roles deploy from role-owned Jinja templates, not directly from
+upstream examples. Upstream README and Compose examples are tracked as copied
+snapshots under each role's `upstream/` directory and indexed in
+`docs/upstream-sources.yml`.
+
+Use `compose_paths` for Compose files inside an upstream repository and
+`compose_urls` for direct raw HTTP Compose YAML fallbacks. Use role-level
+`local_compose_file` for Compose reference material already stored in this
+repository. README fenced Compose blocks are parsed when no explicit Compose
+file is available.
+
+Use `docs/compose-update-policy.md` when updating services so upstream drift,
+NBOPS overrides, image pins, and generated Compose files stay reviewable in Git.
+
+To test upstream references for one role:
+
+```sh
+scripts/vendor-upstream-snapshots.py jellyfin
+```
+
+To refresh copied upstream references:
+
+```sh
+scripts/vendor-upstream-snapshots.py --apply jellyfin
+```
+
 ## Bootstrap
 
 Render `templates/cloud-init-user-data.yml.j2` with host variables and pass it to

docs/compose-update-policy.md

@@ -0,0 +1,87 @@
+# Compose Update Policy
+
+Compose-backed services are deployed from role-owned Jinja templates. Vendored
+upstream files are reference snapshots only and must not be deployed directly.
+
+## Layout
+
+Each Docker-backed role has:
+
+- `templates/compose.yaml.j2`: base deployed Compose file
+- `templates/compose.override.yaml.j2`: NBOPS-specific local override
+- `templates/env.j2`: generated environment file
+- `upstream/`: copied upstream reference files
+
+`docs/upstream-sources.yml` is the authoritative inventory of upstream Git
+repositories, README paths, Compose paths, fallback Compose URLs, local Compose
+references, refs, and verification status.
+
+Role entries support one local fallback:
+
+- `local_compose_file`: repo-local Compose file to copy as role reference
+  material when upstream does not provide a useful Compose example.
+
+Repository entries support three upstream Compose discovery sources:
+
+- `compose_paths`: paths to Compose files inside the checked-out repository.
+- `compose_urls`: direct `http` or `https` URLs that return Compose YAML.
+- README fenced YAML blocks, parsed when a README is listed in `readme_paths`.
+
+Repository entries that only use `compose_urls` may omit `url` and `ref`.
+Entries that use `readme_paths` or `compose_paths` must include both `url` and
+`ref` so the script can clone the source repository.
+
+## Update Workflow
+
+1. Read `docs/upstream-sources.yml` for the role being updated.
+2. Test the upstream inventory without writing snapshots:
+
+   ```sh
+   scripts/vendor-upstream-snapshots.py <role>
+   ```
+
+3. Fetch or copy the listed upstream README and Compose files into
+   `roles/<role>/upstream/`:
+
+   ```sh
+   scripts/vendor-upstream-snapshots.py --apply <role>
+   ```
+
+   The script also looks for Compose-shaped fenced YAML blocks in README files.
+   When exactly one candidate is found, `--apply` writes it as
+   `compose.from-readme.yaml`. Compose YAML fetched from `compose_urls` is
+   written as `compose.from-url.yaml`, or `compose.from-url-N.yaml` when a
+   repository has multiple fallback URLs. A role-level `local_compose_file` is
+   copied under `roles/<role>/upstream/local/`.
+4. Update `roles/<role>/upstream/SOURCE.md` with source URL, ref, snapshot date,
+   fetched paths, and any manual verification notes.
+5. Commit upstream snapshot changes separately from NBOPS deployment template
+   changes.
+6. Diff upstream snapshots against current role templates.
+7. Apply upstream structural changes to `templates/compose.yaml.j2`.
+8. Keep NBOPS-local changes in `templates/compose.override.yaml.j2`, including:
+   Traefik labels, internal networks, host paths, ports, restart policy, logging,
+   resource limits, and deployment-specific environment wiring.
+9. Replace mutable image tags with pinned versions where practical.
+10. Document breaking changes or operator actions in the role README.
+
+## Rules
+
+- Do not edit generated Compose files on VMs.
+- Do not deploy files from `upstream/` directly.
+- Do not treat `status: verify` sources as trusted until manually checked.
+- Prefer pinned tags or digests over `latest` and other mutable tags.
+- Keep HTTP application ports unpublished in Traefik mode; document internal
+  service ports as comments in generated Compose.
+
+## Validation
+
+Run after every Compose template update:
+
+```sh
+ansible-playbook --syntax-check playbooks/site.yml
+git diff --check
+```
+
+Later, add a render check that runs `docker compose config` against generated
+`compose.yaml` plus `compose.override.yaml` for selected roles.

docs/service-catalog.md

@@ -54,10 +54,19 @@ Monitoring:
 - `prometheus`
 - `uptime_kuma`
 
-Most roles use the shared `docker_app` implementation and support:
+Compose-backed roles use the shared `compose_project` lifecycle directly or via
+the `docker_app` single-container adapter. They support:
 
 - `host` routing mode: publish ports directly and open UFW rules.
 - `traefik` routing mode: attach to the proxy network and render Traefik labels.
+- `traefik_file` routing mode: publish service ports for central edge Traefik,
+  without rendering Docker labels. Prefer `traefik` for normal multi-VM
+  deployments so edge Traefik forwards to internal Traefik, and internal Traefik
+  routes to applications by labels.
 
 Override role defaults in `host_vars` or `group_vars`; do not edit generated
 Compose files on the VM.
+
+Upstream README and Compose examples are tracked as copied snapshots under each
+role's `upstream/` directory. See `docs/upstream-sources.yml` and
+`docs/compose-update-policy.md`.

docs/topology.md

@@ -21,9 +21,9 @@ authentik_domain: auth.example.invalid
 
 ## Downstream VMs
 
-Downstream VMs also run Docker. Instead of publishing each application port on
+Downstream VMs also run Docker and normally run an internal Traefik instance.
-the host, run Traefik on the VM and attach application containers to the shared
+Application containers route through that local Traefik using Docker labels and
-Docker proxy network.
+the shared Docker proxy network.
 
 ```yaml
 nbops_roles:
@@ -47,13 +47,85 @@ Traefik labels and join `nbops_proxy_network`, which defaults to `proxy`.
 Only Traefik entrypoints should be exposed on the downstream host firewall. Use
 `traefik_bind_address` to bind those entrypoints to the VM's internal address.
 
+For central edge routing, the edge Traefik uses the file provider to route
+machine-to-machine traffic to each downstream VM's internal Traefik entrypoint.
+The internal Traefik then routes to applications using Docker labels. This keeps
+container discovery local to the VM and gives the edge-to-internal leg a stable
+place for future mTLS.
+
+Edge VM:
+
+```yaml
+nbops_roles:
+  - base
+  - ssh
+  - ufw
+  - updates
+  - docker
+  - traefik
+
+traefik_docker_provider_enabled: false
+traefik_file_provider_enabled: true
+traefik_dynamic_inventory_group: nbops
+```
+
+Downstream VM:
+
+```yaml
+nbops_service_routing_mode: traefik
+nbops_traefik_entrypoint: web
+nbops_traefik_tls: false
+
+traefik_bind_address: "10.0.10.25"
+traefik_publish_entrypoints: true
+
+nbops_traefik_file_routes:
+  - name: jellyfin
+    domain: jellyfin.example.invalid
+    scheme: http
+    port: 80
+  - name: gitea
+    domain: git.example.invalid
+    scheme: http
+    port: 80
+```
+
+When the play runs against the edge VM, Traefik renders
+`dynamic/http-services.yml` from `nbops_traefik_file_routes` declared across the
+inventory group. Each route targets `ansible_host` for that inventory host by
+default. Set `target_host` for a different VM address, or set `url` to provide
+the complete upstream URL.
+
+For future mTLS between edge Traefik and internal Traefik, routes can reference a
+Traefik `serversTransport`:
+
+```yaml
+nbops_traefik_file_routes:
+  - name: jellyfin
+    domain: jellyfin.example.invalid
+    scheme: https
+    port: 443
+    servers_transport: internal-mtls
+
+traefik_dynamic_servers_transports:
+  - name: internal-mtls
+    server_name: apps-01.example.internal
+    root_cas:
+      - /etc/pki/internal/certs/ca.crt
+    certificates:
+      - cert_file: /etc/pki/internal/certs/edge.crt
+        key_file: /etc/pki/internal/private/edge.key
+```
+
 ## Routing Modes
 
 Application roles support:
 
 - `host`: publish application ports directly and open those ports in UFW.
 - `traefik`: do not publish HTTP ports; attach to Traefik and render labels.
+- `traefik_file`: publish a service port without labels. This is available for
+  exceptional direct edge-to-app routes, but the preferred multi-VM topology is
+  edge Traefik -> internal Traefik -> application.
 
 Gitea is special: HTTP can be routed through Traefik while SSH remains published
 with `gitea_publish_ssh: true`.
-

docs/upstream-sources.yml

@@ -0,0 +1,553 @@
+---
+version: 1
+policy:
+  vendor_method: copied_snapshots
+  vendor_root: roles
+  deployed_from: role_templates
+  notes:
+    - Upstream files are reference snapshots only and are not deployed directly.
+    - "Use compose_paths: [] when upstream documents Compose in README files only."
+    - "Use compose_urls: [] for direct raw HTTP Compose YAML fallback URLs."
+    - "Use role-level local_compose_file as a repo-local fallback Compose reference."
+    - "status: verify means the source mapping must be checked before pinning."
+
+sources:
+  alloy:
+    role: alloy
+    vendor_dir: roles/alloy/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: application
+        url: https://github.com/grafana/alloy.git
+        ref: main
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: []
+
+  arr:
+    role: arr
+    vendor_dir: roles/arr/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: prowlarr-container
+        url: https://github.com/linuxserver/docker-prowlarr.git
+        ref: master
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: []
+      - purpose: sonarr-container
+        url: https://github.com/linuxserver/docker-sonarr.git
+        ref: master
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: []
+      - purpose: radarr-container
+        url: https://github.com/linuxserver/docker-radarr.git
+        ref: master
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: []
+      - purpose: lidarr-container
+        url: https://github.com/linuxserver/docker-lidarr.git
+        ref: master
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: []
+      - purpose: bazarr-container
+        url: https://github.com/linuxserver/docker-bazarr.git
+        ref: master
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: []
+
+  authentik:
+    role: authentik
+    vendor_dir: roles/authentik/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: application
+        url: https://github.com/goauthentik/authentik.git
+        ref: main
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: [https://docs.goauthentik.io/compose.yml]
+
+  authentik_ldap:
+    role: authentik_ldap
+    vendor_dir: roles/authentik_ldap/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: application
+        url: https://github.com/goauthentik/authentik.git
+        ref: main
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: [https://docs.goauthentik.io/add-secure-apps/outposts/manual-deploy-docker-compose/]
+
+  authentik_proxy:
+    role: authentik_proxy
+    vendor_dir: roles/authentik_proxy/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: application
+        url: https://github.com/goauthentik/authentik.git
+        ref: main
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: [https://docs.goauthentik.io/add-secure-apps/outposts/manual-deploy-docker-compose/]
+
+  authentik_rac:
+    role: authentik_rac
+    vendor_dir: roles/authentik_rac/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: application
+        url: https://github.com/goauthentik/authentik.git
+        ref: main
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: [https://docs.goauthentik.io/add-secure-apps/outposts/manual-deploy-docker-compose/]
+
+  cleanuparr:
+    role: cleanuparr
+    vendor_dir: roles/cleanuparr/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: application
+        url: https://github.com/cleanuparr/cleanuparr.git
+        ref: main
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: []
+
+  code_server:
+    role: code_server
+    vendor_dir: roles/code_server/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: container
+        url: https://github.com/linuxserver/docker-code-server.git
+        ref: master
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: []
+
+  filebrowser_quantum:
+    role: filebrowser_quantum
+    status: verify
+    vendor_dir: roles/filebrowser_quantum/upstream
+    local_compose_file: ""
+    notes:
+      - Verify upstream repository for the gtstef/filebrowser image before pinning.
+    repositories:
+      - purpose: container
+        url: https://github.com/gtsteffaniak/filebrowser.git
+        ref: main
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: [https://filebrowserquantum.com/en/docs/user-guides/other/standalone/]
+
+  fiveetools:
+    role: fiveetools
+    status: verify
+    vendor_dir: roles/fiveetools/upstream
+    local_compose_file: ""
+    notes:
+      - Verify upstream repository for the jafner/5etools image before pinning.
+    repositories:
+      - purpose: container
+        url: https://github.com/Jafner/5etools-docker.git
+        ref: main
+        readme_paths: [README.md]
+        compose_paths: [docker-compose.yml]
+        compose_urls: []
+
+  flaresolverr:
+    role: flaresolverr
+    vendor_dir: roles/flaresolverr/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: application
+        url: https://github.com/FlareSolverr/FlareSolverr.git
+        ref: master
+        readme_paths: [README.md]
+        compose_paths: [docker-compose.yml]
+        compose_urls: []
+
+  gitea:
+    role: gitea
+    vendor_dir: roles/gitea/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: application
+        url: https://github.com/go-gitea/gitea.git
+        ref: main
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: [https://docs.gitea.com/installation/install-with-docker-rootless]
+
+  gitea_act_runner:
+    role: gitea_act_runner
+    vendor_dir: roles/gitea_act_runner/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: application
+        url: https://gitea.com/gitea/act_runner.git
+        ref: main
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: [https://docs.gitea.com/usage/actions/act-runner#start-the-runner-using-docker-compose]
+
+  grafana:
+    role: grafana
+    vendor_dir: roles/grafana/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: application
+        url: https://github.com/grafana/grafana.git
+        ref: main
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: [] # Host own, all examples are bad
+
+  grafana_renderer:
+    role: grafana_renderer
+    vendor_dir: roles/grafana_renderer/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: application
+        url: https://github.com/grafana/grafana-image-renderer.git
+        ref: master
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: []
+
+  homarr:
+    role: homarr
+    vendor_dir: roles/homarr/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: application
+        url: https://github.com/homarr-labs/homarr.git
+        ref: dev
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: []
+
+  immich:
+    role: immich
+    vendor_dir: roles/immich/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: application
+        url: https://github.com/immich-app/immich.git
+        ref: main
+        readme_paths: [README.md]
+        compose_paths: [docker/docker-compose.yml]
+        compose_urls: []
+
+  ipv6nat:
+    role: ipv6nat
+    vendor_dir: roles/ipv6nat/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: container
+        url: https://github.com/robbertkl/docker-ipv6nat.git
+        ref: master
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: []
+
+  jellyfin:
+    role: jellyfin
+    vendor_dir: roles/jellyfin/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: container
+        url: https://github.com/linuxserver/docker-jellyfin.git
+        ref: master
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: []
+      - purpose: application
+        url: https://github.com/jellyfin/jellyfin.git
+        ref: master
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: []
+
+  jellyseerr:
+    role: jellyseerr
+    vendor_dir: roles/jellyseerr/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: application
+        url: https://github.com/Fallenbagel/jellyseerr.git
+        ref: develop
+        readme_paths: [README.md]
+        compose_paths: [docker-compose.yml]
+        compose_urls: []
+
+  kavita:
+    role: kavita
+    vendor_dir: roles/kavita/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: container
+        url: https://github.com/linuxserver/docker-kavita.git
+        ref: master
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: []
+
+  kiwix_serve:
+    role: kiwix_serve
+    vendor_dir: roles/kiwix_serve/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: application
+        url: https://github.com/kiwix/kiwix-tools.git
+        ref: main
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: []
+
+  loki:
+    role: loki
+    vendor_dir: roles/loki/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: application
+        url: https://github.com/grafana/loki.git
+        ref: main
+        readme_paths: [README.md]
+        compose_paths: [production/docker-compose.yaml]
+        compose_urls: []
+
+  nginx_content:
+    role: nginx_content
+    vendor_dir: roles/nginx_content/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: container
+        url: https://github.com/nginx/nginx.git
+        ref: master
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: []
+
+  ntfy:
+    role: ntfy
+    vendor_dir: roles/ntfy/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: application
+        url: https://github.com/binwiederhier/ntfy.git
+        ref: main
+        readme_paths: [README.md]
+        compose_paths: [docker-compose.yml]
+        compose_urls: []
+
+  ocis:
+    role: ocis
+    vendor_dir: roles/ocis/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: application
+        url: https://github.com/owncloud/ocis.git
+        ref: master
+        readme_paths: [README.md]
+        compose_paths: [deployments/examples/ocis_full/docker-compose.yml]
+        compose_urls: []
+
+  paperless_ngx:
+    role: paperless_ngx
+    vendor_dir: roles/paperless_ngx/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: application
+        url: https://github.com/paperless-ngx/paperless-ngx.git
+        ref: main
+        readme_paths: [README.md]
+        compose_paths: [docker/compose/docker-compose.postgres.yml]
+        compose_urls: []
+
+  pelican_panel:
+    role: pelican_panel
+    vendor_dir: roles/pelican_panel/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: application
+        url: https://github.com/pelican-dev/panel.git
+        ref: main
+        readme_paths: [README.md]
+        compose_paths: [compose-full-stack.yml]
+        compose_urls: []
+
+  php_fpm:
+    role: php_fpm
+    vendor_dir: roles/php_fpm/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: container
+        url: https://github.com/docker-library/php.git
+        ref: master
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: []
+
+  pinchflat:
+    role: pinchflat
+    vendor_dir: roles/pinchflat/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: application
+        url: https://github.com/kieraneglin/pinchflat.git
+        ref: main
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: []
+
+  postgres:
+    role: postgres
+    vendor_dir: roles/postgres/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: container
+        url: https://github.com/docker-library/postgres.git
+        ref: master
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: []
+
+  prometheus:
+    role: prometheus
+    vendor_dir: roles/prometheus/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: application
+        url: https://github.com/prometheus/prometheus.git
+        ref: main
+        readme_paths: [README.md]
+        compose_paths: [documentation/examples/prometheus.yml]
+        compose_urls: []
+
+  pterodactyl:
+    role: pterodactyl
+    vendor_dir: roles/pterodactyl/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: application
+        url: https://github.com/pterodactyl/panel.git
+        ref: 1.0-develop
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: []
+
+  qbittorrent:
+    role: qbittorrent
+    vendor_dir: roles/qbittorrent/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: container
+        url: https://github.com/linuxserver/docker-qbittorrent.git
+        ref: master
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: []
+
+  requarks:
+    role: requarks
+    vendor_dir: roles/requarks/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: application
+        url: https://github.com/requarks/wiki.git
+        ref: master
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: []
+
+  syncthing:
+    role: syncthing
+    vendor_dir: roles/syncthing/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: container
+        url: https://github.com/linuxserver/docker-syncthing.git
+        ref: master
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: []
+
+  traefik:
+    role: traefik
+    vendor_dir: roles/traefik/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: application
+        url: https://github.com/traefik/traefik.git
+        ref: master
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: []
+
+  transmission:
+    role: transmission
+    vendor_dir: roles/transmission/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: container
+        url: https://github.com/linuxserver/docker-transmission.git
+        ref: master
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: []
+
+  uptime_kuma:
+    role: uptime_kuma
+    vendor_dir: roles/uptime_kuma/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: application
+        url: https://github.com/louislam/uptime-kuma.git
+        ref: master
+        readme_paths: [README.md]
+        compose_paths: [compose.yaml]
+        compose_urls: []
+
+  valkey:
+    role: valkey
+    vendor_dir: roles/valkey/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: application
+        url: https://github.com/valkey-io/valkey.git
+        ref: unstable
+        readme_paths: [README.md]
+        compose_paths: []
+        compose_urls: []
+
+  vaultwarden:
+    role: vaultwarden
+    vendor_dir: roles/vaultwarden/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: application
+        url: https://github.com/dani-garcia/vaultwarden.git
+        ref: main
+        readme_paths: [README.md]
+        compose_paths: [docker/docker-compose.yml]
+        compose_urls: []
+
+  wizarr:
+    role: wizarr
+    vendor_dir: roles/wizarr/upstream
+    local_compose_file: ""
+    repositories:
+      - purpose: application
+        url: https://github.com/Wizarrrr/wizarr.git
+        ref: main
+        readme_paths: [README.md]
+        compose_paths: [docker-compose.yml]
+        compose_urls: []

group_vars/.gitignore

@@ -0,0 +1 @@
+*.yml

group_vars/all.yml

@@ -1,71 +0,0 @@
----
-nbops_environment: production
-nbops_admin_user: admin
-nbops_admin_groups:
-  - sudo
-nbops_hostname: "{{ inventory_hostname }}"
-nbops_fqdn: "{{ inventory_hostname }}"
-nbops_timezone: Etc/UTC
-nbops_locale: en_GB.UTF-8
-nbops_ssh_port: 22
-nbops_dns_servers:
-  - 1.1.1.1
-  - 9.9.9.9
-
-nbops_standard_directories:
-  - /srv/docker
-  - /srv/config
-  - /srv/backups
-  - /srv/data
-  - /srv/media
-  - /etc/pki/internal
-  - /etc/pki/internal/private
-  - /etc/pki/internal/certs
-  - /usr/local/share/ca-certificates/internal
-
-nbops_base_packages:
-  - acl
-  - apt-transport-https
-  - bash-completion
-  - ca-certificates
-  - chrony
-  - curl
-  - git
-  - gnupg
-  - htop
-  - jq
-  - locales
-  - lsb-release
-  - needrestart
-  - qemu-guest-agent
-  - rsync
-  - sudo
-  - ufw
-  - unattended-upgrades
-  - vim
-
-nbops_sysctl:
-  net.ipv4.ip_forward: "1"
-  net.ipv6.conf.all.forwarding: "1"
-  fs.inotify.max_user_watches: "1048576"
-  fs.inotify.max_user_instances: "1024"
-
-docker_users:
-  - "{{ nbops_admin_user }}"
-
-ufw_allowed_tcp_ports:
-  - "{{ nbops_ssh_port }}"
-ufw_allowed_udp_ports: []
-
-monitoring_agent: none
-monitoring_packages: []
-
-mtls_ca_certificates: []
-mtls_host_certificates: []
-mtls_private_keys: []
-
-nbops_proxy_network: proxy
-nbops_service_routing_mode: host
-nbops_service_domain_suffix: example.invalid
-nbops_traefik_entrypoint: websecure
-nbops_traefik_tls: true

group_vars/all.yml.example

@@ -0,0 +1,73 @@
+---
+nbops_environment: production
+nbops_admin_user: admin
+nbops_admin_groups:
+  - sudo
+nbops_hostname: "{{ inventory_hostname }}"
+nbops_fqdn: "{{ inventory_hostname }}"
+nbops_timezone: Etc/UTC
+nbops_locale: en_GB.UTF-8
+nbops_ssh_port: 22
+nbops_dns_servers:
+  - 1.1.1.1
+  - 9.9.9.9
+
+nbops_standard_directories:
+  - /srv/docker
+  - /srv/config
+  - /srv/backups
+  - /srv/data
+  - /srv/media
+  - /etc/pki/internal
+  - /etc/pki/internal/private
+  - /etc/pki/internal/certs
+  - /usr/local/share/ca-certificates/internal
+
+nbops_base_packages:
+  - acl
+  - apt-transport-https
+  - bash-completion
+  - ca-certificates
+  - chrony
+  - curl
+  - git
+  - gnupg
+  - htop
+  - jq
+  - locales
+  - lsb-release
+  - needrestart
+  - qemu-guest-agent
+  - rsync
+  - sudo
+  - ufw
+  - unattended-upgrades
+  - vim
+
+nbops_sysctl:
+  net.ipv4.ip_forward: "1"
+  net.ipv6.conf.all.forwarding: "1"
+  fs.inotify.max_user_watches: "1048576"
+  fs.inotify.max_user_instances: "1024"
+
+docker_users:
+  - "{{ nbops_admin_user }}"
+
+ufw_allowed_tcp_ports:
+  - "{{ nbops_ssh_port }}"
+ufw_allowed_udp_ports: []
+
+monitoring_agent: none
+monitoring_packages: []
+
+mtls_ca_certificates: []
+mtls_host_certificates: []
+mtls_private_keys: []
+
+nbops_proxy_network: proxy
+nbops_service_routing_mode: host
+nbops_service_domain_suffix: example.invalid
+nbops_traefik_entrypoint: websecure
+nbops_traefik_tls: true
+nbops_traefik_file_bind_address: "0.0.0.0"
+nbops_traefik_file_routes: []

host_vars/.gitignore

@@ -0,0 +1 @@
+*internal.yml

host_vars/cloud.internal.yml.example

@@ -1,29 +0,0 @@
----
-nbops_hostname: cloud
-nbops_fqdn: cloud.example.internal
-nbops_roles:
-  - base
-  - ssh
-  - ufw
-  - updates
-  - docker
-  - mtls
-  - monitoring
-  - traefik
-  - ocis
-
-nbops_service_routing_mode: traefik
-nbops_traefik_entrypoint: web
-nbops_traefik_tls: false
-
-# Bind this to the VM's internal/LAN address in production.
-traefik_bind_address: "0.0.0.0"
-traefik_publish_entrypoints: true
-traefik_domain: apps-01.example.internal
-traefik_forwarded_headers_trusted_ips:
-  - 10.0.0.0/8
-  - 172.16.0.0/12
-  - 192.168.0.0/16
-
-ocis_url: https://files.example.internal
-

host_vars/edge.yml.example

@@ -1,31 +0,0 @@
----
-nbops_hostname: edge
-nbops_fqdn: edge.example.invalid
-nbops_roles:
-  - base
-  - ssh
-  - ufw
-  - updates
-  - docker
-  - mtls
-  - monitoring
-  - traefik
-  - authentik
-  - authentik_rac
-  - authentik_ldap
-  - authentik_worker
-
-nbops_service_routing_mode: traefik
-nbops_service_domain_suffix: example.invalid
-nbops_traefik_entrypoint: websecure
-nbops_traefik_tls: true
-
-traefik_bind_address: "0.0.0.0"
-traefik_publish_entrypoints: true
-traefik_domain: example.invalid
-traefik_acme_email: admin@example.invalid
-
-authentik_domain: auth.example.invalid
-authentik_http_port: 9000
-authentik_https_port: 9443
-

host_vars/generic-downstream.yml.example

@@ -19,8 +19,21 @@ nbops_service_routing_mode: traefik
 nbops_traefik_entrypoint: web
 nbops_traefik_tls: false
 
+# Edge Traefik consumes these file-provider routes and forwards to this VM's
+# internal Traefik. Internal Traefik still discovers application containers
+# through Docker labels.
+nbops_traefik_file_routes:
+  - name: gitea
+    domain: git.example.internal
+    scheme: http
+    port: 80
+  - name: immich
+    domain: photos.example.internal
+    scheme: http
+    port: 80
+
 # Bind this to the VM's internal/LAN address in production.
-traefik_bind_address: "0.0.0.0"
+traefik_bind_address: "10.0.10.25"
 traefik_publish_entrypoints: true
 traefik_domain: apps-01.example.internal
 traefik_forwarded_headers_trusted_ips:
@@ -54,4 +67,3 @@ arr_services:
     image: lscr.io/linuxserver/bazarr:latest
     port: 6767
     domain: bazarr.example.internal
-

host_vars/pelican-server.yml.example

@@ -1,15 +0,0 @@
----
-nbops_hostname: pelican-node-01
-nbops_fqdn: pelican-node-01.example.internal
-nbops_roles:
-  - base
-  - ssh
-  - ufw
-  - updates
-  - docker
-  - pelican_server
-
-pelican_server_daemon_port: 8080
-pelican_server_sftp_port: 2022
-pelican_server_allocation_ports:
-  - { port: "25565:25575", proto: tcp }

host_vars/wings.internal.example

@@ -1,29 +0,0 @@
----
-nbops_hostname: cloud
-nbops_fqdn: cloud.example.internal
-nbops_roles:
-  - base
-  - ssh
-  - ufw
-  - updates
-  - docker
-  - mtls
-  - monitoring
-  - traefik
-  - ocis
-
-nbops_service_routing_mode: traefik
-nbops_traefik_entrypoint: web
-nbops_traefik_tls: false
-
-# Bind this to the VM's internal/LAN address in production.
-traefik_bind_address: "0.0.0.0"
-traefik_publish_entrypoints: true
-traefik_domain: apps-01.example.internal
-traefik_forwarded_headers_trusted_ips:
-  - 10.0.0.0/8
-  - 172.16.0.0/12
-  - 192.168.0.0/16
-
-ocis_url: https://files.example.internal
-

roles/alloy/tasks/main.yml

@@ -5,6 +5,7 @@
   vars:
     docker_app_env_template_src: "{{ playbook_dir }}/../roles/alloy/templates/env.j2"
     docker_app_compose_template_src: "{{ playbook_dir }}/../roles/alloy/templates/compose.yaml.j2"
+    docker_app_compose_override_template_src: "{{ playbook_dir }}/../roles/alloy/templates/compose.override.yaml.j2"
     docker_app_name: "{{ alloy_name }}"
     docker_app_dir: "{{ alloy_dir }}"
     docker_app_image: "{{ alloy_image }}"

roles/alloy/templates/compose.override.yaml.j2

@@ -0,0 +1,3 @@
+services:
+  {{ docker_app_name }}: {}
+

roles/alloy/templates/compose.yaml.j2

@@ -17,10 +17,10 @@ services:
 {% if docker_app_env | length > 0 %}
     env_file: .env
 {% endif %}
-{% if docker_app_routing_mode == "host" and docker_app_ports | length > 0 %}
+{% if docker_app_routing_mode in ["host", "traefik_file"] and docker_app_ports | length > 0 %}
     ports:
 {% for port in docker_app_ports %}
-      - "{{ port.bind | default('0.0.0.0') }}:{{ port.host | default(port.container) }}:{{ port.container }}{% if port.protocol | default('tcp') != 'tcp' %}/{{ port.protocol }}{% endif %}"
+      - "{{ port.bind | default((docker_app_traefik_file_bind_address if docker_app_routing_mode == 'traefik_file' else '0.0.0.0')) }}:{{ port.host | default(port.container) }}:{{ port.container }}{% if port.protocol | default('tcp') != 'tcp' %}/{{ port.protocol }}{% endif %}"
 {% endfor %}
 {% endif %}
 {% if docker_app_routing_mode == "traefik" and docker_app_service_port %}

roles/alloy/upstream/SOURCE.md

@@ -0,0 +1,7 @@
+# Upstream Snapshot
+
+This directory stores copied upstream reference files for the `alloy` role.
+
+See `docs/upstream-sources.yml` for repository URLs, refs, README paths, Compose paths, and verification status.
+
+Snapshot files are reference material only. Deployments are generated from this role's `templates/` directory.

roles/alloy/upstream/docker-compose.yml

@@ -0,0 +1,23 @@
+services:
+  grafana-alloy:
+    image: grafana/alloy:latest
+    container_name: grafana-alloy
+    ports:
+      - '12345:12345'
+    volumes:
+      # mount config file
+      - './grafana/alloy/config.alloy:/etc/alloy/config.alloy'
+      # give access to running docker containers for discovery.docker
+      - /var/run/docker.sock:/var/run/docker.sock
+      # give access to docker's log files directory (optional)
+      - /var/lib/docker/containers:/var/lib/docker/containers:ro
+    environment:
+      # pass environment variables for config.alloy
+      GRAFANA_LOKI_URL: ${GRAFANA_LOKI_URL}
+      GRAFANA_LOKI_USERNAME: ${GRAFANA_LOKI_USERNAME}
+#      GRAFANA_CLOUD_API_KEY: ${GRAFANA_CLOUD_API_KEY}
+    command:
+      - run
+      - --server.http.listen-addr=0.0.0.0:12345
+      - --storage.path=/var/lib/alloy/data
+      - /etc/alloy/config.alloy

roles/arr/handlers/.gitkeep

@@ -0,0 +1 @@
+

roles/arr/handlers/main.yml

@@ -1,6 +0,0 @@
----
-- name: restart arr
-  community.docker.docker_compose_v2:
-    project_src: "{{ arr_dir }}"
-    state: restarted
-

roles/arr/tasks/main.yml

@@ -23,43 +23,22 @@
   loop: "{{ arr_services | dict2items }}"
   tags: [arr, config]
 
-- name: Render Arr environment
+- name: Deploy Arr Compose project
-  ansible.builtin.template:
+  ansible.builtin.include_role:
-    src: env.j2
+    name: compose_project
-    dest: "{{ arr_dir }}/.env"
+  vars:
-    owner: root
+    compose_project_dir: "{{ arr_dir }}"
-    group: root
+    compose_project_directories:
-    mode: "0644"
+      - "{{ arr_dir }}"
-  tags: [arr, config]
+      - "{{ arr_config_root }}"
-
+      - "{{ arr_media_root }}"
-- name: Ensure Arr proxy network exists
+      - "{{ arr_downloads_root }}"
-  community.docker.docker_network:
+    compose_project_env_template_src: "{{ playbook_dir }}/../roles/arr/templates/env.j2"
-    name: "{{ arr_traefik_network }}"
+    compose_project_env_mode: "0644"
-    state: present
+    compose_project_compose_template_src: "{{ playbook_dir }}/../roles/arr/templates/compose.yaml.j2"
-  when: arr_routing_mode == "traefik"
+    compose_project_override_template_src: "{{ playbook_dir }}/../roles/arr/templates/compose.override.yaml.j2"
-  tags: [arr, docker]
+    compose_project_create_proxy_network: "{{ arr_routing_mode == 'traefik' }}"
-
+    compose_project_proxy_network: "{{ arr_traefik_network }}"
-- name: Render Arr Compose file
+    compose_project_firewall_ports: "{{ arr_tcp_ports }}"
-  ansible.builtin.template:
+    compose_project_firewall_enabled: "{{ arr_routing_mode in ['host', 'traefik_file'] }}"
-    src: compose.yaml.j2
+  tags: [arr]
-    dest: "{{ arr_dir }}/compose.yaml"
-    owner: root
-    group: root
-    mode: "0644"
-  notify: restart arr
-  tags: [arr, compose]
-
-- name: Allow Arr ports
-  community.general.ufw:
-    rule: allow
-    port: "{{ item }}"
-    proto: tcp
-  loop: "{{ arr_tcp_ports }}"
-  when: arr_routing_mode == "host"
-  tags: [arr, firewall]
-
-- name: Start Arr stack
-  community.docker.docker_compose_v2:
-    project_src: "{{ arr_dir }}"
-    state: present
-  tags: [arr, compose]

roles/arr/templates/compose.override.yaml.j2

@@ -0,0 +1,5 @@
+services:
+{% for name, service in arr_services.items() %}
+  {{ name }}: {}
+{% endfor %}
+

roles/arr/templates/compose.yaml.j2

@@ -4,9 +4,9 @@ services:
     image: {{ service.image }}
     restart: unless-stopped
     env_file: .env
-{% if arr_routing_mode == "host" %}
+{% if arr_routing_mode in ["host", "traefik_file"] %}
     ports:
-      - "{{ service.port }}:{{ service.port }}"
+      - "{{ nbops_traefik_file_bind_address if arr_routing_mode == 'traefik_file' else '0.0.0.0' }}:{{ service.port }}:{{ service.port }}"
 {% endif %}
 {% if arr_routing_mode == "traefik" %}
     # internal service port: {{ service.port }}; not published on the Docker host

roles/arr/upstream/SOURCE.md

@@ -0,0 +1,7 @@
+# Upstream Snapshot
+
+This directory stores copied upstream reference files for the `arr` role.
+
+See `docs/upstream-sources.yml` for repository URLs, refs, README paths, Compose paths, and verification status.
+
+Snapshot files are reference material only. Deployments are generated from this role's `templates/` directory.

roles/authentik/handlers/.gitkeep

@@ -0,0 +1 @@
+

roles/authentik/handlers/main.yml

@@ -1,6 +0,0 @@
----
-- name: restart authentik
-  community.docker.docker_compose_v2:
-    project_src: "{{ authentik_dir }}"
-    state: restarted
-

roles/authentik/tasks/main.yml

@@ -8,44 +8,18 @@
     mode: "0755"
   tags: [authentik]
 
-- name: Render authentik environment
+- name: Deploy authentik Compose project
-  ansible.builtin.template:
+  ansible.builtin.include_role:
-    src: env.j2
+    name: compose_project
-    dest: "{{ authentik_dir }}/.env"
+  vars:
-    owner: root
+    compose_project_dir: "{{ authentik_dir }}"
-    group: root
+    compose_project_directories:
-    mode: "0600"
+      - "{{ authentik_dir }}"
-  no_log: true
+    compose_project_env_template_src: "{{ playbook_dir }}/../roles/authentik/templates/env.j2"
-  tags: [authentik, config]
+    compose_project_compose_template_src: "{{ playbook_dir }}/../roles/authentik/templates/compose.yaml.j2"
-
+    compose_project_override_template_src: "{{ playbook_dir }}/../roles/authentik/templates/compose.override.yaml.j2"
-- name: Ensure authentik proxy network exists
+    compose_project_create_proxy_network: "{{ authentik_routing_mode == 'traefik' }}"
-  community.docker.docker_network:
+    compose_project_proxy_network: "{{ authentik_traefik_network }}"
-    name: "{{ authentik_traefik_network }}"
+    compose_project_firewall_ports: "{{ authentik_tcp_ports }}"
-    state: present
+    compose_project_firewall_enabled: "{{ authentik_routing_mode in ['host', 'traefik_file'] }}"
-  when: authentik_routing_mode == "traefik"
+  tags: [authentik]
-  tags: [authentik, docker]
-
-- name: Render authentik Compose file
-  ansible.builtin.template:
-    src: compose.yaml.j2
-    dest: "{{ authentik_dir }}/compose.yaml"
-    owner: root
-    group: root
-    mode: "0644"
-  notify: restart authentik
-  tags: [authentik, compose]
-
-- name: Allow authentik ports
-  community.general.ufw:
-    rule: allow
-    port: "{{ item }}"
-    proto: tcp
-  loop: "{{ authentik_tcp_ports }}"
-  when: authentik_routing_mode == "host"
-  tags: [authentik, firewall]
-
-- name: Start authentik
-  community.docker.docker_compose_v2:
-    project_src: "{{ authentik_dir }}"
-    state: present
-  tags: [authentik, compose]

roles/authentik/templates/compose.override.yaml.j2

@@ -0,0 +1,6 @@
+services:
+  postgresql: {}
+  redis: {}
+  server: {}
+  worker: {}
+

roles/authentik/templates/compose.yaml.j2

@@ -16,10 +16,10 @@ services:
     restart: unless-stopped
     command: server
     env_file: .env
-{% if authentik_routing_mode == "host" %}
+{% if authentik_routing_mode in ["host", "traefik_file"] %}
     ports:
-      - "{{ authentik_http_port }}:9000"
+      - "{{ nbops_traefik_file_bind_address if authentik_routing_mode == 'traefik_file' else '0.0.0.0' }}:{{ authentik_http_port }}:9000"
-      - "{{ authentik_https_port }}:9443"
+      - "{{ nbops_traefik_file_bind_address if authentik_routing_mode == 'traefik_file' else '0.0.0.0' }}:{{ authentik_https_port }}:9443"
 {% endif %}
 {% if authentik_routing_mode == "traefik" %}
     # internal HTTP service port: 9000; not published on the Docker host

roles/authentik/upstream/SOURCE.md

@@ -0,0 +1,7 @@
+# Upstream Snapshot
+
+This directory stores copied upstream reference files for the `authentik` role.
+
+See `docs/upstream-sources.yml` for repository URLs, refs, README paths, Compose paths, and verification status.
+
+Snapshot files are reference material only. Deployments are generated from this role's `templates/` directory.

roles/authentik_ldap/tasks/main.yml

@@ -5,6 +5,7 @@
   vars:
     docker_app_env_template_src: "{{ playbook_dir }}/../roles/authentik_ldap/templates/env.j2"
     docker_app_compose_template_src: "{{ playbook_dir }}/../roles/authentik_ldap/templates/compose.yaml.j2"
+    docker_app_compose_override_template_src: "{{ playbook_dir }}/../roles/authentik_ldap/templates/compose.override.yaml.j2"
     docker_app_name: "{{ authentik_ldap_name }}"
     docker_app_dir: "{{ authentik_ldap_dir }}"
     docker_app_image: "{{ authentik_ldap_image }}"

roles/authentik_ldap/templates/compose.override.yaml.j2

@@ -0,0 +1,3 @@
+services:
+  {{ docker_app_name }}: {}
+

roles/authentik_ldap/templates/compose.yaml.j2

@@ -17,10 +17,10 @@ services:
 {% if docker_app_env | length > 0 %}
     env_file: .env
 {% endif %}
-{% if docker_app_routing_mode == "host" and docker_app_ports | length > 0 %}
+{% if docker_app_routing_mode in ["host", "traefik_file"] and docker_app_ports | length > 0 %}
     ports:
 {% for port in docker_app_ports %}
-      - "{{ port.bind | default('0.0.0.0') }}:{{ port.host | default(port.container) }}:{{ port.container }}{% if port.protocol | default('tcp') != 'tcp' %}/{{ port.protocol }}{% endif %}"
+      - "{{ port.bind | default((docker_app_traefik_file_bind_address if docker_app_routing_mode == 'traefik_file' else '0.0.0.0')) }}:{{ port.host | default(port.container) }}:{{ port.container }}{% if port.protocol | default('tcp') != 'tcp' %}/{{ port.protocol }}{% endif %}"
 {% endfor %}
 {% endif %}
 {% if docker_app_routing_mode == "traefik" and docker_app_service_port %}

roles/authentik_ldap/upstream/SOURCE.md

@@ -0,0 +1,7 @@
+# Upstream Snapshot
+
+This directory stores copied upstream reference files for the `authentik_ldap` role.
+
+See `docs/upstream-sources.yml` for repository URLs, refs, README paths, Compose paths, and verification status.
+
+Snapshot files are reference material only. Deployments are generated from this role's `templates/` directory.

roles/authentik_proxy/tasks/main.yml

@@ -5,6 +5,7 @@
   vars:
     docker_app_env_template_src: "{{ playbook_dir }}/../roles/authentik_proxy/templates/env.j2"
     docker_app_compose_template_src: "{{ playbook_dir }}/../roles/authentik_proxy/templates/compose.yaml.j2"
+    docker_app_compose_override_template_src: "{{ playbook_dir }}/../roles/authentik_proxy/templates/compose.override.yaml.j2"
     docker_app_name: "{{ authentik_proxy_name }}"
     docker_app_dir: "{{ authentik_proxy_dir }}"
     docker_app_image: "{{ authentik_proxy_image }}"

roles/authentik_proxy/templates/compose.override.yaml.j2

@@ -0,0 +1,3 @@
+services:
+  {{ docker_app_name }}: {}
+

roles/authentik_proxy/templates/compose.yaml.j2

@@ -17,10 +17,10 @@ services:
 {% if docker_app_env | length > 0 %}
     env_file: .env
 {% endif %}
-{% if docker_app_routing_mode == "host" and docker_app_ports | length > 0 %}
+{% if docker_app_routing_mode in ["host", "traefik_file"] and docker_app_ports | length > 0 %}
     ports:
 {% for port in docker_app_ports %}
-      - "{{ port.bind | default('0.0.0.0') }}:{{ port.host | default(port.container) }}:{{ port.container }}{% if port.protocol | default('tcp') != 'tcp' %}/{{ port.protocol }}{% endif %}"
+      - "{{ port.bind | default((docker_app_traefik_file_bind_address if docker_app_routing_mode == 'traefik_file' else '0.0.0.0')) }}:{{ port.host | default(port.container) }}:{{ port.container }}{% if port.protocol | default('tcp') != 'tcp' %}/{{ port.protocol }}{% endif %}"
 {% endfor %}
 {% endif %}
 {% if docker_app_routing_mode == "traefik" and docker_app_service_port %}

roles/authentik_proxy/upstream/SOURCE.md

@@ -0,0 +1,7 @@
+# Upstream Snapshot
+
+This directory stores copied upstream reference files for the `authentik_proxy` role.
+
+See `docs/upstream-sources.yml` for repository URLs, refs, README paths, Compose paths, and verification status.
+
+Snapshot files are reference material only. Deployments are generated from this role's `templates/` directory.

roles/authentik_rac/tasks/main.yml

@@ -5,6 +5,7 @@
   vars:
     docker_app_env_template_src: "{{ playbook_dir }}/../roles/authentik_rac/templates/env.j2"
     docker_app_compose_template_src: "{{ playbook_dir }}/../roles/authentik_rac/templates/compose.yaml.j2"
+    docker_app_compose_override_template_src: "{{ playbook_dir }}/../roles/authentik_rac/templates/compose.override.yaml.j2"
     docker_app_name: "{{ authentik_rac_name }}"
     docker_app_dir: "{{ authentik_rac_dir }}"
     docker_app_image: "{{ authentik_rac_image }}"

roles/authentik_rac/templates/compose.override.yaml.j2

@@ -0,0 +1,3 @@
+services:
+  {{ docker_app_name }}: {}
+

roles/authentik_rac/templates/compose.yaml.j2

@@ -17,10 +17,10 @@ services:
 {% if docker_app_env | length > 0 %}
     env_file: .env
 {% endif %}
-{% if docker_app_routing_mode == "host" and docker_app_ports | length > 0 %}
+{% if docker_app_routing_mode in ["host", "traefik_file"] and docker_app_ports | length > 0 %}
     ports:
 {% for port in docker_app_ports %}
-      - "{{ port.bind | default('0.0.0.0') }}:{{ port.host | default(port.container) }}:{{ port.container }}{% if port.protocol | default('tcp') != 'tcp' %}/{{ port.protocol }}{% endif %}"
+      - "{{ port.bind | default((docker_app_traefik_file_bind_address if docker_app_routing_mode == 'traefik_file' else '0.0.0.0')) }}:{{ port.host | default(port.container) }}:{{ port.container }}{% if port.protocol | default('tcp') != 'tcp' %}/{{ port.protocol }}{% endif %}"
 {% endfor %}
 {% endif %}
 {% if docker_app_routing_mode == "traefik" and docker_app_service_port %}

roles/authentik_rac/upstream/SOURCE.md

@@ -0,0 +1,7 @@
+# Upstream Snapshot
+
+This directory stores copied upstream reference files for the `authentik_rac` role.
+
+See `docs/upstream-sources.yml` for repository URLs, refs, README paths, Compose paths, and verification status.
+
+Snapshot files are reference material only. Deployments are generated from this role's `templates/` directory.

roles/cleanuparr/tasks/main.yml

@@ -5,6 +5,7 @@
   vars:
     docker_app_env_template_src: "{{ playbook_dir }}/../roles/cleanuparr/templates/env.j2"
     docker_app_compose_template_src: "{{ playbook_dir }}/../roles/cleanuparr/templates/compose.yaml.j2"
+    docker_app_compose_override_template_src: "{{ playbook_dir }}/../roles/cleanuparr/templates/compose.override.yaml.j2"
     docker_app_name: "{{ cleanuparr_name }}"
     docker_app_dir: "{{ cleanuparr_dir }}"
     docker_app_image: "{{ cleanuparr_image }}"

roles/cleanuparr/templates/compose.override.yaml.j2

@@ -0,0 +1,3 @@
+services:
+  {{ docker_app_name }}: {}
+

roles/cleanuparr/templates/compose.yaml.j2

@@ -17,10 +17,10 @@ services:
 {% if docker_app_env | length > 0 %}
     env_file: .env
 {% endif %}
-{% if docker_app_routing_mode == "host" and docker_app_ports | length > 0 %}
+{% if docker_app_routing_mode in ["host", "traefik_file"] and docker_app_ports | length > 0 %}
     ports:
 {% for port in docker_app_ports %}
-      - "{{ port.bind | default('0.0.0.0') }}:{{ port.host | default(port.container) }}:{{ port.container }}{% if port.protocol | default('tcp') != 'tcp' %}/{{ port.protocol }}{% endif %}"
+      - "{{ port.bind | default((docker_app_traefik_file_bind_address if docker_app_routing_mode == 'traefik_file' else '0.0.0.0')) }}:{{ port.host | default(port.container) }}:{{ port.container }}{% if port.protocol | default('tcp') != 'tcp' %}/{{ port.protocol }}{% endif %}"
 {% endfor %}
 {% endif %}
 {% if docker_app_routing_mode == "traefik" and docker_app_service_port %}

roles/cleanuparr/upstream/SOURCE.md

@@ -0,0 +1,7 @@
+# Upstream Snapshot
+
+This directory stores copied upstream reference files for the `cleanuparr` role.
+
+See `docs/upstream-sources.yml` for repository URLs, refs, README paths, Compose paths, and verification status.
+
+Snapshot files are reference material only. Deployments are generated from this role's `templates/` directory.

roles/code_server/tasks/main.yml

@@ -5,6 +5,7 @@
   vars:
     docker_app_env_template_src: "{{ playbook_dir }}/../roles/code_server/templates/env.j2"
     docker_app_compose_template_src: "{{ playbook_dir }}/../roles/code_server/templates/compose.yaml.j2"
+    docker_app_compose_override_template_src: "{{ playbook_dir }}/../roles/code_server/templates/compose.override.yaml.j2"
     docker_app_name: "{{ code_server_name }}"
     docker_app_dir: "{{ code_server_dir }}"
     docker_app_image: "{{ code_server_image }}"

roles/code_server/templates/compose.override.yaml.j2

@@ -0,0 +1,3 @@
+services:
+  {{ docker_app_name }}: {}
+

roles/code_server/templates/compose.yaml.j2

@@ -17,10 +17,10 @@ services:
 {% if docker_app_env | length > 0 %}
     env_file: .env
 {% endif %}
-{% if docker_app_routing_mode == "host" and docker_app_ports | length > 0 %}
+{% if docker_app_routing_mode in ["host", "traefik_file"] and docker_app_ports | length > 0 %}
     ports:
 {% for port in docker_app_ports %}
-      - "{{ port.bind | default('0.0.0.0') }}:{{ port.host | default(port.container) }}:{{ port.container }}{% if port.protocol | default('tcp') != 'tcp' %}/{{ port.protocol }}{% endif %}"
+      - "{{ port.bind | default((docker_app_traefik_file_bind_address if docker_app_routing_mode == 'traefik_file' else '0.0.0.0')) }}:{{ port.host | default(port.container) }}:{{ port.container }}{% if port.protocol | default('tcp') != 'tcp' %}/{{ port.protocol }}{% endif %}"
 {% endfor %}
 {% endif %}
 {% if docker_app_routing_mode == "traefik" and docker_app_service_port %}

roles/code_server/upstream/SOURCE.md

@@ -0,0 +1,7 @@
+# Upstream Snapshot
+
+This directory stores copied upstream reference files for the `code_server` role.
+
+See `docs/upstream-sources.yml` for repository URLs, refs, README paths, Compose paths, and verification status.
+
+Snapshot files are reference material only. Deployments are generated from this role's `templates/` directory.

roles/compose_project/README.md

@@ -0,0 +1,11 @@
+# compose_project
+
+Normalizes Docker Compose project deployment for all Compose-backed roles.
+
+This role renders `.env`, `compose.yaml`, and optional `compose.override.yaml`,
+creates required directories and proxy networks, opens declared UFW ports, and
+starts the Compose project.
+
+Application roles should provide their own templates and call this role instead
+of duplicating Compose lifecycle tasks.
+

roles/compose_project/defaults/main.yml

@@ -0,0 +1,20 @@
+---
+compose_project_dir: ""
+compose_project_directories:
+  - "{{ compose_project_dir }}"
+compose_project_env_template_src: ""
+compose_project_compose_template_src: ""
+compose_project_override_template_src: ""
+compose_project_env_dest: "{{ compose_project_dir }}/.env"
+compose_project_compose_dest: "{{ compose_project_dir }}/compose.yaml"
+compose_project_override_dest: "{{ compose_project_dir }}/compose.override.yaml"
+compose_project_env_mode: "0600"
+compose_project_compose_mode: "0644"
+compose_project_override_mode: "0644"
+compose_project_proxy_network: ""
+compose_project_create_proxy_network: false
+compose_project_firewall_ports: []
+compose_project_firewall_enabled: false
+compose_project_state: present
+compose_project_pull: missing
+

roles/compose_project/files/.gitkeep

@@ -0,0 +1 @@
+

roles/compose_project/handlers/main.yml

@@ -0,0 +1,6 @@
+---
+- name: restart compose project
+  community.docker.docker_compose_v2:
+    project_src: "{{ compose_project_dir }}"
+    state: restarted
+

roles/compose_project/tasks/main.yml

@@ -0,0 +1,75 @@
+---
+- name: Validate Compose project directory is configured
+  ansible.builtin.assert:
+    that:
+      - compose_project_dir | length > 0
+      - compose_project_compose_template_src | length > 0
+    fail_msg: "compose_project_dir and compose_project_compose_template_src are required."
+  tags: [compose_project]
+
+- name: Create Compose project directories
+  ansible.builtin.file:
+    path: "{{ item }}"
+    state: directory
+    owner: root
+    group: root
+    mode: "0755"
+  loop: "{{ compose_project_directories }}"
+  tags: [compose_project, directories]
+
+- name: Ensure Compose project proxy network exists
+  community.docker.docker_network:
+    name: "{{ compose_project_proxy_network }}"
+    state: present
+  when:
+    - compose_project_create_proxy_network | bool
+    - compose_project_proxy_network | length > 0
+  tags: [compose_project, docker]
+
+- name: Render Compose project environment file
+  ansible.builtin.template:
+    src: "{{ compose_project_env_template_src }}"
+    dest: "{{ compose_project_env_dest }}"
+    owner: root
+    group: root
+    mode: "{{ compose_project_env_mode }}"
+  when: compose_project_env_template_src | length > 0
+  no_log: true
+  tags: [compose_project, config]
+
+- name: Render Compose project file
+  ansible.builtin.template:
+    src: "{{ compose_project_compose_template_src }}"
+    dest: "{{ compose_project_compose_dest }}"
+    owner: root
+    group: root
+    mode: "{{ compose_project_compose_mode }}"
+  notify: restart compose project
+  tags: [compose_project, compose]
+
+- name: Render Compose project override file
+  ansible.builtin.template:
+    src: "{{ compose_project_override_template_src }}"
+    dest: "{{ compose_project_override_dest }}"
+    owner: root
+    group: root
+    mode: "{{ compose_project_override_mode }}"
+  when: compose_project_override_template_src | length > 0
+  notify: restart compose project
+  tags: [compose_project, compose]
+
+- name: Allow Compose project firewall ports
+  community.general.ufw:
+    rule: allow
+    port: "{{ item.port | default(item.host | default(item.container | default(item))) }}"
+    proto: "{{ item.proto | default(item.protocol | default('tcp')) }}"
+  loop: "{{ compose_project_firewall_ports }}"
+  when: compose_project_firewall_enabled | bool
+  tags: [compose_project, firewall]
+
+- name: Start Compose project
+  community.docker.docker_compose_v2:
+    project_src: "{{ compose_project_dir }}"
+    state: "{{ compose_project_state }}"
+    pull: "{{ compose_project_pull }}"
+  tags: [compose_project, compose]

roles/compose_project/templates/.gitkeep

@@ -0,0 +1 @@
+

roles/docker_app/README.md

@@ -1,10 +1,12 @@
 # docker_app
 
-Shared implementation role for single-container Docker Compose applications.
+Shared adapter role for single-container Docker Compose applications.
 Application roles set `docker_app_*` variables and include this role.
 
+`docker_app` validates single-container app inputs and delegates the common
+Compose lifecycle to `compose_project`.
+
 It supports direct host-port publishing with UFW rules or Traefik routing via
 labels and a shared Docker network.
 
 Tags: `docker_app`, `docker`, `config`, `compose`, `firewall`.
-

roles/docker_app/defaults/main.yml

@@ -26,7 +26,9 @@ docker_app_traefik_entrypoint: "{{ nbops_traefik_entrypoint }}"
 docker_app_traefik_tls: "{{ nbops_traefik_tls }}"
 docker_app_traefik_middlewares: []
 docker_app_traefik_rule: "Host(`{{ docker_app_domain }}`)"
+docker_app_traefik_file_bind_address: "{{ nbops_traefik_file_bind_address }}"
 docker_app_labels: {}
 docker_app_ufw_ports: "{{ docker_app_ports }}"
 docker_app_env_template_src: env.j2
 docker_app_compose_template_src: compose.yaml.j2
+docker_app_compose_override_template_src: ""

roles/docker_app/handlers/.gitkeep

@@ -0,0 +1 @@
+

roles/docker_app/handlers/main.yml

@@ -1,6 +0,0 @@
----
-- name: restart docker app
-  community.docker.docker_compose_v2:
-    project_src: "{{ docker_app_dir }}"
-    state: restarted
-

roles/docker_app/tasks/main.yml

@@ -5,58 +5,18 @@
       - docker_app_image | length > 0
     fail_msg: "docker_app_image must be configured for {{ docker_app_name }}."
   tags: [docker_app]
-
+- name: Deploy Docker app Compose project
-- name: Create Docker app directories
+  ansible.builtin.include_role:
-  ansible.builtin.file:
+    name: compose_project
-    path: "{{ item }}"
+  vars:
-    state: directory
+    compose_project_dir: "{{ docker_app_dir }}"
-    owner: root
+    compose_project_directories: "{{ docker_app_directories }}"
-    group: root
+    compose_project_env_template_src: "{{ docker_app_env_template_src }}"
-    mode: "0755"
+    compose_project_compose_template_src: "{{ docker_app_compose_template_src }}"
-  loop: "{{ docker_app_directories }}"
+    compose_project_override_template_src: "{{ docker_app_compose_override_template_src }}"
+    compose_project_create_proxy_network: "{{ docker_app_routing_mode == 'traefik' and docker_app_network_mode | length == 0 }}"
+    compose_project_proxy_network: "{{ docker_app_traefik_network }}"
+    compose_project_firewall_ports: "{{ docker_app_ufw_ports }}"
+    compose_project_firewall_enabled: "{{ docker_app_routing_mode in ['host', 'traefik_file'] }}"
+    compose_project_pull: "{{ docker_app_pull }}"
   tags: [docker_app]
-
-- name: Ensure proxy network exists
-  community.docker.docker_network:
-    name: "{{ docker_app_traefik_network }}"
-    state: present
-  when:
-    - docker_app_routing_mode == "traefik"
-    - docker_app_network_mode | length == 0
-  tags: [docker_app, docker]
-
-- name: Render Docker app environment
-  ansible.builtin.template:
-    src: "{{ docker_app_env_template_src }}"
-    dest: "{{ docker_app_dir }}/.env"
-    owner: root
-    group: root
-    mode: "0600"
-  no_log: true
-  tags: [docker_app, config]
-
-- name: Render Docker app Compose file
-  ansible.builtin.template:
-    src: "{{ docker_app_compose_template_src }}"
-    dest: "{{ docker_app_dir }}/compose.yaml"
-    owner: root
-    group: root
-    mode: "0644"
-  notify: restart docker app
-  tags: [docker_app, compose]
-
-- name: Allow Docker app host ports
-  community.general.ufw:
-    rule: allow
-    port: "{{ item.host | default(item.container) }}"
-    proto: "{{ item.protocol | default('tcp') }}"
-  loop: "{{ docker_app_ufw_ports }}"
-  when: docker_app_routing_mode == "host"
-  tags: [docker_app, firewall]
-
-- name: Start Docker app
-  community.docker.docker_compose_v2:
-    project_src: "{{ docker_app_dir }}"
-    state: present
-    pull: "{{ docker_app_pull }}"
-  tags: [docker_app, compose]

roles/docker_app/templates/compose.override.yaml.j2

@@ -0,0 +1,3 @@
+services:
+  {{ docker_app_name }}: {}
+

roles/docker_app/templates/compose.yaml.j2

@@ -17,10 +17,10 @@ services:
 {% if docker_app_env | length > 0 %}
     env_file: .env
 {% endif %}
-{% if docker_app_routing_mode == "host" and docker_app_ports | length > 0 %}
+{% if docker_app_routing_mode in ["host", "traefik_file"] and docker_app_ports | length > 0 %}
     ports:
 {% for port in docker_app_ports %}
-      - "{{ port.bind | default('0.0.0.0') }}:{{ port.host | default(port.container) }}:{{ port.container }}{% if port.protocol | default('tcp') != 'tcp' %}/{{ port.protocol }}{% endif %}"
+      - "{{ port.bind | default((docker_app_traefik_file_bind_address if docker_app_routing_mode == 'traefik_file' else '0.0.0.0')) }}:{{ port.host | default(port.container) }}:{{ port.container }}{% if port.protocol | default('tcp') != 'tcp' %}/{{ port.protocol }}{% endif %}"
 {% endfor %}
 {% endif %}
 {% if docker_app_routing_mode == "traefik" and docker_app_service_port %}

roles/filebrowser_quantum/tasks/main.yml

@@ -5,6 +5,7 @@
   vars:
     docker_app_env_template_src: "{{ playbook_dir }}/../roles/filebrowser_quantum/templates/env.j2"
     docker_app_compose_template_src: "{{ playbook_dir }}/../roles/filebrowser_quantum/templates/compose.yaml.j2"
+    docker_app_compose_override_template_src: "{{ playbook_dir }}/../roles/filebrowser_quantum/templates/compose.override.yaml.j2"
     docker_app_name: "{{ filebrowser_quantum_name }}"
     docker_app_dir: "{{ filebrowser_quantum_dir }}"
     docker_app_image: "{{ filebrowser_quantum_image }}"

roles/filebrowser_quantum/templates/compose.override.yaml.j2

@@ -0,0 +1,3 @@
+services:
+  {{ docker_app_name }}: {}
+

roles/filebrowser_quantum/templates/compose.yaml.j2

@@ -17,10 +17,10 @@ services:
 {% if docker_app_env | length > 0 %}
     env_file: .env
 {% endif %}
-{% if docker_app_routing_mode == "host" and docker_app_ports | length > 0 %}
+{% if docker_app_routing_mode in ["host", "traefik_file"] and docker_app_ports | length > 0 %}
     ports:
 {% for port in docker_app_ports %}
-      - "{{ port.bind | default('0.0.0.0') }}:{{ port.host | default(port.container) }}:{{ port.container }}{% if port.protocol | default('tcp') != 'tcp' %}/{{ port.protocol }}{% endif %}"
+      - "{{ port.bind | default((docker_app_traefik_file_bind_address if docker_app_routing_mode == 'traefik_file' else '0.0.0.0')) }}:{{ port.host | default(port.container) }}:{{ port.container }}{% if port.protocol | default('tcp') != 'tcp' %}/{{ port.protocol }}{% endif %}"
 {% endfor %}
 {% endif %}
 {% if docker_app_routing_mode == "traefik" and docker_app_service_port %}

roles/filebrowser_quantum/upstream/SOURCE.md

@@ -0,0 +1,7 @@
+# Upstream Snapshot
+
+This directory stores copied upstream reference files for the `filebrowser_quantum` role.
+
+See `docs/upstream-sources.yml` for repository URLs, refs, README paths, Compose paths, and verification status.
+
+Snapshot files are reference material only. Deployments are generated from this role's `templates/` directory.

roles/fiveetools/tasks/main.yml

@@ -5,6 +5,7 @@
   vars:
     docker_app_env_template_src: "{{ playbook_dir }}/../roles/fiveetools/templates/env.j2"
     docker_app_compose_template_src: "{{ playbook_dir }}/../roles/fiveetools/templates/compose.yaml.j2"
+    docker_app_compose_override_template_src: "{{ playbook_dir }}/../roles/fiveetools/templates/compose.override.yaml.j2"
     docker_app_name: "{{ fiveetools_name }}"
     docker_app_dir: "{{ fiveetools_dir }}"
     docker_app_image: "{{ fiveetools_image }}"

roles/fiveetools/templates/compose.override.yaml.j2

@@ -0,0 +1,3 @@
+services:
+  {{ docker_app_name }}: {}
+

roles/fiveetools/templates/compose.yaml.j2

@@ -17,10 +17,10 @@ services:
 {% if docker_app_env | length > 0 %}
     env_file: .env
 {% endif %}
-{% if docker_app_routing_mode == "host" and docker_app_ports | length > 0 %}
+{% if docker_app_routing_mode in ["host", "traefik_file"] and docker_app_ports | length > 0 %}
     ports:
 {% for port in docker_app_ports %}
-      - "{{ port.bind | default('0.0.0.0') }}:{{ port.host | default(port.container) }}:{{ port.container }}{% if port.protocol | default('tcp') != 'tcp' %}/{{ port.protocol }}{% endif %}"
+      - "{{ port.bind | default((docker_app_traefik_file_bind_address if docker_app_routing_mode == 'traefik_file' else '0.0.0.0')) }}:{{ port.host | default(port.container) }}:{{ port.container }}{% if port.protocol | default('tcp') != 'tcp' %}/{{ port.protocol }}{% endif %}"
 {% endfor %}
 {% endif %}
 {% if docker_app_routing_mode == "traefik" and docker_app_service_port %}

roles/fiveetools/upstream/SOURCE.md

@@ -0,0 +1,7 @@
+# Upstream Snapshot
+
+This directory stores copied upstream reference files for the `fiveetools` role.
+
+See `docs/upstream-sources.yml` for repository URLs, refs, README paths, Compose paths, and verification status.
+
+Snapshot files are reference material only. Deployments are generated from this role's `templates/` directory.

roles/fiveetools/upstream/docker-compose.yml

@@ -0,0 +1,13 @@
+services:
+  5etools:
+    container_name: 5etools
+    image: jafner/5etools-docker
+    volumes:
+      - ./5etools-docker/htdocs:/usr/local/apache2/htdocs
+    ports:
+     - 5370:80/tcp
+    environment:
+     - IMG=TRUE # Set to TRUE to pull images from https://github.com/5etools-mirror-2/5etools-img (as a Git submodule)
+#     - OFFLINE_MODE=TRUE # Optional. Expects "TRUE" or "FALSE". Disables checking for new updates.
+     - DL_LINK=https://github.com/5etools-mirror-3/5etools-src.git
+     - IMG_LINK=https://github.com/5etools-mirror-3/5etools-img.git

roles/flaresolverr/tasks/main.yml

@@ -5,6 +5,7 @@
   vars:
     docker_app_env_template_src: "{{ playbook_dir }}/../roles/flaresolverr/templates/env.j2"
     docker_app_compose_template_src: "{{ playbook_dir }}/../roles/flaresolverr/templates/compose.yaml.j2"
+    docker_app_compose_override_template_src: "{{ playbook_dir }}/../roles/flaresolverr/templates/compose.override.yaml.j2"
     docker_app_name: "{{ flaresolverr_name }}"
     docker_app_dir: "{{ flaresolverr_dir }}"
     docker_app_image: "{{ flaresolverr_image }}"

roles/flaresolverr/templates/compose.override.yaml.j2

@@ -0,0 +1,3 @@
+services:
+  {{ docker_app_name }}: {}
+

roles/flaresolverr/templates/compose.yaml.j2

@@ -17,10 +17,10 @@ services:
 {% if docker_app_env | length > 0 %}
     env_file: .env
 {% endif %}
-{% if docker_app_routing_mode == "host" and docker_app_ports | length > 0 %}
+{% if docker_app_routing_mode in ["host", "traefik_file"] and docker_app_ports | length > 0 %}
     ports:
 {% for port in docker_app_ports %}
-      - "{{ port.bind | default('0.0.0.0') }}:{{ port.host | default(port.container) }}:{{ port.container }}{% if port.protocol | default('tcp') != 'tcp' %}/{{ port.protocol }}{% endif %}"
+      - "{{ port.bind | default((docker_app_traefik_file_bind_address if docker_app_routing_mode == 'traefik_file' else '0.0.0.0')) }}:{{ port.host | default(port.container) }}:{{ port.container }}{% if port.protocol | default('tcp') != 'tcp' %}/{{ port.protocol }}{% endif %}"
 {% endfor %}
 {% endif %}
 {% if docker_app_routing_mode == "traefik" and docker_app_service_port %}

roles/flaresolverr/upstream/SOURCE.md

@@ -0,0 +1,7 @@
+# Upstream Snapshot
+
+This directory stores copied upstream reference files for the `flaresolverr` role.
+
+See `docs/upstream-sources.yml` for repository URLs, refs, README paths, Compose paths, and verification status.
+
+Snapshot files are reference material only. Deployments are generated from this role's `templates/` directory.

roles/gitea/handlers/.gitkeep

@@ -0,0 +1 @@
+

roles/gitea/handlers/main.yml

@@ -1,6 +0,0 @@
----
-- name: restart gitea
-  community.docker.docker_compose_v2:
-    project_src: "{{ gitea_dir }}"
-    state: restarted
-

roles/gitea/tasks/main.yml

@@ -8,41 +8,21 @@
     mode: "0755"
   tags: [gitea]
 
-- name: Render Gitea environment
+- name: Deploy Gitea Compose project
-  ansible.builtin.template:
+  ansible.builtin.include_role:
-    src: env.j2
+    name: compose_project
-    dest: "{{ gitea_dir }}/.env"
+  vars:
-    owner: root
+    compose_project_dir: "{{ gitea_dir }}"
-    group: root
+    compose_project_directories:
-    mode: "0600"
+      - "{{ gitea_dir }}"
-  no_log: true
+    compose_project_env_template_src: "{{ playbook_dir }}/../roles/gitea/templates/env.j2"
-  tags: [gitea, config]
+    compose_project_compose_template_src: "{{ playbook_dir }}/../roles/gitea/templates/compose.yaml.j2"
-
+    compose_project_override_template_src: "{{ playbook_dir }}/../roles/gitea/templates/compose.override.yaml.j2"
-- name: Ensure Gitea proxy network exists
+    compose_project_create_proxy_network: "{{ gitea_routing_mode == 'traefik' }}"
-  community.docker.docker_network:
+    compose_project_proxy_network: "{{ gitea_traefik_network }}"
-    name: "{{ gitea_traefik_network }}"
+    compose_project_firewall_ports: "{{ gitea_tcp_ports }}"
-    state: present
+    compose_project_firewall_enabled: "{{ gitea_routing_mode in ['host', 'traefik_file'] }}"
-  when: gitea_routing_mode == "traefik"
+  tags: [gitea]
-  tags: [gitea, docker]
-
-- name: Render Gitea Compose file
-  ansible.builtin.template:
-    src: compose.yaml.j2
-    dest: "{{ gitea_dir }}/compose.yaml"
-    owner: root
-    group: root
-    mode: "0644"
-  notify: restart gitea
-  tags: [gitea, compose]
-
-- name: Allow Gitea ports
-  community.general.ufw:
-    rule: allow
-    port: "{{ item }}"
-    proto: tcp
-  loop: "{{ gitea_tcp_ports }}"
-  when: gitea_routing_mode == "host"
-  tags: [gitea, firewall]
 
 - name: Allow Gitea SSH port when published behind Traefik
   community.general.ufw:
@@ -53,9 +33,3 @@
     - gitea_routing_mode == "traefik"
     - gitea_publish_ssh | bool
   tags: [gitea, firewall]
-
-- name: Start Gitea
-  community.docker.docker_compose_v2:
-    project_src: "{{ gitea_dir }}"
-    state: present
-  tags: [gitea, compose]

roles/gitea/templates/compose.override.yaml.j2

@@ -0,0 +1,3 @@
+services:
+  gitea: {}
+

roles/gitea/templates/compose.yaml.j2

@@ -3,10 +3,10 @@ services:
     image: {{ gitea_image }}
     restart: unless-stopped
     env_file: .env
-{% if gitea_routing_mode == "host" or gitea_publish_ssh | bool %}
+{% if gitea_routing_mode in ["host", "traefik_file"] or gitea_publish_ssh | bool %}
     ports:
-{% if gitea_routing_mode == "host" %}
+{% if gitea_routing_mode in ["host", "traefik_file"] %}
-      - "{{ gitea_http_port }}:3000"
+      - "{{ nbops_traefik_file_bind_address if gitea_routing_mode == 'traefik_file' else '0.0.0.0' }}:{{ gitea_http_port }}:3000"
 {% endif %}
 {% if gitea_publish_ssh | bool %}
       - "{{ gitea_ssh_port }}:22"

roles/gitea/upstream/SOURCE.md

@@ -0,0 +1,7 @@
+# Upstream Snapshot
+
+This directory stores copied upstream reference files for the `gitea` role.
+
+See `docs/upstream-sources.yml` for repository URLs, refs, README paths, Compose paths, and verification status.
+
+Snapshot files are reference material only. Deployments are generated from this role's `templates/` directory.

roles/gitea_act_runner/tasks/main.yml

@@ -5,6 +5,7 @@
   vars:
     docker_app_env_template_src: "{{ playbook_dir }}/../roles/gitea_act_runner/templates/env.j2"
     docker_app_compose_template_src: "{{ playbook_dir }}/../roles/gitea_act_runner/templates/compose.yaml.j2"
+    docker_app_compose_override_template_src: "{{ playbook_dir }}/../roles/gitea_act_runner/templates/compose.override.yaml.j2"
     docker_app_name: "{{ gitea_act_runner_name }}"
     docker_app_dir: "{{ gitea_act_runner_dir }}"
     docker_app_image: "{{ gitea_act_runner_image }}"

roles/gitea_act_runner/templates/compose.override.yaml.j2

@@ -0,0 +1,3 @@
+services:
+  {{ docker_app_name }}: {}
+

roles/gitea_act_runner/templates/compose.yaml.j2

@@ -17,10 +17,10 @@ services:
 {% if docker_app_env | length > 0 %}
     env_file: .env
 {% endif %}
-{% if docker_app_routing_mode == "host" and docker_app_ports | length > 0 %}
+{% if docker_app_routing_mode in ["host", "traefik_file"] and docker_app_ports | length > 0 %}
     ports:
 {% for port in docker_app_ports %}
-      - "{{ port.bind | default('0.0.0.0') }}:{{ port.host | default(port.container) }}:{{ port.container }}{% if port.protocol | default('tcp') != 'tcp' %}/{{ port.protocol }}{% endif %}"
+      - "{{ port.bind | default((docker_app_traefik_file_bind_address if docker_app_routing_mode == 'traefik_file' else '0.0.0.0')) }}:{{ port.host | default(port.container) }}:{{ port.container }}{% if port.protocol | default('tcp') != 'tcp' %}/{{ port.protocol }}{% endif %}"
 {% endfor %}
 {% endif %}
 {% if docker_app_routing_mode == "traefik" and docker_app_service_port %}

roles/gitea_act_runner/upstream/SOURCE.md

@@ -0,0 +1,7 @@
+# Upstream Snapshot
+
+This directory stores copied upstream reference files for the `gitea_act_runner` role.
+
+See `docs/upstream-sources.yml` for repository URLs, refs, README paths, Compose paths, and verification status.
+
+Snapshot files are reference material only. Deployments are generated from this role's `templates/` directory.

roles/grafana/tasks/main.yml

@@ -5,6 +5,7 @@
   vars:
     docker_app_env_template_src: "{{ playbook_dir }}/../roles/grafana/templates/env.j2"
     docker_app_compose_template_src: "{{ playbook_dir }}/../roles/grafana/templates/compose.yaml.j2"
+    docker_app_compose_override_template_src: "{{ playbook_dir }}/../roles/grafana/templates/compose.override.yaml.j2"
     docker_app_name: "{{ grafana_name }}"
     docker_app_dir: "{{ grafana_dir }}"
     docker_app_image: "{{ grafana_image }}"

roles/grafana/templates/compose.override.yaml.j2

@@ -0,0 +1,3 @@
+services:
+  {{ docker_app_name }}: {}
+

roles/grafana/templates/compose.yaml.j2

@@ -17,10 +17,10 @@ services:
 {% if docker_app_env | length > 0 %}
     env_file: .env
 {% endif %}
-{% if docker_app_routing_mode == "host" and docker_app_ports | length > 0 %}
+{% if docker_app_routing_mode in ["host", "traefik_file"] and docker_app_ports | length > 0 %}
     ports:
 {% for port in docker_app_ports %}
-      - "{{ port.bind | default('0.0.0.0') }}:{{ port.host | default(port.container) }}:{{ port.container }}{% if port.protocol | default('tcp') != 'tcp' %}/{{ port.protocol }}{% endif %}"
+      - "{{ port.bind | default((docker_app_traefik_file_bind_address if docker_app_routing_mode == 'traefik_file' else '0.0.0.0')) }}:{{ port.host | default(port.container) }}:{{ port.container }}{% if port.protocol | default('tcp') != 'tcp' %}/{{ port.protocol }}{% endif %}"
 {% endfor %}
 {% endif %}
 {% if docker_app_routing_mode == "traefik" and docker_app_service_port %}

roles/grafana/upstream/SOURCE.md

@@ -0,0 +1,7 @@
+# Upstream Snapshot
+
+This directory stores copied upstream reference files for the `grafana` role.
+
+See `docs/upstream-sources.yml` for repository URLs, refs, README paths, Compose paths, and verification status.
+
+Snapshot files are reference material only. Deployments are generated from this role's `templates/` directory.

roles/grafana_renderer/tasks/main.yml

@@ -5,6 +5,7 @@
   vars:
     docker_app_env_template_src: "{{ playbook_dir }}/../roles/grafana_renderer/templates/env.j2"
     docker_app_compose_template_src: "{{ playbook_dir }}/../roles/grafana_renderer/templates/compose.yaml.j2"
+    docker_app_compose_override_template_src: "{{ playbook_dir }}/../roles/grafana_renderer/templates/compose.override.yaml.j2"
     docker_app_name: "{{ grafana_renderer_name }}"
     docker_app_dir: "{{ grafana_renderer_dir }}"
     docker_app_image: "{{ grafana_renderer_image }}"

roles/grafana_renderer/templates/compose.override.yaml.j2

@@ -0,0 +1,3 @@
+services:
+  {{ docker_app_name }}: {}
+

roles/grafana_renderer/templates/compose.yaml.j2

@@ -17,10 +17,10 @@ services:
 {% if docker_app_env | length > 0 %}
     env_file: .env
 {% endif %}
-{% if docker_app_routing_mode == "host" and docker_app_ports | length > 0 %}
+{% if docker_app_routing_mode in ["host", "traefik_file"] and docker_app_ports | length > 0 %}
     ports:
 {% for port in docker_app_ports %}
-      - "{{ port.bind | default('0.0.0.0') }}:{{ port.host | default(port.container) }}:{{ port.container }}{% if port.protocol | default('tcp') != 'tcp' %}/{{ port.protocol }}{% endif %}"
+      - "{{ port.bind | default((docker_app_traefik_file_bind_address if docker_app_routing_mode == 'traefik_file' else '0.0.0.0')) }}:{{ port.host | default(port.container) }}:{{ port.container }}{% if port.protocol | default('tcp') != 'tcp' %}/{{ port.protocol }}{% endif %}"
 {% endfor %}
 {% endif %}
 {% if docker_app_routing_mode == "traefik" and docker_app_service_port %}

roles/grafana_renderer/upstream/SOURCE.md

@@ -0,0 +1,7 @@
+# Upstream Snapshot
+
+This directory stores copied upstream reference files for the `grafana_renderer` role.
+
+See `docs/upstream-sources.yml` for repository URLs, refs, README paths, Compose paths, and verification status.
+
+Snapshot files are reference material only. Deployments are generated from this role's `templates/` directory.

roles/grafana_renderer/upstream/docker-compose.yml

@@ -0,0 +1,5 @@
+services:
+  renderer:
+    container_name: grafana-renderer
+    image: grafana/grafana-image-renderer:latest
+    restart: unless-stopped

roles/homarr/tasks/main.yml

@@ -5,6 +5,7 @@
   vars:
     docker_app_env_template_src: "{{ playbook_dir }}/../roles/homarr/templates/env.j2"
     docker_app_compose_template_src: "{{ playbook_dir }}/../roles/homarr/templates/compose.yaml.j2"
+    docker_app_compose_override_template_src: "{{ playbook_dir }}/../roles/homarr/templates/compose.override.yaml.j2"
     docker_app_name: "{{ homarr_name }}"
     docker_app_dir: "{{ homarr_dir }}"
     docker_app_image: "{{ homarr_image }}"

roles/homarr/templates/compose.override.yaml.j2

@@ -0,0 +1,3 @@
+services:
+  {{ docker_app_name }}: {}
+

roles/homarr/templates/compose.yaml.j2

@@ -17,10 +17,10 @@ services:
 {% if docker_app_env | length > 0 %}
     env_file: .env
 {% endif %}
-{% if docker_app_routing_mode == "host" and docker_app_ports | length > 0 %}
+{% if docker_app_routing_mode in ["host", "traefik_file"] and docker_app_ports | length > 0 %}
     ports:
 {% for port in docker_app_ports %}
-      - "{{ port.bind | default('0.0.0.0') }}:{{ port.host | default(port.container) }}:{{ port.container }}{% if port.protocol | default('tcp') != 'tcp' %}/{{ port.protocol }}{% endif %}"
+      - "{{ port.bind | default((docker_app_traefik_file_bind_address if docker_app_routing_mode == 'traefik_file' else '0.0.0.0')) }}:{{ port.host | default(port.container) }}:{{ port.container }}{% if port.protocol | default('tcp') != 'tcp' %}/{{ port.protocol }}{% endif %}"
 {% endfor %}
 {% endif %}
 {% if docker_app_routing_mode == "traefik" and docker_app_service_port %}

roles/homarr/upstream/SOURCE.md

@@ -0,0 +1,7 @@
+# Upstream Snapshot
+
+This directory stores copied upstream reference files for the `homarr` role.
+
+See `docs/upstream-sources.yml` for repository URLs, refs, README paths, Compose paths, and verification status.
+
+Snapshot files are reference material only. Deployments are generated from this role's `templates/` directory.