computer-playbook/roles/web-app-kix/README.md

KIX

Description

KIX Start is an open-source IT service management and helpdesk platform forked from OTRS. It provides ticket management, configuration management, knowledge base, and reporting for IT service teams.

Overview

This role deploys KIX as an Infinito.Nexus web app behind the project's standard sys-stk-front-proxy and web-app-keycloak's SSO-proxy sidecar chain. The upstream kix-on-premise proxy, backend, and frontend containers ship from docker-registry.kixdesk.com/public/. The backend initialises its schema (scripts/database/kix-schema.xml) against the central svc-db-postgres cluster, or against the embedded postgres sidecar when no central provider is in the inventory, with pg_trgm pre-activated via services.postgres.extensions; the cache is the role-local passwordless redis sidecar (the frontend ignores REDIS_CACHE_PASSWORD). Initial admin credentials are seeded via INITIAL_ADMIN_PW on first start (see meta/secrets.yml).

Cosmos

The diagram places KIX in the Infinito.Nexus cosmos: the components it deploys (capabilities), the central services it consumes (dependencies), and its outward reach (federation and bridged external networks).

flowchart LR
    subgraph deps [Dependencies]
        dep_svc_bkp_volume_2_local["svc-bkp-volume-2-local 💻"]
        dep_svc_db_openldap["svc-db-openldap 🐳🐝"]
        dep_svc_db_postgres["svc-db-postgres 🐳🐝"]
        dep_svc_net_tor["svc-net-tor 🐳🐝"]
        dep_web_app_dashboard["web-app-dashboard 🐳🐝"]
        dep_web_app_keycloak["web-app-keycloak 🐳🐝"]
        dep_web_app_matomo["web-app-matomo 🐳🐝"]
        dep_web_app_prometheus["web-app-prometheus 🐳🐝"]
        dep_web_app_stalwart["web-app-stalwart 🐳🐝"]
        dep_web_svc_css["web-svc-css 💻"]
        dep_web_svc_logout["web-svc-logout 🐳🐝"]
    end
    subgraph role [web-app-kix 🐳🐝]
        svc_logout["logout"]
        svc_dashboard["dashboard"]
        svc_matomo["matomo"]
        svc_email["email"]
        svc_ldap["ldap"]
        svc_sso["sso"]
        svc_css["css"]
        svc_prometheus["prometheus"]
        svc_postgres["postgres"]
        svc_redis["redis"]
        svc_kix["kix"]
        svc_proxy["proxy"]
        svc_backend["backend"]
        svc_frontend["frontend"]
        svc_tor["tor"]
        svc_container_backup["container_backup"]
    end
    dep_svc_bkp_volume_2_local -. "0..1" .-> svc_container_backup
    dep_svc_db_openldap -. "0..1" .-> svc_ldap
    dep_svc_db_postgres -. "0..1" .-> svc_postgres
    dep_svc_net_tor -. "0..1" .-> svc_tor
    dep_web_app_dashboard -. "0..1" .-> svc_dashboard
    dep_web_app_keycloak -. "0..1" .-> svc_sso
    dep_web_app_matomo -. "0..1" .-> svc_matomo
    dep_web_app_prometheus -. "0..1" .-> svc_prometheus
    dep_web_app_stalwart -. "0..1" .-> svc_email
    dep_web_svc_css -. "0..1" .-> svc_css
    dep_web_svc_logout -. "0..1" .-> svc_logout

Solid 1:1 edges are fixed relationships; dashed 0..1 edges are conditional (enabled only in matching deployments); red 0..0 edges are turned off in this role. Node markers show the role's deploy modes (💻 host, 🐳 compose, 🐝 swarm); ❌ marks a service that is explicitly turned off, and ⚙️ an Ansible role dependency declared in meta/main.yml.

Features

