Getting Started

Everything in this repo assumes two credentials: a Proxmox API token (to discover hosts) and a Bitwarden Secrets Manager access token (to inject secrets at container start). Get those in place and the rest follows.

Clone and install tooling

git clone git@github.com:markkpamy/infrastructure-toolkit.git
cd infrastructure-toolkit

# Formatting + secret scanning on every commit
./utils/utils-linux/install-pre-commit.sh
./utils/utils-linux/setup-pre-commit-repo.sh

Configure credentials

cd ansible
cp .env.example .env

Fill in .env. The three that matter most:

Variable	What it is
PROXMOX_TOKEN_SECRET	Proxmox API token secret. Create under Datacenter → Permissions → API Tokens.
BWS_ACCESS_TOKEN	Bitwarden machine-account token used on the controller to wrap stack restarts.
BWS_HOST_ACCESS_TOKEN	A separate, read-only token distributed to hosts as /etc/bws/token.

Use two different BWS tokens

BWS_HOST_ACCESS_TOKEN lands on every LXC in the fleet. Reusing the broader BWS_ACCESS_TOKEN there would put a full-access credential on every container. Scope the host token to only the projects the hosts actually read.

.env is gitignored, and gitleaks runs as a pre-commit hook — but the safest habit is never pasting a real secret into a tracked file in the first place.

Load credentials and collections

# From ansible/
ansible-galaxy collection install -r collections/requirements.yml
export $(cat .env | grep -v '^#' | xargs)

Run something read-only first

Confirm the dynamic inventory can actually reach Proxmox before changing anything:

ansible-inventory -i inventory/proxmox.proxmox.yml --graph

You should see every VM and LXC, grouped by node and by Proxmox tag (hosts tagged docker show up as tag_docker). If that works, credentials and network path are good.

Then a real playbook in check mode:

ansible-playbook -i inventory/proxmox.proxmox.yml \
  playbooks/system-update.yml --limit arcane --check --diff

Everyday commands

# Whole fleet
ansible-playbook -i inventory/proxmox.proxmox.yml playbooks/<playbook>.yml

# One host, or a few
ansible-playbook -i inventory/proxmox.proxmox.yml playbooks/<playbook>.yml --limit arcane
ansible-playbook -i inventory/proxmox.proxmox.yml playbooks/<playbook>.yml --limit 'arcane,traefik'

# Restart every running Docker stack with BWS secrets injected
ansible-playbook -i inventory/proxmox.proxmox.yml playbooks/restart-docker-stacks.yml

Full playbook and role reference: Ansible.

Before you touch a live host

Read Host Access Notes first. It records which hosts accept which user, which are only reachable via pve-dell, and the rules for making changes safely — most notably that hosts track main, so changes flow commit → push → pull on the host, never by editing files in place.

Working on this documentation site

cd docs
npm install
npm run dev      # syncs content from the repo, then serves at localhost:4321
npm test         # unit tests for the sync + catalog scripts

See Editing these docs for how content gets here.