Skip to content

Quick Start

Prerequisites

  • Docker and Docker Compose

That's it. Secretary is distributed as a single Docker image that bundles the backend, frontend, and reverse proxy.

1. Create a rules directory

mkdir rules.d

You can leave it empty for now and add rules later via the Web UI.

2. Create docker-compose.yml

---
services:
  secretary:
    image: ghcr.io/tb1337/paperless-secretary:latest
    restart: unless-stopped
    ports:
      - "7777:7777"
    volumes:
      - ./rules.d:/secretary/rules.d
      - ./secretary.db:/secretary/secretary.db
    environment:
      SECRETARY_SECRET_KEY: "<random 32+ char string>"
      SECRETARY_API_TOKEN: "<token for incoming webhook requests>"
      SECRETARY_PAPERLESS__URL: "https://paperless.example.com"
      SECRETARY_PAPERLESS__TOKEN: "<your paperless-ngx API token>"
      SECRETARY_WEBSERVER__ADMIN_USERNAME: "admin"
      SECRETARY_WEBSERVER__ADMIN_PASSWORD: "<your chosen password>"

Generating a secret key

openssl rand -hex 32

3. Start the service

docker compose up -d

The Web UI is available at http://localhost:7777/.

4. Configure the Paperless-ngx webhook

In Paperless-ngx, go to Settings → Workflows (or the admin panel, depending on your version) and add a webhook trigger pointing to:

http://<secretary-host>:7777/api/webhook/paperless

Add an Authorization header:

Bearer <your SECRETARY_API_TOKEN>

Enable both document_added and document_updated events.

5. Write your first rule

Create a file rules.d/my-first-rule.yml:

---
- id: inbox_to_review
  description: Tag every new document with "To Review".
  triggers:
    - created
  conditions:
    - not:
        - field: tags
          contains: "To Review"
  actions:
    - add_tag: "To Review"
    - save

Secretary hot-reloads the rules directory — your rule is active immediately.

Next steps