Develop

App reference

All fields of iac.json, the variables and helper roles of iac-core, tests, CI and common mistakes.

How an installation runs

Every way – container, image build, first boot of a VM, update, adoption – ends up at the same playbook inside the guest:

Proxmox host                    Guest (LXC, VM or image build)
────────────                    ───────────────────────────────────────────────────────
ct.sh ──── pct exec ──────────▶ bin/iac-install  →  ansible-playbook site.yml
vm.sh ──── ready image ───────▶   (ran in the chroot during the image build, again on first boot)
                                update      → Debian upgrade → bin/iac-install (iac_mode=update)
                                adopt.sh    → tasks/adopt_check.yml → backup
                                              → bin/iac-install (iac_mode=adopt)

site.yml:
  iac_facts      iac.json, instance, settings, secrets, modules
  iac_baseline   SSH, base packages, base firewall rules, update
  iac_modules    PostgreSQL, Valkey, …
  YOUR APP       tasks/main.yml        ← this is what you write
  iac_finish     handlers (restarts) → firewall from "ports" → start "services"
                 → check "health" → /etc/iac/instance.json

ct.sh, vm.sh and adopt.sh only live in iac-core (entry/). The website serves them for every app with its name. adopt.sh exists as soon as the app has tasks/adopt_check.yml.

iac.json

The complete schema: iac-core/schema/iac.schema.json.

Variables

iac-core sets these variables, your tasks may read them:

All of them with explanations: header of iac-core/ansible/site.yml.

Versions

Debian packages: with "upstream": {"type": "debian", "repo": "<package>"} iac-core reads the version itself. The app does not have to do anything.

Everything else (GitHub release, own download page): the role iac_version decides what is installed. You only tell it how to find out the installed version:

- name: Version to install
  ansible.builtin.include_role:
    name: iac_version
  vars:
    iac_version_command: /usr/local/bin/myapp --version
    iac_version_regex: 'v?([0-9.]+)'          # optional: first group = version

- name: "Install myapp {{ iac_version_target }}"
  when: iac_version_target != iac_version_installed
  block:
    - name: Download (checksum from the release)
      ansible.builtin.get_url:
        url: "https://github.com/vendor/myapp/releases/download/v{{ iac_version_target }}/myapp.tar.gz"
        dest: /tmp/myapp.tar.gz
        checksum: "sha256:https://github.com/vendor/myapp/releases/download/v{{ iac_version_target }}/SHA256SUMS"
        mode: "0644"
    # … unpack, install, notify: Restart myapp

Two things are mandatory:

• Checksum: checksum: with the release’s checksum file. No download without a checksum. If a project publishes no checksums, settle that before building the app.
• Only install on a new version: when: iac_version_target != iac_version_installed, file to /tmp and delete it afterwards. Without checksum, get_url does not download an existing file again – a fixed target like /var/cache/myapp.tar.gz would unpack the old archive on every update.

iac_version_installed is empty as long as nothing is installed. The role sets the version for instance.json itself. Examples: iac-traefik (binary, update with rollback), iac-netbox (release per directory), iac-ai-workstation.

Helper roles

Enable and start a service, also in the image build (there only enable):

- ansible.builtin.include_role:
    name: iac_service
  vars:
    iac_service: myapp-worker

You do not need this for the services in services – iac-core starts those itself.

Database: postgresql in modules, then:

- name: Database
  ansible.builtin.include_role:
    name: postgresql
    tasks_from: database
  vars:
    postgresql_db: myapp
    postgresql_user: myapp
    postgresql_password: "{{ iac_settings.myapp_db_password }}"
  when: not iac_build

With MariaDB instead of PostgreSQL: module mariadb, tasks_from: database with mariadb_db, mariadb_user and mariadb_password.

Files in the guest

