📦 Creating TrueNAS Apps with Ansible

📖 Purpose

This explains how to declare a TrueNAS application in the inventory and deploy it with the truenas role. It covers:

1. choosing between a catalog app and a custom (Compose) app
2. finding the correct values for a catalog app from its schema
3. storing secrets in the host Vault
4. planning, applying, upgrading, and removing the app

It uses two worked examples: a Postgres app and a Nexdeck app. The two have different values, and the guide explains why so you can configure any other catalog app.

For the role’s general design, see the TrueNAS Role Contributor Guide.

🧭 How App Deployment Works Here

Apps are not part of configure_truenas.yml. They have their own playbook, playbooks/truenas/deploy_truenas_apps.yml, which imports roles/truenas/tasks/apps.yml.

For each entry in truenas_apps, the workflow:

1. validates every declaration locally (apps_validate.yml) before it contacts the NAS
2. runs the read-only preflight and checks that an Apps storage pool exists (docker.config)
3. calls the truenas_api module in mode: app (library/truenas_api.py), which:
   • creates the app with app.create when it does not exist
   • compares your values with app.config <name> and calls app.update only when they differ
   • calls app.upgrade when catalog.version changes, but only if you set allow_upgrade: true
   • starts or stops the app to match runtime
   • waits for each middleware job, then waits for the app to reach RUNNING or STOPPED

truenas_apps_mode defaults to plan, so the playbook only reports what it would do. Nothing changes until you pass -e truenas_apps_mode=apply. Ansible check mode (--check) is always read-only.

App declarations go in inventory/truenas/host_vars/truenas-01/default.yml. Secrets go in inventory/truenas/host_vars/truenas-01/vault.yml.

🧱 Anatomy of an App Entry

Every entry in truenas_apps accepts only these top-level keys. Any other key fails validation.

catalog block

⚠️ app and train cannot change after the app is created. The role refuses to replace an app from a different catalog entry. Delete it and create it again instead.

🔍 Finding the Correct values for a Catalog App

This is the step that differs between apps. values is not a fixed role schema. It is the answer set for that app’s questions.yaml in the TrueNAS catalog. Postgres asks different questions than Nexdeck, so copying the Postgres block will not work.

Step 1: Get the app’s schema

Use either source. Both give the same schema for the same version.

Option A: GitHub (no NAS access needed). Open:

https://github.com/truenas/apps/tree/master/ix-dev/<train>/<app>/

• app.yaml has version (use this for catalog.version), app_version, train, host_mounts, and run_as_context.
• questions.yaml is the schema for values.

master holds the latest version. If you pin an older catalog.version, check that the schema has not changed since.

Option B: The NAS itself (SSH as an admin user; see the midclt cheat sheet):

# Confirm the app exists, and see its train and latest catalog version
midclt call app.available '["name","=","nexdeck"]("name","=","nexdeck".md)' '{"select":["name","train","latest_version","latest_app_version"]}'

# Full details, including the questions schema for each available version
midclt call catalog.get_app_details nexdeck '{"train":"community"}' | jq '.versions | keys'
midclt call catalog.get_app_details nexdeck '{"train":"community"}' | jq '.versions["1.0.42"].schema.questions'

Step 2: Translate questions.yaml into YAML values

Each question is a variable. The variable names become your values keys, and nesting follows schema.type: dict → attrs.

Step 3: Decide what to declare

Values are merged into the app’s current configuration. The role only compares and updates the keys you list:

• On create, TrueNAS fills in the schema default for every key you omit. You must still supply any required key whose default is empty or invalid.
• On later runs, keys you leave out are not managed. Changes made in the UI to those keys are not reverted.

Recommendation: declare every setting you care about (secrets, ports, storage, resources, timezone), and leave UI-only or rarely used keys such as labels and networks at their defaults.

Comparison rules to keep in mind

The module compares desired and current values strictly (app_config_matches):

• Types must match exactly. port_number: 30495 matches, but port_number: "30495" is reported as a change on every run.
• Lists are compared in order and by length. List host_ips in the same order every time.
• Mappings are compared one way. Extra keys that TrueNAS returns are ignored. Missing keys are not.

If a plan reports update on every run, compare your entry with midclt call app.config <name> and look for a type or ordering mismatch.

🐘 Example 1: Postgres

The schema for ix-dev/community/postgres has top-level questions postgres, run_as, network, storage, labels, and resources. Its network question is called tcp_port, and its data volume is storage.data.

truenas_apps:
  - name: postgres
    source: catalog
    state: present
    runtime: running
    catalog:
      app: postgres
      train: community
      version: "1.5.46"
    values:
      postgres:                       # app-specific block
        image_selector: v18_image
        user: postgres
        password: "{{ vault_truenas_postgres_password }}"
        database: postgres
        shm_size_mb: 512
      resources:
        limits:
          cpus: 2
          memory: 4096
      network:
        host_network: false
        tcp_port:                     # Postgres calls its port "tcp_port"
          bind_mode: published
          port_number: 5432
          host_ips:
            - "0.0.0.0"
      storage:
        data:
          type: ix_volume
          ix_volume_config:
            acl_enable: false
            dataset_name: data

🗂️ Example 2: Nexdeck

Nexdeck is a homelab dashboard in the community train. From ix-dev/community/nexdeck/app.yaml:

