playbooks/trilium/roles/trilium/tasks/main.yaml

---
# TriliumNext Notes as a rootless Podman Quadlet unit.
#
# Everything here runs as {{ podman_user }} — the connection user. No become, no
# XDG_RUNTIME_DIR: the SSH connection gave us a real PAM session, so systemd's
# user manager is reachable through the standard environment.

# The image's data directory is one tree: document.db with its WAL sidecars,
# config.ini, session_secret.txt, and the three subdirectories below. It is
# created here as the copy target as much as for a fresh install.
- name: Ensure the Trilium data directory exists
  ansible.builtin.file:
    path: "{{ data_dir }}"
    state: directory
    owner: "{{ podman_user }}"
    group: "{{ podman_user }}"
    mode: '0755'

# Trilium creates these itself on first start, at 0700 — which is exactly how
# they are on monoco. Creating them here means a fresh host and a migrated one
# look the same, and that the destinations named in readme.md exist before the
# copy. log/ is where the app writes its daily log — which the play reads back
# later as evidence that the container is writing to the host — and backup/ is
# where its own zipped document.db backups land.
- name: Ensure the app-managed subdirectories exist
  ansible.builtin.file:
    path: "{{ item }}"
    state: directory
    owner: "{{ podman_user }}"
    group: "{{ podman_user }}"
    mode: '0700'
  loop:
    - "{{ log_dir }}"
    - "{{ tmp_dir }}"
    - "{{ backup_dir }}"

# Checked before the unit starts, because this is the one thing the play cannot
# tell after the fact: with no document.db the app serves a brand new, empty
# document, which is right for a fresh install and wrong for a migration whose
# copy has not run yet. Once the app has started it creates the file itself and
# the evidence is gone.
- name: Check whether a document has been copied in
  ansible.builtin.stat:
    path: "{{ data_dir }}/document.db"
  register: trilium_document_db

- name: Note that this will start with a fresh document
  ansible.builtin.debug:
    msg: >-
      {{ data_dir }}/document.db does not exist, so Trilium will create an empty
      document on first start. That is correct for a fresh install — and it is
      what happens if the copy from monoco has not run yet. See readme.md,
      "Migrating the data from monoco".
  when: not trilium_document_db.stat.exists

- name: Install the Trilium Quadlet unit
  ansible.builtin.template:
    src: trilium.container.j2
    dest: "{{ quadlet_dir }}/{{ container_name }}.container"
    owner: "{{ podman_user }}"
    group: "{{ podman_user }}"
    mode: '0644'
  notify:
    - Reload systemd user units
    - Restart Trilium

- name: Start Trilium
  block:
    - name: Start Trilium
      ansible.builtin.systemd_service:
        name: "{{ unit_name }}"
        scope: user
        state: started
        daemon_reload: true
  rescue:
    # systemd reports "control process exited with error code" and nothing
    # else, which is useless for the usual failures (an unattached network, an
    # unwritable data directory, a bad volume). Pull the real reason out.
    - name: Collect Trilium diagnostics
      ansible.builtin.command: "{{ item }}"
      loop:
        - "systemctl --user status {{ unit_name }} --no-pager"
        - "journalctl --user -u {{ unit_name }} --no-pager -n 40"
        - "podman logs --tail 40 {{ container_name }}"
      register: trilium_diag
      changed_when: false
      failed_when: false

    - name: Show Trilium diagnostics
      ansible.builtin.debug:
        msg: "{{ trilium_diag.results | map(attribute='stdout') | list }}"

    - name: Fail
      ansible.builtin.fail:
        msg: "Trilium did not start — see the diagnostics above."

# Quadlet honours [Install] WantedBy= when it generates the unit, so
# `systemctl --user enable` is neither needed nor possible on a generated unit.
- name: Verify Trilium is running
  ansible.builtin.command: "systemctl --user is-active {{ unit_name }}"
  register: trilium_active
  changed_when: false
  failed_when: trilium_active.stdout != 'active'