• What your tasks place with copy/template belongs to iac and is reconciled on every run. Such files start with # managed by iac – do not edit.
• Changes by users go into files iac does not touch – plan a local file for that (iac-netbox: /etc/netbox/configuration.local.py).
• You do not need a firewall file – it is built from ports.
• Secrets never go into the repository: secrets in iac.json, in the template {{ iac_settings.name }}, tasks that use them get no_log: true.

First login

If the app has a login, it must be usable right after the installation:

• Password as a secret in iac.json, e.g. {"name": "myapp_admin_password", "length": 24}.
• The tasks create the first user with it, only as long as there is no admin yet – iac never touches a changed password or your own admins. no_log: true, when: not iac_build.
• access names the user and where to find the password; the app page (“Then:”) and ct.sh show it:

"access": "Web: http://{ip}:8000/ – login: admin, password in the guest: grep myapp_admin_password /etc/iac/settings.env"

A setup wizard in the browser is not enough: whoever opens it first on the network decides the admin, and often the service only listens on its ports after it – then the port check, smoke test and boot test fail. Create a start configuration instead (force: false, so later changes stay) that skips the wizard. Example: iac-netbox (netbox_admin_password).

Smoke test

iac-core already checks instance.json, the services, health and the ports in the firewall. tests/smoke.sh only contains what is specific to your app:

check "API answers"             'curl -fsS http://127.0.0.1:9090/api/health | jq -e .ok'
check "runs as its own user"    'ps -o user= -C myapp | grep -qx myapp'

tests/smoke.sh is not a script of its own: iac-smoke reads it with source. So no shebang, no set -e, no exit – only check "description" 'command' (header as in the template, # shellcheck shell=bash).

check never aborts: all checks run, failed ones show the command and its output. The same test runs in the boot test of every image and by hand in the guest (bash /var/lib/iac/src/core/bin/iac-smoke).

Adoption

Example: iac-traefik (adopts its own configuration as traefik.local.yaml). If it cannot be done automatically, a guide belongs in docs/MIGRATION.md – the website links it.

Testing

Lint – typos, wrong fields, Ansible syntax, leftovers of old apps:

iac-core/tools/lint.sh iac-myapp

Without Proxmox – Docker container with systemd:

iac-core/tools/dev-container.sh iac-myapp                     # install + smoke test
iac-core/tools/dev-container.sh iac-myapp                     # again = like update
IAC_APP_VERSION=1.2.3 iac-core/tools/dev-container.sh iac-myapp   # specific version
docker exec -e IAC_MODE=update iac-dev-myapp \
  bash /var/lib/iac/src/core/bin/iac-install                  # update path of the app

The second run should show changed=1 (only instance.json) – then the app is idempotent. The container is not a real LXC (privileged, no cloud-init), but it is enough for the app logic.

On Proxmox – a branch, before it goes to main:

IAC_APP_REF=my-branch bash -c "$(curl -fsSL https://iac.heyer.systems/myapp/ct.sh)"

In the guest, IAC_VERBOSE=1 bash /var/lib/iac/src/core/bin/iac-install shows all task results.

CI

The workflows are the same in all apps and consist of a single call. The steps live in iac-core (ci/lint, ci/image):

Only an image that passes the boot test is published. Hostname and size of the image come from iac.json. For more (additional bootstrap-vz settings) there is the optional image/manifest.yml.

Own modules

What several apps can use (database, cache, monitoring …) belongs in iac-core as a module – then every app can use it:

1. Role iac-core/ansible/roles/<module>/ with module_state: present installs and starts, absent removes packages and files again – data stays.
2. Firewall rules of the module in /etc/nftables.d/40-<module>.nft.
3. Entry in iac-core/modules.json: title, description (English), supports (lxc, vm), optionally default and icon (slug at selfh.st/icons, default: the module’s name).

A module for one app only lives in roles/<module>/ in the app repository. Structure and examples: iac-core/ansible/roles/README.md. Notes for the module’s page on this website go into iac-website/module-notes/<module>.md.

Common mistakes

Ansible knowledge

Available is ansible-core from Debian, so the modules of ansible.builtin – no other collections: documentation of the built-in modules.