How Nexdeck differs from Postgres

Nexdeck values reference

Settings from questions.yaml for catalog version 1.0.42:

Step 1: Add the secret to Vault

Generate a key of at least 16 characters:

openssl rand -hex 32

Add it to the host Vault:

ansible-vault edit inventory/truenas/host_vars/truenas-01/vault.yml

vault_truenas_nexdeck_secret_key: "<paste the generated value>"

Step 2: Add the app to truenas_apps

Add a second, distinct entry next to Postgres in inventory/truenas/host_vars/truenas-01/default.yml. Each name can appear only once, so a copied postgres entry fails validation with “Each TrueNAS application name must appear exactly once.”

truenas_apps:
  - name: postgres
    # ... unchanged ...

  - name: nexdeck
    source: catalog
    state: present
    runtime: running
    catalog:
      app: nexdeck
      train: community
      version: "1.0.42"
    values:
      TZ: America/Chicago
      nexdeck:
        secret_key: "{{ vault_truenas_nexdeck_secret_key }}"
        public_url: https://nexdeck.refol.us
        docker_socket: false
      run_as:
        user: 568
        group: 568
      network:
        host_network: false
        web_port:
          bind_mode: published
          port_number: 30495
          host_ips:
            - "0.0.0.0"
      storage:
        data:
          type: ix_volume
          ix_volume_config:
            acl_enable: false
            dataset_name: config
      resources:
        limits:
          cpus: 2
          memory: 2048

Replace TZ, public_url, and the memory limit with your own values. Delete public_url if you have no reverse-proxy name yet.

Variant: store data on an existing dataset

Use this if you want Nexdeck’s data on a dataset you manage and snapshot, instead of an ix volume. The path must already exist; create it with truenas_datasets if needed.

      storage:
        data:
          type: host_path
          host_path_config:
            acl_enable: false
            path: /mnt/Data/configs/nexdeck

⚠️ Do not switch storage.data.type on an app that already has data. The new location starts empty.

Step 3: (Optional) Publish through the reverse proxy

If you set public_url, add the DNS and proxy entry for it. See Configuring an inventory host web service for a reverse proxy. The backend is http://192.168.2.250:30495.

🧩 Custom (Compose) Apps

Use source: custom when the app is not in any catalog train, or when the catalog app lacks options you need. Do not set catalog or values.

truenas_apps:
  - name: example-web
    source: custom
    runtime: running
    compose: |
      services:
        web:
          image: nginx:1.27
          restart: unless-stopped
          ports:
            - "8080:80"
          volumes:
            - /mnt/Data/configs/example-web:/usr/share/nginx/html:ro

Unlike catalog values, Compose is compared in both directions and replaced as a whole on update, so the YAML in the inventory is the complete definition. An app cannot be converted between catalog and custom.

▶️ Plan and Apply

1. Plan (read-only). Validates locally, then reports the actions for each app:

   ansible-playbook -i inventory/truenas/inventory.ini playbooks/truenas/deploy_truenas_apps.yml \
     --limit truenas-01 --check --diff -k --ask-vault-pass
   

   For a new app, expect actions: ['create'] and runtime_state: ABSENT. App results are redacted while truenas_no_log is true. Set it to false temporarily only if you need to debug, because it can print secrets.

2. Apply:

   ansible-playbook -i inventory/truenas/inventory.ini playbooks/truenas/deploy_truenas_apps.yml \
     --limit truenas-01 -e truenas_apps_mode=apply -k --ask-vault-pass
   

   The role waits up to truenas_apps_job_timeout (900 s) for the create job and up to truenas_apps_health_timeout (180 s) for RUNNING. A first install pulls images, so raise the timeouts if your link is slow:

   -e truenas_apps_job_timeout=1800 -e truenas_apps_health_timeout=600
   

3. Verify:

   midclt call app.query '["id","=","nexdeck"]("id","=","nexdeck".md)' '{"select":["id","state","version","human_version"]}'
   midclt call app.config nexdeck
   

   Then browse to http://192.168.2.250:30495.

4. Run the plan again. It should report no actions. If it reports update, see Comparison rules.

⬆️ Upgrading and 🗑️ Removing

Upgrade. Find the new catalog version with midclt call app.upgrade_summary nexdeck '{}' or from app.yaml on GitHub. Check questions.yaml for added or renamed keys, then:

    catalog:
      version: "1.0.43"        # new catalog version
    allow_upgrade: true

Plan, apply, then set allow_upgrade back to false. Downgrades and versions that app.upgrade_summary does not offer are refused.

Remove.

  - name: nexdeck
    source: catalog
    state: absent
    allow_delete: true

The app is deleted, but its images and ix volumes are kept. Remove the volume by hand once you no longer need its data. After the app is gone, you can delete the entry.

🛠️ Troubleshooting

✅ Checklist for Any New Catalog App

• Found the app’s train and catalog version (not app_version)
• Read questions.yaml for that version, and listed all required keys with empty defaults
• Used the app’s own key names (web_port vs tcp_port, TZ, app block name)
• Wrote ints and booleans unquoted
• Put private: true values in vault.yml as vault_truenas_<app>_<key>
• Chose a host port that does not conflict with other apps
• Gave the app a unique name in truenas_apps
• Ran the plan, reviewed actions, then applied
• Ran the plan again and confirmed it reports no changes