---
argument_specs:
  main:
    short_description: Deploy BookStack (LSIO image + MariaDB) via Docker Compose.
    description:
      - Renders a Compose stack for the linuxserver.io BookStack image
        with a sibling MariaDB container behind Traefik, then bootstraps
        the initial admin user via C(php artisan bookstack:create-admin)
        and optionally enables OIDC SSO (Entra ID by default).
      - "Persists the Laravel C(APP_KEY) on the host so the same key is
        re-used across deploys (a fresh key would orphan all encrypted
        database values: 2FA secrets, API tokens, OIDC client_secret)."
      - Ships an optional systemd timer that backs up the database dump,
        uploads tarball and APP_KEY daily with configurable retention.
    options:
      docker_compose_base_dir:
        type: path
        default: /etc/docker/compose
      docker_volume_base_dir:
        type: path
        default: /srv/data
      bookstack_service_name:
        type: str
        default: bookstack
      bookstack_docker_compose_dir:
        type: path
      bookstack_docker_volume_dir:
        type: path
      bookstack_appdata_dir:
        type: path
      bookstack_db_data_dir:
        type: path
      bookstack_backup_dir:
        type: path

      bookstack_domain:
        type: str
        default: wiki.local.test
        description: Hostname used in the Traefik Host rule.
      bookstack_base_url:
        type: str
        description: Defaults to C("https://{{ bookstack_domain }}").

      bookstack_image:
        type: str
        default: "lscr.io/linuxserver/bookstack:version-v26.03.3"
      bookstack_db_image:
        type: str
        default: "lscr.io/linuxserver/mariadb:11.4.9"

      bookstack_traefik_network:
        type: str
        default: proxy
      bookstack_traefik_certresolver:
        type: str
        default: le

      bookstack_tz:
        type: str
        default: Europe/Zurich
      bookstack_puid:
        type: str
        default: "1000"
      bookstack_pgid:
        type: str
        default: "1000"

      bookstack_db_name:
        type: str
        default: bookstack
      bookstack_db_user:
        type: str
        default: bookstack
      bookstack_db_root_password:
        type: str
        required: true
        description: MariaDB C(root) password. Override per-inventory.
      bookstack_db_password:
        type: str
        required: true
        description: MariaDB C(bookstack_db_user) password. Override per-inventory.

      bookstack_admin_password:
        type: str
        required: true
        description:
          - Password for the local admin user that the role creates via
            C(bookstack:create-admin). Lives alongside any OIDC users.

      bookstack_app_key:
        type: str
        default: ''
        description:
          - When empty the role generates a persistent C(APP_KEY) on first
            run and stores it under C({{ bookstack_docker_volume_dir }}/.app_key).
            Override only when restoring an existing instance — a mismatching
            key orphans all encrypted database values.

      bookstack_admin_name:
        type: str
        default: Admin
      bookstack_admin_email:
        type: str
        default: admin@local.test
      bookstack_artisan_path:
        type: path
        default: /app/www/artisan
        description:
          - Path to BookStack's C(artisan) script inside the container. The
            LSIO image's C(WORKDIR) is not the app directory, so this must
            be absolute.

      bookstack_mail_driver:
        type: str
        choices: [smtp, log, sendmail, mailgun, ses, postmark]
        default: smtp
      bookstack_mail_host:
        type: str
        default: smtp.local.test
      bookstack_mail_port:
        type: int
        default: 587
      bookstack_mail_encryption:
        type: str
        choices: [tls, ssl, '']
        default: tls
      bookstack_mail_from:
        type: str
        default: bookstack@local.test
      bookstack_mail_from_name:
        type: str
        default: BookStack
      bookstack_mail_username:
        type: str
        default: ''
      bookstack_mail_password:
        type: str
        default: ''

      bookstack_oidc_enabled:
        type: bool
        default: false
      bookstack_oidc_name:
        type: str
        default: SSO
        description: Display name of the SSO button on the login page.
      bookstack_entra_tenant_id:
        type: str
        default: ''
        description: Entra tenant UUID. Required when C(bookstack_oidc_enabled=true).
      bookstack_oidc_issuer:
        type: str
        description:
          - OIDC issuer URL. Defaults to the Entra v2 issuer template
            built from C(bookstack_entra_tenant_id). Override for
            Keycloak or any other provider.
      bookstack_oidc_client_id:
        type: str
        default: ''
        description: Required when C(bookstack_oidc_enabled=true).
      bookstack_oidc_client_secret:
        type: str
        default: ''
        description: Required when C(bookstack_oidc_enabled=true).
      bookstack_oidc_auto_initiate:
        type: bool
        default: false
        description:
          - When true users are redirected straight to the IdP and the
            local login is reachable only via C(?email_login=1).
      bookstack_oidc_user_to_groups:
        type: bool
        default: false
        description:
          - When true BookStack syncs roles from the IdP groups claim
            on every login. Requires BookStack roles whose
            C(External Auth ID) matches the IdP group's Object ID.
      bookstack_oidc_groups_claim:
        type: str
        default: groups
      bookstack_oidc_additional_scopes:
        type: str
        default: openid profile email

      bookstack_backup_enabled:
        type: bool
        default: true
      bookstack_backup_retention_days:
        type: int
        default: 14
      bookstack_backup_schedule:
        type: str
        default: "*-*-* 03:00:00"
        description: systemd C(OnCalendar) expression for the backup timer.