• TLS and HSTS: KIX is reachable at kix.<DOMAIN_PRIMARY> via sys-stk-front-proxy with HSTS enabled.
• OAuth2 proxy gate: Every request is gated by web-app-keycloak's SSO-proxy sidecar (services.sso.enabled: true). The Keycloak realm-level OTP and WebAuthn flow enforces 2FA before the OAuth2 proxy admits a session; KIX itself carries no 2FA logic.
• Per-app RBAC: Members of /roles/web-app-kix/administrator or /roles/web-app-kix/user are admitted to KIX; other users are blocked at the OAuth2 proxy. The user role is declared via meta/rbac.yml so non-admin agents can be granted helpdesk access without bumping them to global administrator.
• LDAP user directory: KIX' Auth::LDAP and Auth::Sync::LDAP modules are wired against svc-db-openldap, with one backend per role group. On first login KIX pulls the user's profile (display name, email, group membership) from LDAP, so no manual KIX-side user pre-creation is required.
• Custom kix-proxy routing: The role bind-mounts a complete default.conf into the upstream kix-proxy container that exposes the agent portal on port 80, routes through the frontend Node server, and forwards the OAuth2-proxy X-Forwarded-User header as a Remote-User upstream header.
• Outbound mail: KIX notification mail flows through the project's sys-svc-mail-smtp relay.
• Dashboard card: web-app-dashboard surfaces a KIX tile pointing at the canonical URL.
• Universal logout: The project logout endpoint terminates the KIX session alongside every other Infinito.Nexus app.

Quick Setup

Development

Clone, set up the workstation, and deploy KIX onto the local stack:

git clone https://github.com/infinito-nexus/core.git
cd core
make onboard
make compose-deploy mode=reinstall apps=web-app-kix full_cycle=false

Production

Run the published image to provision the inventory and deploy KIX to a managed server (the mounted volume persists the inventory):

APP=web-app-kix
HOST=<your-server>
DOMAIN=<your-domain>
TLS_MODE=self_signed
SSH_PUBLIC_KEY="<your-ssh-public-key>"

docker run --rm -it \
  -v "$PWD/inventories:/etc/infinito.nexus/inventories" \
  -e APP="$APP" -e HOST="$HOST" -e DOMAIN="$DOMAIN" -e TLS_MODE="$TLS_MODE" -e SSH_PUBLIC_KEY="$SSH_PUBLIC_KEY" \
  ghcr.io/infinito-nexus/core/debian bash -c '
    INVENTORY=/etc/infinito.nexus/inventories/production
    infinito administration inventory provision "$INVENTORY" \
      --inventory-file "$INVENTORY/devices.yml" \
      --host "$HOST" \
      --include "$APP" \
      --vars "{\"TLS_MODE\": \"$TLS_MODE\", \"DOMAIN_PRIMARY\": \"$DOMAIN\", \"users\": {\"administrator\": {\"authorized_keys\": [\"$SSH_PUBLIC_KEY\"]}}}" &&
    infinito administration deploy dedicated "$INVENTORY/devices.yml" \
      --password-file "$INVENTORY/.password" \
      --diff -vv'

Further Resources

• KIX Start website
• KIX documentation

Persona contract opt-outs

This role declares PERSONA_BIBER_BLOCKED in templates/playwright.env.j2. KIX sits behind an oauth2-proxy whose sso.oauth2.allowed_groups in meta/services.yml admits only roles/web-app-kix/administrator and roles/web-app-kix/user; biber belongs to neither, so the proxy denies him before KIX renders anything. Past the proxy KIX is a two-stage login: the SPA still presents its own agent form at /auth that binds against LDAP, and the shared persona helper has no second stage after the Keycloak round-trip.

The runnable journey lives in files/playwright/test-login-biber.js, which first grants biber the KIX user group over the Keycloak Admin API and then drives runKixLoginLogoutFlow through both stages to the universal logout. The path back to the generic persona is a KIX build that accepts the proxy's trusted headers instead of demanding its own login.

Credits

Implemented by Kevin Veen-Birkenbach. Part of the Infinito.Nexus Project and maintained by Kevin Veen-Birkenbach. Licensed under the Infinito.Nexus Community License (Non-Commercial).