# `is-active` says the container is running; it does not say the app can serve.
# `Restart=always` means even a crash-looping container is reported active.
#
# Unlike audiobookshelf, this image ships its own HEALTHCHECK
# (`exec gosu node node /usr/src/app/docker_healthcheck.cjs`, which the
# Docker-era container reported healthy with), so there is no HealthCmd= in the
# unit to run here — `podman healthcheck run` executes the image's own probe and
# this depends on no path the play has to know about.
- name: Wait for Trilium to pass its own health check
  ansible.builtin.command: "podman healthcheck run {{ container_name }}"
  register: trilium_health
  until: trilium_health.rc == 0
  retries: 24
  delay: 5
  changed_when: false

# The check that catches a missing or mistyped Volume= line, which is the one
# failure here that is silent: the app would run perfectly well with document.db
# in the container's writable layer — or in an anonymous volume, if the image
# declares one — and lose it on the next recreate.
#
# It has to be a mount check and not a file check. Audiobookshelf can assert that
# its database appeared on the host, because the app creates it; here the
# migration puts document.db on the host *before* the app ever runs, so its
# presence proves nothing about whether the container can see it.
#
# Both halves matter: the destination alone would still be satisfied by an
# anonymous volume mounted where the bind mount should be, which is exactly the
# silent case. `Source` is the path Quadlet passed to podman, verbatim.
- name: Read the running container's configuration back
  ansible.builtin.command: "podman inspect {{ container_name }}"
  register: trilium_inspect
  changed_when: false

- name: Fail if the data directory is not bind-mounted into the container
  ansible.builtin.assert:
    that:
      - >-
        (trilium_inspect.stdout | from_json)[0].Mounts | default([])
        | selectattr('Source', 'defined')
        | selectattr('Source', 'eq', data_dir)
        | selectattr('Destination', 'eq', container_data_dir)
        | list | length == 1
    fail_msg: >-
      {{ data_dir }} is not mounted at {{ container_data_dir }} in the running
      container. Whatever the app is writing is inside the container's writable
      layer, or in an anonymous volume, and will be lost when it is recreated —
      check the Volume= line in the generated unit
      ({{ quadlet_dir }}/{{ container_name }}.container).

# Evidence rather than a gate: with keep-id:uid=1000 mapped onto
# {{ podman_user }}, what the app writes lands in {{ data_dir }} owned by
# {{ podman_user }} — and the app writes a daily log the moment it starts. A log
# touched in the last few minutes is that, visible from the host. It is reported
# rather than asserted because a slow start can legitimately leave nothing here
# yet; the mount assertion above is the hard check.
- name: Look for a log written since the unit started
  ansible.builtin.find:
    paths: "{{ log_dir }}"
    patterns: 'trilium-*.log'
    age: -5m
    file_type: file
  register: trilium_recent_logs

- name: Report whether the app is writing to the host data directory
  ansible.builtin.debug:
    msg: >-
      {{ trilium_recent_logs.matched }} log file(s) in {{ log_dir }} touched in
      the last 5 minutes. With container uid 1000 mapped onto {{ podman_user }},
      a log appearing there is the app writing into {{ data_dir }} on the host;
      nothing yet, on a unit that is serving, means checking the Volume= and
      UserNS= lines in the generated unit.

- name: Check the document the container is reading
  ansible.builtin.stat:
    path: "{{ data_dir }}/document.db"
  register: trilium_document_db_after

# A migrated document.db is a few megabytes; the empty one the app creates on a
# fresh install is kilobytes. Worth printing, because it is the difference
# between "the notes came across" and "the copy never ran".
- name: Report the document on the host
  ansible.builtin.debug:
    msg: >-
      {{ data_dir }}/document.db is
      {{ trilium_document_db_after.stat.pw_name | default('?') }}:{{ trilium_document_db_after.stat.gr_name | default('?') }},
      {{ trilium_document_db_after.stat.size | default(0) }} bytes
  when: trilium_document_db_after.stat.exists