Getting started

Pick the deployment shape that fits.

Docker Compose (canonical)

docker-compose.yml

services:
  suchi:
    image: ghcr.io/suchi-dms/suchi:latest
    restart: unless-stopped
    user: "1000:1000"
    read_only: true
    tmpfs: [/tmp]
    security_opt: [no-new-privileges:true]
    cap_drop: [ALL]
    volumes:
      - ./data:/data
    ports:
      - "8000:8000"
    environment:
      PUBLIC_URL: https://docs.example.com

docker compose up -d
docker compose logs suchi | grep 'setup.token'

Copy the token from the log and POST it to /setup:

curl -X POST http://localhost:8000/setup \
    -H 'Content-Type: application/json' \
    -d '{"token":"<the token>","email":"[email protected]","password":"..."}'

Then hit http://localhost:8000/ in a browser and sign in.

Bare binary + systemd

Download the suchi binary for your OS/arch from the releases page.

install -m 0755 suchi /usr/local/bin/suchi
mkdir -p /var/lib/suchi
suchi serve

Ready-to-copy templates for the four common self-host shapes live under deploy/ in the repo:

deploy/systemd/suchi.service — systemd unit with a hardened sandbox and the two required env vars pre-set.
deploy/caddy/Caddyfile — Caddy reverse-proxy block (auto-TLS).
deploy/nginx/suchi.conf — nginx server block (bring your own certs).
deploy/traefik/suchi.yml — Traefik dynamic-config snippet.
deploy/k8s/suchi.yaml — single-replica Deployment + PVC + Service. SQLite is single-writer; do not scale up.

Every template documents the placeholders you need to edit before paste.

What just happened?

On first boot, suchi ran embedded migrations up to the current schema version.
It auto-loaded the Johnny.Decimal starter tree (four areas: Life admin, Money, Home, System). See JD for the shape.
It printed a one-time setup token to the log at WARN level.
/healthz is process-alive; /readyz is DB-reachable + schema current.
/metrics exposes Prometheus counters (idle counts, HTTP latency histogram, job pipeline gauges).

Picking an image: slim vs full

The ghcr.io/suchi-dms/suchi:latest tag is the slim image (~70 MB, Alpine + qpdf + pdftotext + tesseract). It covers the whole PDF pipeline including OCR of scanned pages via the in-process tessocr engine (pdftoppm → tesseract). Image barcodes, EPUBs, and office documents (docx, xlsx, pptx, odt, rtf, csv via anydoc) work out of the box. What it doesn’t ship: the ocrmypdf wrapper (so no text-selectable scanned-PDF archives — the extracted text still lands in documents.content and FTS indexes it), DjVu, and Outlook .msg parsing. For those, pull the full image (~400 MB): ghcr.io/suchi-dms/suchi:latest-full. Same binary, extra runtime deps. Both images can be forced to a specific OCR engine via OCR_ENGINE (auto | tesseract | ocrmypdf). See supported file types for the per-format matrix.

Next steps

What suchi actually ingests: supported file types
Import an existing archive bundle: importer
Tune the running instance: config
Add OIDC for team sign-in: config#oidc

Overview

Getting started

Reference

Concepts

Operations

Guides

Development

Alternatives

Getting started

Docker Compose (canonical)

Bare binary + systemd

What just happened?

Picking an image: slim vs full

Next steps

​Docker Compose (canonical)

​Bare binary + systemd

​What just happened?

​Picking an image: slim vs full

​Next steps

Docker Compose (canonical)

Bare binary + systemd

What just happened?

Picking an image: slim vs full

Next steps