Skip to content

Web UI

Secretary ships with a built-in web interface built with Vue 3 + TypeScript. It is served at the container's base path (default: /).

Enabling the UI

The UI is always served. To require login, set admin credentials:

environment:
  SECRETARY_WEBSERVER__ADMIN_USERNAME: "admin"
  SECRETARY_WEBSERVER__ADMIN_PASSWORD: "your-password"

Without credentials configured, the UI is accessible without login (not recommended for public deployments).

Login

Navigate to http://<host>:7777/. If credentials are configured, you are redirected to a login page. After successful authentication, an HttpOnly JWT session cookie (secretary_session) is set.

Session lifetime is controlled by SECRETARY_WEBSERVER__SESSION_MAX_AGE (default: 7 days).

Rules editor

The rules editor is the main view of the UI. It shows all rule files in the rules.d directory as a tree on the left side.

Features:

  • Syntax-highlighted YAML editor with Monaco Editor
  • Schema-driven autocomplete — rule keywords, action types, and condition operators are suggested as you type
  • Inline validation — YAML and DSL errors are shown before saving
  • _vars.yml preview — renders the Jinja2 variables template and shows the resulting YAML
  • Create new rule files (in any sub-directory)
  • Delete rule files

Click Save to validate and write the file. The rules engine reloads automatically.

Dry-run runner

From the editor, select a rule and click Run (dry-run). Enter a Paperless document ID to test the rule against.

The result shows:

  • Whether the rule was skipped (trigger mismatch, filter mismatch, conditions not met)
  • Which actions were executed
  • What changes would have been applied
  • Any errors encountered

No changes are written to Paperless-ngx in dry-run mode.

Execution history

The History view lists past executions stored in the SQLite database. Each record shows:

  • Rule ID and document ID
  • Whether it was a dry-run
  • Execution result (skipped, executed, stopped, error)
  • Timestamp

Click a record to expand the full execution trace with per-action detail.

Records are automatically purged based on the retention settings:

  • Dry-run records: SECRETARY_DB__DRY_RUN_RETENTION_HOURS (default: 24 h)
  • Real executions: SECRETARY_DB__EXECUTION_RETENTION_HOURS (default: 14 days)

Live log

The Log view connects to the WebSocket endpoint and streams execution events in real time. New traces appear as documents are processed by incoming webhooks.

Hosting behind a sub-path

If you expose Secretary at a sub-path (e.g. /secretary/), set:

environment:
  SECRETARY_WEBSERVER__BASE_PATH: "/secretary/"

The frontend is automatically configured to use the correct base path.