Toolsera Infrastructure
Infrastructure-as-code for a Proxmox homelab. Guests are discovered dynamically rather than listed by hand, configured by Ansible, and run their workloads as Docker Compose stacks fronted by Traefik. Secrets never live in this repo — they are injected at container start from Bitwarden Secrets Manager. Custom tooling ships as Debian packages through an internal Nexus APT repository.
New here? Start with Getting Started.
What lives here
Section titled “What lives here”| Directory | Contents |
|---|---|
ansible/ | Dynamic Proxmox inventory, six idempotent roles, and the playbooks that provision and maintain the fleet |
docker-compose-apps/ | One directory per Compose stack, routed through Traefik and fed secrets by bws run |
community-scripts-lxc/ | Config for applications installed natively into an LXC from the community-scripts helpers |
packages/ | Custom .deb packages built with dpkg-deb or FPM and published to Nexus |
utils/ | Standalone scripts that run anywhere — a laptop, the controller, a host |
docs/ | The Astro Starlight site that publishes this documentation |
Reading order
Section titled “Reading order”| Document | When you need it |
|---|---|
| Getting Started | Cloning, loading credentials, running a first playbook |
| Architecture | How provisioning, routing, secrets and package distribution fit together |
| Conventions | Internal domains, formatting, pre-commit hooks |
| Operations | The rules for changing things on a live host without breaking them |
| Host access notes | Verified SSH routes and per-host gotchas — read before touching a host |
The stack catalog is worth a look on the docs site: it is
generated by parsing the compose files themselves, including their include:
directives, so adding a stack adds a catalog entry with no documentation edit at all.
How the documentation works
Section titled “How the documentation works”Every page on the docs site is generated. Nothing is authored inside docs/ — the
site is built entirely from the Markdown in this repo, copied in at build time with
links rewritten so they resolve in both places. Each document stays canonical where it
lives, so browsing on GitHub works and the site cannot drift from it.
To add a page: write the Markdown where it belongs in the repo, then add an entry to the
SOURCES array in docs/scripts/sync-content.mjs. A
source listed there that goes missing fails the build rather than silently dropping the
page.
See docs/README.md for the full contract.