a13labs.infra/AGENTS.md

AGENTS.md - A13Labs Infrastructure

Repo Structure

• ansible/ — Playbooks, roles, inventory. Runs against bare-metal servers.
• .opencode/plans/ — Plans under execution
• implemented/ — Reports of implemented features
• terraform/ — IaC (OpenTofu for K8s app deployments + cloud provisioning).
• inventory/hosts — Ansible inventory. All hosts and groups.
• requirements/ — pip requirements files: ansible.txt, dev.txt, opentofu.txt.
• sectool — Secret manager (Bitwarden, configured in sectool.json). Both root and ansible/ have their own sectool.json + sectool.env.

Key Facts

• No Makefile, no justfile, no pre-commit config. Commands are run directly.
• All GitHub workflows are .disabled — CI is not active. Verification is local-only.
• ansible/ansible.cfg points to ../inventory/hosts (relative to ansible/ dir). Always run playbooks from the ansible/ directory, or use -i to override.
• YAML linting: ansible-lint config at ansible/.ansible-lint. .yamllint.yml at ansible/.yamllint.yml (120 char line warning).
• No .pre-commit-config.yaml exists — linting is manual or CI-only.

Ansible

Required Environment vars

export ANSIBLE_USER=provision 
export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES # if on a MAC

Running playbooks

Note: sectool just need to be used when secrets must be injected to the environment, if the command does not requires secrets injection do not use sectool

sh
cd ansible
sectool exec ansible-playbook -u $ANSIBLE_USER  playbook_<name>.yml

Role testing (Molecule + Podman - Linux Only)

cd ansible/roles/<role_name>
molecule test          # create -> converge -> verify -> destroy
molecule converge       # run converge only
molecule destroy        # clean up

Molecule gotchas:

• Always run molecule commands from the role directory, not from repo root.
• Molecule containers use podman driver. No systemd by default — guard service tasks with when: ansible_service_mgr == "systemd".
• molecule/default/prepare.yml must install python3 and sudo via raw: before Ansible can run Python modules.
• provisioner.env.ANSIBLE_ROLES_PATH should point up to the parent (e.g., ../../../).

Ansible-lint

ansible-lint  # runs from repo root or ansible/

Excluded paths: .git/, .github/, tests/. Warns on: line-length, yaml[line-length], var-naming[no-role-prefix].

Terraform / OpenTofu

App deployments (K8s)

• terraform/apps/dev-01/ — dev Kubernetes cluster (microk8s)
• terraform/apps/prod-01/ — prod Kubernetes cluster (microk8s)
• Uses Kubernetes + TLS providers. provider.tf sets insecure = true.

Cloud IaC

• terraform/iac/aws/ — AWS infrastructure
• terraform/iac/contabo/ — Contabo VPS
• terraform/iac/cloudns/ — DNS (cloudns)
• terraform/iac/scaleway/ — Scaleway infrastructure

Running Terraform / OpenTofu

Each terraform directory has its own sectool.env. Run sectool to load secrets before tofu init/plan/apply: To validate plane (mandatory before apply)

sectool exec tofu plan

Apply:

sectool exec tofu apply --auto-approve

Secrets

To list secrets:

sectool vault list

To set a secret:

sectool vault set <secret name> <secret value>

To set a secret:

sectool vault get <secret name> <secret value>

Module structure

• terraform/modules/apps/ — application modules (Nextcloud, etc.)
• terraform/modules/db/ — database modules (MariaDB with backups)
• terraform/modules/utils/ — utilities (exporters, cert-checker, prometheus, trivy, etc.)

Scripts (scripts/)

One-off utility scripts — not library code:

• install-opnsense.sh — boots OPNsense on a VM via virt-install (one-time router setup)
• chronograf.sh — kubectl port-forward wrapper for Chronograf pod
• proxy-pt.sh — kubectl port-forward wrapper for m3uproxy pod
• steamos — launches SteamOS gaming session with sunshine
• cpu_power_monitor.py — RAPL power monitoring (requires root)

Environment Setup

# Ansible + dev tools
pip install -r requirements/ansible.txt -r requirements/dev.txt

# Terraform/OpenTofu deps
pip install -r requirements/opentofu.txt

Contabo CLI

sectool exec cntb get instances --oauth2-clientid="$CONTABO_CLIENT_ID" ...

Windows hosts

• Use ConfigureRemotingForAnsible.ps1 in scripts/ to enable WinRM on Windows targets.
• On MSYS2: install packages listed in Readme.MD (go, python, cryptography, paramiko, rpds-py, etc.).
• Python venv: python -m venv .venv --system-site-packages

Style Conventions

• YAML: 120 char line length (warning threshold)
• Ansible roles follow galaxy conventions: defaults/, tasks/, meta/, files/, templates/
• tasks/main.yml is the entrypoint for every role
• Host vars: ansible/host_vars/<hostname>.yml

Troubleshooting and planning

• When troubleshooting and planning use deepwiki whenever possible to get documentation or information, deepwiki provides information about projects hosted on github to agents.