{"id":50521323,"url":"https://github.com/dryvist/ansible-proxmox-apps","last_synced_at":"2026-07-04T20:00:31.122Z","repository":{"id":333366859,"uuid":"1136622486","full_name":"dryvist/ansible-proxmox-apps","owner":"dryvist","description":"Ansible roles for configuring applications on Proxmox VMs and LXC containers - includes Cribl Edge, Cribl Stream, HAProxy syslog load balancer, and common application patterns","archived":false,"fork":false,"pushed_at":"2026-07-03T02:58:36.000Z","size":7862,"stargazers_count":0,"open_issues_count":20,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-03T04:36:00.271Z","etag":null,"topics":["ansible","automation","cribl","devops","haproxy","infrastructure-as-code","log-management","lxc","observability","proxmox","syslog","virtualization"],"latest_commit_sha":null,"homepage":null,"language":"Jinja","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dryvist.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-18T02:52:50.000Z","updated_at":"2026-07-03T02:58:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dryvist/ansible-proxmox-apps","commit_stats":null,"previous_names":["jacobpevans/ansible-proxmox-apps","dryvist/ansible-proxmox-apps"],"tags_count":134,"template":false,"template_full_name":null,"purl":"pkg:github/dryvist/ansible-proxmox-apps","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dryvist%2Fansible-proxmox-apps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dryvist%2Fansible-proxmox-apps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dryvist%2Fansible-proxmox-apps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dryvist%2Fansible-proxmox-apps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dryvist","download_url":"https://codeload.github.com/dryvist/ansible-proxmox-apps/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dryvist%2Fansible-proxmox-apps/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35133834,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-04T02:00:05.987Z","response_time":113,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansible","automation","cribl","devops","haproxy","infrastructure-as-code","log-management","lxc","observability","proxmox","syslog","virtualization"],"created_at":"2026-06-03T04:03:59.194Z","updated_at":"2026-07-04T20:00:31.054Z","avatar_url":"https://github.com/dryvist.png","language":"Jinja","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ansible Proxmox Apps\n\nConfigure applications running on Proxmox VMs and LXC containers.\n\nThis repository manages application deployment and configuration only. It assumes\nthe target VMs and containers — and their persistent storage — already exist and\nare reachable over SSH. It does not provision infrastructure; it consumes a\npublished inventory describing the hosts it should configure (see\n[Inventory contract](#inventory-contract)).\n\n## Purpose and Scope\n\nDeploy and configure the following application stacks:\n\n- **Cribl Edge**: Syslog ingestion and log processing with persistent queue\n- **Cribl Stream**: Central processing node for log pipeline\n- **HAProxy**: Syslog/netflow load balancer distributing traffic to Cribl nodes\n\nCribl Edge, Cribl Stream, and HAProxy run natively on LXC containers. Splunk runs\non a VM. This repository handles application configuration on those hosts; it does\nnot create them.\n\n## Inventory contract\n\nThis repository is configuration-only. It expects the hosts, their IPs, and the\npipeline's port constants to be supplied at run time as a published inventory\nartifact — a single JSON document — rather than hardcoded here. Any system that\nemits a document matching the shape below can drive these playbooks.\n\nThe inventory loader (`inventory/load_tofu.yml`) resolves the artifact at run\ntime, in priority order (first that resolves wins):\n\n1. `TOFU_INVENTORY_PATH` — an explicit local file (pin / override, e.g. tests).\n2. **Published S3 artifact** — the raw inventory JSON fetched natively from S3\n   (`amazon.aws.aws_caller_info` + `amazon.aws.s3_object`; boto3 comes from the\n   dev shell — no checkout, no provisioning toolchain, no `aws` CLI). Point at it\n   with `TOFU_INVENTORY_S3_URI` (else the URI is derived from the active AWS\n   account); set the region with `TOFU_INVENTORY_S3_REGION` (default `us-east-2`).\n3. `inventory/tofu_inventory.json` — a local gitignored cache.\n\nThe resolved document is loaded as `tofu_data` and validated before any play\nruns. It MUST contain at least:\n\n- `tofu_data.domain` — the DNS domain used to derive each container's Proxmox\n  node host as `{node-role}.{domain}` (so there is no global Proxmox host to set).\n- `tofu_data.nodes` — node-name to role mapping, used in the FQDN derivation above.\n- `tofu_data.containers`, `tofu_data.vms`, `tofu_data.docker_vms`,\n  `tofu_data.splunk_vm` — the hosts to configure, each carrying its IP and\n  connection settings; surfaced to roles via `hostvars`.\n- `tofu_data.constants` — the pipeline's port assignments. `service_ports` and\n  `syslog_ports` are required; roles also read `syslog_port_map`, `netflow_ports`,\n  `notification_ports`, and `media_ports`. Ports are never hardcoded in playbooks\n  or roles — they are always read from `tofu_data.constants`.\n\nIf `tofu_data` is missing required keys, the loader fails loudly before\nconfiguring anything.\n\n## Installation\n\nThis repository owns its toolchain via a Nix flake + direnv (`ansible`,\n`ansible-lint`, `molecule`, `sops`, `age`, `python3` with paramiko/pyyaml/jinja2,\n`jq`, `yq`, `pre-commit`). Run everything inside that dev shell.\n\n```bash\ngit clone \u003crepo-url\u003e ansible-proxmox-apps\ncd ansible-proxmox-apps\ndirenv allow    # one-time per worktree — auto-activates the dev shell on cd\n\n# Install required Ansible Galaxy collections\nansible-galaxy collection install -r requirements.yml\n\n# Configure Doppler for secrets (API keys, passwords)\ndoppler configure set project ansible-proxmox-apps\ndoppler configure set config prd\n```\n\nSet the SSH key used to reach the LXC containers. The Docker-VM roles\n(testing/dev only) reach their hosts over a separate key, which the inventory\nloader requires whenever the inventory contains Docker VMs:\n\n```bash\n# SSH key for the LXC containers (production stacks)\nexport PROXMOX_SSH_KEY_PATH=\"\u003cpath-to-ssh-key\u003e\"\n\n# SSH key for the Docker VMs — required when the inventory has docker_vms\nexport PROXMOX_DKR_SSH_KEY_PATH=\"\u003cpath-to-docker-vm-ssh-key\u003e\"\n```\n\n## Usage\n\nRun playbooks inside the dev shell, with secrets injected by Doppler. Hosts and\nports come from the published inventory (see\n[Inventory contract](#inventory-contract)).\n\n```bash\n# Deploy Cribl Edge (syslog processing on LXC containers)\ndoppler run -- ansible-playbook \\\n  -i inventory/hosts.yml playbooks/site.yml --tags cribl_edge\n\n# Deploy Cribl Stream (netflow/IPFIX processing on LXC containers)\ndoppler run -- ansible-playbook \\\n  -i inventory/hosts.yml playbooks/site.yml --tags cribl_stream\n\n# Deploy HAProxy (load balancer on LXC container)\ndoppler run -- ansible-playbook \\\n  -i inventory/hosts.yml playbooks/site.yml --tags haproxy\n\n# Deploy all applications\ndoppler run -- ansible-playbook \\\n  -i inventory/hosts.yml playbooks/site.yml\n```\n\n## Roles\n\n### cribl_edge\n\nDeploy Cribl Edge log processor with syslog listeners and Splunk HEC output.\n\n- Installs Cribl Edge from official package repository\n- Configures UDP/TCP syslog listeners (ports 1514-1518)\n- Configures Splunk HEC output\n- Mounts 100GB persistent queue disk at `/opt/cribl/data`\n\nSee `roles/cribl_edge/README.md` for detailed configuration.\n\n### cribl_stream\n\nDeploy Cribl Stream as central processing node in the pipeline.\n\n- Installs Cribl Stream from official packages\n- Configures as processing node (not leader)\n- Mounts 100GB persistent queue disk at `/opt/cribl/data`\n\nSee `roles/cribl_stream/README.md` for configuration options.\n\n### haproxy\n\nProduction load balancer on a dedicated LXC container.\n\n- Installs HAProxy and Nginx Stream on the HAProxy LXC container\n- Forwards syslog traffic (TCP/UDP) to Cribl Edge LXC containers\n- Forwards netflow/IPFIX traffic (TCP/UDP) to Cribl Stream LXC containers\n- HAProxy stats dashboard available (port from `tofu_data.constants`)\n\nSee `roles/haproxy/README.md` for details.\n\n### apt_cacher_ng\n\nAPT package caching proxy to reduce bandwidth usage across containers and VMs.\n\nSee `roles/apt_cacher_ng/README.md` for configuration.\n\n### cribl_docker_stack (testing/dev only)\n\nDeploy Cribl Stream and Cribl Edge as Docker containers on the docker-host VM.\nThis role is for testing and development only. Production pipelines use the\n`cribl_edge` and `cribl_stream` roles on native LXC containers.\n\n### mailpit_docker\n\nDeploy Mailpit email testing container for local SMTP capture and inspection.\n\n### mssql_docker\n\nDeploy Microsoft SQL Server as a Docker container.\n\n### ntfy_docker\n\nDeploy ntfy push notification service as a Docker container.\n\n### technitium_dns\n\nDeploy Technitium DNS server container for local DNS resolution and blocking.\n\n## Architecture\n\nAll production components run on LXC containers (Cribl Edge, Cribl Stream,\nHAProxy) or VMs (Splunk).\n\n```text\n┌──────────────────┐    ┌──────────────────┐\n│  Syslog Sources  │    │ NetFlow Sources   │\n└────────┬─────────┘    └────────┬─────────┘\n         │                       │\n    (UDP/TCP syslog)        (UDP IPFIX)\n         │                       │\n         ▼                       ▼\n┌────────────────────────────────────────┐\n│         HAProxy LXC                    │\n│         (Load Balancer)                │\n└───────┬────────────────────┬───────────┘\n        │                    │\n   (syslog)             (netflow)\n        │                    │\n        ▼                    ▼\n   ┌─────────┐         ┌──────────┐\n   │Cribl    │         │Cribl     │\n   │Edge LXCs│         │Stream    │\n   │(syslog) │         │LXCs     │\n   └────┬────┘         │(IPFIX)  │\n        │              └────┬─────┘\n        │                   │\n        └─────────┬─────────┘\n                  │\n            (Splunk HEC)\n                  │\n                  ▼\n           ┌──────────────┐\n           │    Splunk    │\n           │      VM      │\n           └──────────────┘\n```\n\n## File Layout\n\n```text\nansible-proxmox-apps/\n├── README.md                    This file\n├── CLAUDE.md                    AI agent documentation\n├── ansible.cfg                  Ansible configuration\n├── requirements.yml             Ansible Galaxy dependencies\n├── .ansible-lint                Linting rules\n├── .gitignore                   Git ignore rules\n├── .pre-commit-config.yaml      Pre-commit hooks\n├── inventory/\n│   ├── hosts.yml                Static shared vars (hosts added dynamically)\n│   ├── load_tofu.yml            Resolves \u0026 validates the inventory artifact\n│   └── group_vars/\n│       └── all.yml              Global variables\n├── playbooks/\n│   └── site.yml                 Main playbook (all roles)\n└── roles/\n    ├── cribl_edge/\n    │   ├── README.md\n    │   ├── defaults/main.yml\n    │   ├── tasks/main.yml\n    │   ├── handlers/main.yml\n    │   └── templates/\n    ├── cribl_stream/\n    │   ├── README.md\n    │   ├── defaults/main.yml\n    │   ├── tasks/main.yml\n    │   ├── handlers/main.yml\n    │   └── templates/\n    └── haproxy/\n        ├── README.md\n        ├── defaults/main.yml\n        ├── tasks/main.yml\n        ├── handlers/main.yml\n        └── templates/\n            └── haproxy.cfg.j2\n```\n\n## Linting\n\nValidate code quality with ansible-lint:\n\n```bash\nansible-lint\n```\n\nFix common issues automatically:\n\n```bash\nansible-lint --fix\n```\n\n## Contributing\n\n1. Update inventory handling in `inventory/`\n2. Modify roles in `roles/*/`\n3. Test with `--check --diff` mode\n4. Validate with `ansible-lint`\n5. Run playbook to apply\n\n## License\n\nApache License 2.0 - see [LICENSE](LICENSE) for details.\n\n---\n\n\u003e Part of a [larger ecosystem of ~40 repos](https://docs.jacobpevans.com) — see how it all fits together.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdryvist%2Fansible-proxmox-apps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdryvist%2Fansible-proxmox-apps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdryvist%2Fansible-proxmox-apps/lists"}