Initialise repository structure and placeholder files. Generic functionality works i guess, need to come up with a better solution for compose templates

docs/operations.md

@@ -0,0 +1,32 @@
+# Operations
+
+Install collections:
+
+```sh
+ansible-galaxy collection install -r requirements.yml
+```
+
+Run a syntax check:
+
+```sh
+ansible-playbook --syntax-check playbooks/site.yml
+```
+
+Run locally:
+
+```sh
+ansible-playbook -i inventories/development/hosts.yml playbooks/site.yml
+```
+
+Run selected tags:
+
+```sh
+ansible-playbook -i inventories/production/hosts.yml playbooks/site.yml --tags base,docker,traefik
+```
+
+Run with ansible-pull:
+
+```sh
+REPO_URL=git@github.com:example/nbops-ansible.git scripts/ansible-pull.sh
+```
+

docs/proxmox-template.md

@@ -0,0 +1,20 @@
+# Proxmox Debian 13 GenericCloud Template
+
+Expected VM defaults:
+
+- Debian 13 Trixie GenericCloud image
+- Q35 machine type
+- UEFI / OVMF
+- VirtIO SCSI controller
+- VirtIO network device
+- CPU type `host`
+- QEMU Guest Agent enabled
+- Cloud-Init drive attached
+- 2 vCPU, 2 GB RAM, 32 GB disk unless a service needs more
+
+Cloud-Init is only responsible for Day 0 bootstrap: user creation, SSH
+hardening, Docker installation, baseline packages, firewall defaults, directory
+layout, PKI directory preparation, and `ansible-pull`.
+
+Applications and durable service configuration belong in Ansible roles.
+

docs/secrets.md

@@ -0,0 +1,16 @@
+# Secrets
+
+Do not commit passwords, API keys, issued certificates, private keys, or `.env`
+files containing secrets.
+
+This repository is ready for these future integrations:
+
+- Ansible Vault
+- SOPS
+- HashiCorp Vault
+- Smallstep certificates
+
+Role defaults deliberately use `CHANGE_ME_IN_VAULT` placeholders for required
+application secrets. Override those values in encrypted inventory data before
+deploying real services.
+

docs/service-catalog.md

@@ -0,0 +1,63 @@
+# Service Catalog
+
+These Docker service roles are available through `nbops_roles`.
+
+Media and downloads:
+
+- `jellyfin`
+- `jellyseerr`
+- `qbittorrent`
+- `transmission`
+- `wizarr`
+- `flaresolverr`
+- `cleanuparr`
+- `pinchflat`
+- `kavita`
+
+Identity and access:
+
+- `authentik`
+- `authentik_ldap`
+- `authentik_proxy`
+- `authentik_rac`
+- `vaultwarden`
+
+Dashboards and file tools:
+
+- `homarr`
+- `nginx_content`
+- `code_server`
+- `filebrowser_quantum`
+- `kiwix_serve`
+- `requarks`
+- `fiveetools`
+- `ntfy`
+
+Infrastructure:
+
+- `pelican_panel`
+- `pelican_server`
+- `gitea`
+- `gitea_act_runner`
+- `postgres`
+- `php_fpm`
+- `valkey`
+- `syncthing`
+- `ipv6nat`
+
+Monitoring:
+
+- `grafana`
+- `loki`
+- `alloy`
+- `grafana_renderer`
+- `prometheus`
+- `uptime_kuma`
+
+Most roles use the shared `docker_app` implementation and support:
+
+- `host` routing mode: publish ports directly and open UFW rules.
+- `traefik` routing mode: attach to the proxy network and render Traefik labels.
+
+Override role defaults in `host_vars` or `group_vars`; do not edit generated
+Compose files on the VM.

docs/topology.md

@@ -0,0 +1,59 @@
+# Topology
+
+Every VM is a Docker host. Proxmox and Cloud-Init only create the machine and
+bootstrap Ansible; service placement is controlled by inventory.
+
+## Edge VM
+
+The edge VM runs:
+
+- Docker
+- Traefik
+- authentik IAM
+
+It publishes Traefik entrypoints on host ports `80` and `443`. authentik can run
+behind the same local Traefik instance by setting:
+
+```yaml
+nbops_service_routing_mode: traefik
+authentik_domain: auth.example.invalid
+```
+
+## Downstream VMs
+
+Downstream VMs also run Docker. Instead of publishing each application port on
+the host, run Traefik on the VM and attach application containers to the shared
+Docker proxy network.
+
+```yaml
+nbops_roles:
+  - base
+  - ssh
+  - ufw
+  - updates
+  - docker
+  - traefik
+  - gitea
+  - immich
+
+nbops_service_routing_mode: traefik
+nbops_traefik_entrypoint: web
+nbops_traefik_tls: false
+```
+
+In this mode application roles do not publish their HTTP ports. They render
+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.
+
+## 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.
+
+Gitea is special: HTTP can be routed through Traefik while SSH remains published
+with `gitea_publish_ssh: true`.
+