Getting Started

For most self-hosted installs, start with Docker Compose.

If you want to run Paperwise from source or contribute to the codebase, see Dev Environment Setup.

Docker Compose

Use the repository root docker compose stack when you want the shortest path to a working deployment.

Prerequisites

• Docker Engine or Docker Desktop with Compose support

Start the stack

mkdir paperwise
cd paperwise

Create a docker-compose.yml file with the published image, then replace replace-with-a-strong-secret with your own secret:

services:
  api:
    image: ghcr.io/zellux/paperwise:latest
    environment:
      PAPERWISE_ENV: docker
      PAPERWISE_LOG_LEVEL: INFO
      PAPERWISE_API_HOST: 0.0.0.0
      PAPERWISE_API_PORT: 8000
      PAPERWISE_REDIS_URL: redis://redis:6379/0
      PAPERWISE_REPOSITORY_BACKEND: postgres
      PAPERWISE_POSTGRES_URL: postgresql+psycopg://paperwise:paperwise@postgres:5432/paperwise
      PAPERWISE_OBJECT_STORE_ROOT: /data/object-store
      PAPERWISE_AUTH_SECRET: replace-with-a-strong-secret
      PAPERWISE_AUTH_TOKEN_TTL_SECONDS: "43200"
    depends_on:
      redis:
        condition: service_healthy
      postgres:
        condition: service_healthy
    ports:
      - "8080:8000"
    volumes:
      - paperwise_data:/data
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/healthz', timeout=3)"]
      interval: 15s
      timeout: 5s
      retries: 5
      start_period: 20s
    restart: unless-stopped

  worker:
    image: ghcr.io/zellux/paperwise:latest
    command: ["celery", "-A", "paperwise.workers.celery_app.celery_app", "worker", "--loglevel=INFO"]
    environment:
      PAPERWISE_ENV: docker
      PAPERWISE_LOG_LEVEL: INFO
      PAPERWISE_REDIS_URL: redis://redis:6379/0
      PAPERWISE_REPOSITORY_BACKEND: postgres
      PAPERWISE_POSTGRES_URL: postgresql+psycopg://paperwise:paperwise@postgres:5432/paperwise
      PAPERWISE_OBJECT_STORE_ROOT: /data/object-store
      PAPERWISE_AUTH_SECRET: replace-with-a-strong-secret
      PAPERWISE_AUTH_TOKEN_TTL_SECONDS: "43200"
    depends_on:
      redis:
        condition: service_healthy
      postgres:
        condition: service_healthy
    volumes:
      - paperwise_data:/data
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 5
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: paperwise
      POSTGRES_PASSWORD: paperwise
      POSTGRES_DB: paperwise
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U paperwise -d paperwise"]
      interval: 10s
      timeout: 3s
      retries: 5
    restart: unless-stopped

volumes:
  paperwise_data:
  postgres_data:

Start the stack:

docker compose up -d

Open Paperwise at http://localhost:8080.

Before sharing

Before you hand this off to other users, verify a clean deploy end to end:

1. Sign up and sign in both work.
2. Saving Settings > Model Config succeeds.
3. Uploading a document moves it out of processing.
4. The worker is running and document jobs complete.
5. Ask My Docs returns an answer for at least one test document.

Updating

New images are published automatically when changes land on main.

To update a running server that uses ghcr.io/zellux/paperwise:latest:

docker compose pull
docker compose up -d

To pin a specific release, replace the image tag, for example:

image: ghcr.io/zellux/paperwise:v0.1.1

Then update by changing the tag in docker-compose.yml and running:

docker compose pull
docker compose up -d

Backups

Back up both persistent data locations:

• postgres_data for users, preferences, document records, and search metadata
• paperwise_data for uploaded files and extracted object-store data

If you only back up one of them, restore will be incomplete.

For a safe upgrade path:

1. Back up postgres_data.
2. Back up paperwise_data.
3. Run docker compose pull.
4. Run docker compose up -d.

Useful commands

Command	What it does
docker compose ps	Show service status for the self-hosted stack.
docker compose logs -f api worker	Follow backend and worker logs.
docker compose logs -f postgres redis	Follow database and queue logs.
docker compose pull	Download the latest published image tags referenced by your compose file.
docker compose down	Stop the stack.

Required first-run setup

After the app is running, there is one more required step: configure model connections in the web UI.

1. Create your first account or sign in. Paperwise has no guest mode.
2. Open Settings > Model Config.
3. Add one or more model connections.
4. Assign task models for metadata extraction, grounded Q&A, and OCR.
5. Save settings and test with a sample document.

Minimum setup by feature

Feature	Minimum setup
Document upload and extraction	A working Metadata Extraction connection in Settings > Model Config
Ask My Docs	A working Grounded Q&A connection in Settings > Model Config
OCR on scans and image PDFs	Either an OCR LLM connection or Local Tesseract enabled

Troubleshooting

If uploads stay stuck in processing:

• check that the worker container is running
• inspect docker compose logs -f api worker
• make sure Redis is healthy and reachable

If a new image was published but your server still looks old:

• run docker compose pull
• then run docker compose up -d
• if you pinned a version tag, update the tag in docker-compose.yml

If upload works but extraction or Ask My Docs fails:

• open Settings > Model Config
• confirm the required task models are assigned
• check the API logs for provider timeout or auth errors

Want to run from source?

If you plan to modify the code, debug the internals, or run Paperwise without Docker for the app processes, follow Dev Environment Setup.

Next: Model Config