What’s in the box:

Step 1: Download

git clone https://github.com/timothystewart6/paperless-stack.git
cd paperless-stack

The stack uses one .env file per service (for example ./paperless/.env and ./postgres/.env).

Step 2: Lock down the ports (important)

Out of the box, the stack publishes its web ports to your whole home network, and Paperless-GPT and Dozzle have no login at all. Before you start anything, open compose.yaml and add 127.0.0.1: to those two:

  paperless-gpt:
    ports:
      - "127.0.0.1:3002:8080"

  dozzle:
    ports:
      - "127.0.0.1:8080:8080"

It’s worth doing the same for Open WebUI (3001) and Paperless-AI (3000) too. Then use tailscale serve (Section 7) when you want to reach them from other devices.

Step 3: Set the basic secrets

• ./postgres/.env: set a strong POSTGRES_PASSWORD.
• ./paperless/.env: set PAPERLESS_DBPASS to the same password, and set a long random PAPERLESS_SECRET_KEY.
• ./paperless/.env: if you’ll open Paperless through Tailscale, add PAPERLESS_URL=https://your-mac-name.your-tailnet.ts.net. Without it, logins from that address can fail with a CSRF error.
• ./paperless/.env (optional): add PAPERLESS_OCR_LANGUAGE=eng (or eng+hin, and so on) to match your documents.

Quick way to make a random secret: openssl rand -hex 32

Step 4: Use Ollama on the Mac’s GPU (what I do)

The compose.yaml you download from the paperless-stack repo includes its own Ollama container. On a Mac, that container can only use the CPU. So I comment it out and point everything at Ollama.app running on the Mac’s GPU (see Section 1 to install it).

4a. Comment out the ollama service in the downloaded compose.yaml:

  # ollama now runs NATIVELY on the Mac (Ollama.app, Metal GPU).
  # Containers reach it at http://host.docker.internal:11434
  # To go back to CPU-only Ollama in Docker, uncomment this service and
  # set the URLs in open-webui/.env, paperless-ai/.env and paperless-gpt/.env
  # back to http://ollama:11434
  # ollama:
  #   image: ollama/ollama:latest
  #   container_name: ollama
  #   env_file:
  #     - ./ollama/.env
  #   environment:
  #     OLLAMA_NUM_PARALLEL: "1"
  #   volumes:
  #     - ./ollama/data/:/root/.ollama
  #     - ./ollama/models:/ollama-models
  #   restart: unless-stopped

4b. Remove - ollama from depends_on: in the open-webui, paperless-ai, and paperless-gpt services. If you skip this, Docker Compose refuses to start because those services depend on one that no longer exists. For example:

  paperless-ai:
    depends_on:
      - paperless        # "- ollama" removed

4c. Point the three AI services at the Mac’s Ollama. Change http://ollama:11434 to http://host.docker.internal:11434:

# ./open-webui/.env
OLLAMA_BASE_URL=http://host.docker.internal:11434

# ./paperless-ai/.env
OLLAMA_API_URL=http://host.docker.internal:11434

# ./paperless-gpt/.env   (this file uses "KEY: value" style)
OLLAMA_HOST: "http://host.docker.internal:11434"

4d. Quick test. Before you start the stack, check that a container can reach the Mac’s Ollama:

docker run --rm curlimages/curl -s http://host.docker.internal:11434/api/version

You should see something like {"version":"0.40.14"}.

Already ran the stack with the Docker Ollama? Two apps remember the old address and ignore the .env change:

• Paperless-AI saves its settings in ./paperless-ai/data/.env. Change OLLAMA_API_URL there too, or update it on its Settings page.
• Open WebUI saves the connection in its database. Change it in Admin Panel → Settings → Connections to http://host.docker.internal:11434.

Then run docker compose up -d --force-recreate --remove-orphans. The --remove-orphans flag removes the old Ollama container. Your previously downloaded models stay in ./ollama/models until you delete that folder.

Step 5: Start it and create your account

docker compose up -d

Open http://localhost:8000 and create your admin account. If you don’t see a sign-up screen, create one from the terminal:

docker compose exec paperless createsuperuser

At this point Paperless works fully without any AI. Drop a PDF into ./paperless/consume/ and watch it show up, searchable, a minute later. The AI layer is optional.

Step 6: Download the AI models

Since Ollama runs on the Mac, pull the models from the Mac’s Terminal:

ollama pull llama3.2:3b     # small text model: titles, tags, summaries
ollama pull minicpm-v:8b    # vision model that "reads" scanned pages for OCR
ollama list                 # check both are there

The names must match what’s set in ./paperless-ai/.env (OLLAMA_MODEL) and ./paperless-gpt/.env (LLM_MODEL, VISION_LLM_MODEL).

Then open Open WebUI at http://localhost:3001 and create your account right away, because the first account created becomes the admin. It shows the same models, because it talks to the same Ollama on the Mac. You can also pull new models from there.

With the GPU you have room for bigger models, for example llama3.1:8b for text or qwen2.5vl:7b for OCR. Just update the model names in the .env files to match.

