Skip to main content

Documentation

The platform's documentation site, plus the notes that describe it as a whole: the child repos, the order they deploy in, and the diagram tying them together. Each repo's own README and docs/ folder is part of the site too. See ../README.md for the quickstart and the controller tool section for what iac-ctl's menu actions do.

Notes in this repo:

  • prerequisites.md: manually managed components and network flow that exist before any deployer runs.
  • router.md: the OpenWrt router's configuration and rebuild checklist.
  • DEVELOPMENT.md: building and previewing the site.

Platform repos​

vault-deployer​

Ansible automation that deploys a single-node secrets vault (mTLS-secured, standalone, backed by its own integrated Raft storage, with automatic unsealing via a root cron job) onto a remote host. It bootstraps without depending on itself: every secret it needs comes from the environment. Runs first, before every other repo, since the DevOps server, onboarding, and application repos read their secrets and per-host config from it.

devops-server-deployer​

Ansible automation that deploys every service on the DevOps server host, one play, inventory group, and tag prefix per service, in this order:

  • PyPI mirror (pypi_mirror_*): a pull-through cache for upstream Python packages used by the platform's Python/uv-based repos.
  • Database (database_*): PostgreSQL, the platform's shared, externally managed Postgres server, reached by its clients through connection details Vault stores. It also seeds Vault with a generated access credential for each downstream database. See devops-server-deployer/docs/database.md for the exact Vault paths and schema.
  • SCM (scm_*): the self-hosted DevOps server itself: source code hosting, artifact delivery (container images, Python packages, generic binaries, release assets), and CI/CD pipelines, connecting as a client to the shared Postgres server, with an internal Root CA, secrets, fail2ban, and CI/CD runners.

Runs after Vault.

devops-server-onboarding​

Scripts that provision users on the DevOps server and on the PyPI mirror, publish artifacts (generic binaries, container images, OpenAPI Python clients) to the devops-server registries, and mirror selected GitHub repositories onto the devops-server as public pull mirrors.

application-deployer​

Ansible automation that deploys the full home-lab: host patching/hardening, NFS, LUKS-encrypted disk mounts, NVIDIA GPU drivers, Docker, VPN (NordVPN or WireGuard, mutually exclusive per host), MinIO S3, Restic backups, a reverse proxy (Caddy or Nginx Proxy Manager, pluggable per host), PostgreSQL, Nextcloud, Emby, Jellyfin, qBittorrent, Samba, Code Server, Navidrome, Vikunja.

dashboard​

Docker Compose stack (Apache as a reverse proxy and form-based auth gate, plus Glance and Homepage) that surfaces links, widgets, and live status for every other self-hosted service and machine on the network, behind one login. See dashboard/README.md for the Homepage/Glance page layout.

Tooling​

mcp-server​

A local MCP server exposing the platform's project knowledge, devops-server management, and Vault secret management as MCP tools for Claude Desktop / Claude Code. It is tooling for working with this platform, not a deployed platform service, so it sits outside the deployment order above.

documentation​

This repo: the platform's documentation site. It is built and published separately from the controller, and it is not a deployed platform service, so it sits outside the deployment order above.

Diagram​

Infrastructure architecture

Source: infra-architecture.excalidraw. The SVG is generated from it with pnpm run diagram; see DEVELOPMENT.md.

How the pieces fit together​

  • vault-deployer stands up the shared mTLS-secured Vault secrets store first, standalone, backed by its own integrated Raft storage. The DevOps server, onboarding, and application repos read their secrets and per-host config from Vault, so none of them can run before it exists.
  • devops-server-deployer stands up the DevOps server host, one service at a time:
    • A PyPI package mirror: a pull-through cache for upstream Python packages used by the platform's Python/uv-based repos.
    • PostgreSQL: the platform's shared, externally managed Postgres server, seeded with a generated access credential in Vault for each downstream database.
    • The DevOps server itself: source code hosting, the container/PyPI/generic-binary artifact registries, and the CI/CD runners used by every other repo in the platform. Its database lives on the shared PostgreSQL server, which it connects to as a client.
  • devops-server-onboarding runs against that DevOps server and the PyPI mirror to provision users, publish the binary, container, and OpenAPI Python client artifacts other projects depend on, and mirror selected GitHub repositories. The project's organization must already exist on the DevOps server.
  • application-deployer deploys the rest of the home-lab (storage, networking, backups, reverse proxy, Nextcloud, Emby, Jellyfin, ...). Its dependency install pulls packages from the devops-server registry, so devops-server-deployer and devops-server-onboarding must already be in place first.
  • dashboard goes up last: its Apache/Glance/Homepage stack calls the live APIs of every service and machine on the network (Nginx Proxy Manager, Devops Server, its PyPI mirror, Emby/Jellyfin, Nextcloud, qBittorrent, Navidrome, Vikunja, Code Server, S3, Vault, OpenWRT, and per-machine Glances/Docker endpoints) to render its links and status widgets, so everything it displays must already exist.

The deployer/onboarding repos share the same conventions: secrets read from Vault (all but vault-deployer, which takes its secrets from the environment because it deploys Vault), CS_PROJECT_CODE scoping of Vault paths and registry namespaces, the Python/uv toolchain, ansible-lint/yamllint settings that mirror their CI workflows under .gitea/workflows/, a gitleaks pre-commit hook and CI job, the WTFPL license, an internal Root CA (stored in Vault) that signs every internal TLS certificate, one shared PostgreSQL server on the DevOps server host that the SCM service connects to as a client, and Restic backups to S3 or SFTP for persistent state (the SCM service, and most application-deployer services).