Self-host on Linux (Docker Compose)

One compose file runs the server and its local AI on any box you own — a NUC in the meter cupboard, a NAS, an old desktop. About twenty minutes, most of it model downloads.

last updated 07 Jul 2026 · applies to server 0.x (pre-1.0)

note

On a Mac, prefer the native install — Docker on macOS cannot pass through Metal, so containers mean slower AI. This guide is the Linux path; OCR inside the container is PaddleOCR, selected automatically per platform.

What you need

Any 64-bit Linux box with Docker and Docker Compose installed. 8 GB of RAM is a comfortable floor for the 4B vision model; a GPU is optional — CPU works, just expect minutes rather than seconds per letter. Around 20 GB of free disk covers the image, the models and years of archive.

Install

Clone the repository and pull the published image (or build it locally with docker compose build):

git clone https://github.com/nielsfilmer/briefkist.git
      cd briefkist
      docker compose pull

The one-time model pull

The AI service sits on an internal-only Docker network with no internet route, by design — the process that holds your letters in plaintext during processing cannot reach the outside world at all. That means the models have to be downloaded once, with egress granted temporarily:

# 1. in docker-compose.yml, uncomment the "- default" line
      #    under ollama -> networks (grants temporary egress)
      docker compose up -d ollama
      docker compose exec ollama ollama pull qwen3-vl:4b-instruct
      docker compose exec ollama ollama pull bge-m3
      # 2. re-comment "- default", then bring everything up:
      docker compose up -d

Download once with egress, run forever without — the OCR models are baked into the image the same way.

Choose where it listens

The compose file publishes the server on 127.0.0.1:8484 by default. For your phone to reach it, change that to the address it should be reachable on — your LAN IP ("192.168.1.20:8484:8484") or your Tailscale IP.

caution

Never a bare "8484:8484" — that publishes your archive on every interface. Always name the exact address, and don't port-forward it to the internet; remote access belongs on a VPN (Tailscale or WireGuard).

Pair your phone

Mint a device token — it is shown exactly once:

docker compose exec briefkist python -m server.tokens_cli add my-phone

On the phone: open http://<server-address>:8484, tap the settings gear, paste the token, save — then "Add to Home Screen". Revoke a lost phone's token any time with tokens_cli revoke my-phone.

Back it up

The whole archive — one SQLite database plus the image folders — lives in the briefkist-data volume. Backing up that volume is a complete backup. Updating is docker compose pull && docker compose up -d.

Already running Ollama natively on the host? A commented variant at the bottom of docker-compose.yml points the server at it instead of the bundled service.

← previousAll docs next →Self-host on a Mac (native)