Step 7: Connect the AI tools to Paperless

The AI tools need an API token, and you can only create one after Paperless is running, which is why this step comes last.

1. In Paperless, open your profile (top right) → API Auth Token → Create, and copy it.
2. Paste it as PAPERLESS_API_TOKEN in ./paperless-ai/.env and ./paperless-gpt/.env.
3. In ./paperless-ai/.env, set PAPERLESS_USERNAME to your Paperless username.
4. Recreate the containers so they pick up the changes:

docker compose up -d --force-recreate paperless-ai paperless-gpt

Tip: you need --force-recreate (or at least up -d) after any .env change. A plain docker compose restart does not reload .env files.

Don’t want AI at all? Comment out open-webui, paperless-ai, and paperless-gpt in compose.yaml (and ollama, if you kept it). Paperless works exactly the same without them.

Meet the AI helpers

Paperless-AI (port 3000) reads your documents and fills in titles, tags, correspondents, and dates using the local model. Open it once to finish its setup screen.

 Heads up: by default it writes changes directly to your documents. With SCAN_INTERVAL=*/30 * * * *, it checks for new documents every 30 minutes. It does not wait for your approval unless you set it up that way. My advice:

• Start with a handful of test documents and check the results.
• In its settings, limit processing to documents with a specific tag, and have it add a tag like ai-processed so you can always find (and undo) its work.
• Its History page shows what it changed.

Paperless-GPT (port 3002) goes further. It uses the vision model to re-read scanned pages, which is often much better than classic OCR on blurry receipts and phone photos. It can also suggest titles, tags, correspondents, and custom fields. You control it with tags in Paperless (these names match my .env, so check yours):

 Paperless-GPT has no login, so keep it on 127.0.0.1 (Step 2).

Dozzle (port 8080) is a live log viewer for every container. When something stops working (“why didn’t my receipt get tagged?”), look here first, or run docker compose logs -f paperless-ai. Note that it reads the Docker socket and has no login by default, so keep it on localhost too.

Other GPU options: LM Studio or another computer

Ollama on the Mac (Step 4) is what I use, but there are two other ways to get GPU speed.

LM Studio on the Mac. It speaks the OpenAI API, so switch the provider, not just the URL:

• Paperless-AI: choose the Custom (OpenAI-compatible) provider in its settings, with base URL http://host.docker.internal:1234/v1.
• Paperless-GPT: set LLM_PROVIDER: "openai" and OPENAI_BASE_URL: "http://host.docker.internal:1234/v1", and use the model name exactly as LM Studio shows it.

Another computer with a GPU (for example a Linux PC with an NVIDIA card running Ollama):

1. On that computer, make Ollama listen on the network:
   

   sudo systemctl edit ollama
   # add:
   # [Service]
   # Environment="OLLAMA_HOST=0.0.0.0:11434"
   sudo systemctl restart ollama
   

2. Use its Tailscale IP in the three .env files, for example http://100.x.y.z:11434. Containers on a Mac don’t always understand Tailscale’s short machine names, so the IP is more reliable.
3.  Ollama has no password. Only reach it over Tailscale, and never forward port 11434 on your router.

After either change, run docker compose up -d --force-recreate.

Backups and updates

• Back up these folders: ./paperless/data, ./paperless/media, and ./postgres/data.
• Even better, also export regularly. Paperless’s built-in exporter makes a clean, restorable copy:

docker compose exec paperless document_exporter ../export

That lands in ./paperless/export/. Copy it off the Mac.

• Updates: docker compose pull && docker compose up -d. Before you pull, check the release notes, especially for Paperless and Postgres. Never bump the Postgres major version (like 18 → 19) without a proper dump and restore.
• Updating the repo itself: you’ve edited the downloaded compose.yaml (Ollama commented out), so a later git pull of paperless-stack may conflict. Run git stash, then git pull, then git stash pop, and re-check that the ollama service is still commented out.
• Updating Ollama: Ollama.app on the Mac updates itself. Just restart it when it asks.

How the Document-AI Workflow Fits Together

scanner / phone / email
        │
        ▼
consume folder ──▶ Paperless-ngx ──OCR + archive──▶ searchable library
                        │
        ┌───────────────┼───────────────────┐
        ▼               ▼                   ▼
  Paperless-AI    Paperless-GPT       Dozzle (logs)
  titles, tags,   vision OCR,
  dates           custom fields
        └───────────────┬───────────────────┘
                        ▼
   Ollama.app on the Mac, Metal GPU (llama3.2:3b + minicpm-v:8b)
          via http://host.docker.internal:11434
                        ▲
            Open WebUI (download/manage models)

The rules I follow:

1. One local brain on the GPU. Ollama on the Mac serves every AI tool, and nothing goes to a cloud API.
2. AI helps, you decide. Test on a few documents first, use review tags where you can, and always check money amounts against the original document.
3. Least privilege. Each tool has its own API token, and Vaultwarden stays completely outside the AI loop.
4. The archive is the source of truth. Paperless stores and searches; AI only organizes. If an AI tool messes up, your original files are untouched.