DOCSEARCHbyAlgolia
Submit Docs

Papermerge DMS Documentation

repository·master·Indexed 19 days ago

https://github.com/papermerge/papermerge-core

An open-source document management system for digital archives featuring OCR text extraction, full-text search, and support for PDF, TIFF, JPEG, and PNG files. Includes guides for Docker deployment, OIDC authentication via Keycloak, OAuth2-Proxy configuration, and development setup for frontend packages like commander.dev, kommon.dev, and viewer.dev.

Tokens
19.3K
Snippets
88
Records
108
Agent score
67%

What's inside Papermerge

  2. How OIDC Authentication works in Papermerge

    master

    The authentication flow uses OAuth2-Proxy as an intermediary between the browser and Papermerge to handle OIDC logic.

    Authentication Flow

    1. The user accesses Papermerge at http://localhost:8080.
    2. OAuth2-Proxy checks for a valid session.
    3. If no session exists, the user is redirected to the Keycloak login page.
    4. After successful login, Keycloak redirects back to OAuth2-Proxy.
    5. OAuth2-Proxy creates a session and forwards the request to Papermerge using the following HTTP headers:
      • X-Forwarded-User: The username.
      • X-Forwarded-Email: The user's email.
      • X-Forwarded-Groups: A comma-separated list of user groups.
    6. Papermerge reads these headers via the RemoteUserScheme. Users are automatically created in the Papermerge system upon their first successful login.

  8. Export Keycloak Realm for Persistence

    master

    To persist your Keycloak configuration (users, groups, roles) outside of the container, you can export the papermerge realm to a JSON file:

    # 1. Export the realm from inside the container
docker compose exec keycloak /opt/keycloak/bin/kc.sh export \
  --dir /tmp/export --realm papermerge

# 2. Copy the exported file to your local host
docker compose cp keycloak:/tmp/export/papermerge-realm.json \
  ./keycloak/realm-export.json

  9. Quick Start: Deploy Papermerge with OIDC (Keycloak) via Docker

    master

    This guide provides the steps to deploy a Papermerge instance using Docker with Keycloak as the OIDC identity provider and OAuth2-Proxy for authentication.

    1. Generate Cookie Secret

    Before starting, generate a unique secret for session cookies and save it to a .env file in the docker/oidc/ directory:

    cd <project root>/docker/oidc/
export OAUTH2_COOKIE_SECRET=$(openssl rand -base64 32)
echo "OAUTH2_COOKIE_SECRET=$OAUTH2_COOKIE_SECRET" > .env

    2. Start Services

    Run the following command to start the stack in detached mode:

    cd <project root>/docker/oidc/
docker compose up -d

    To build from scratch or redirect logs to a file, use:

    # Build and run
cd <project root>/docker/oidc/
docker compose up --build

# Build and redirect logs to compose.log
cd <project root>/docker/oidc/
docker compose up --build 2>&1 | tee compose.log

    3. Initialization and Verification

    Keycloak requires 1-2 minutes to initialize and import the realm. Monitor the status and logs to ensure services are ready:

    # Check container status
docker compose ps

# Follow logs
docker compose logs -f

    4. Access and Default Credentials

    ServiceURLCredentials
    Papermergehttp://localhost:8080(via Keycloak)
    Keycloak Adminhttp://localhost:9090admin / admin

    Pre-configured test users:

    UsernamePasswordRoleDescription
    adminadminadminFull administrator
    demodemouserRegular user
    cd <project root>/docker/oidc/
export OAUTH2_COOKIE_SECRET=$(openssl rand -base64 32)
echo "OAUTH2_COOKIE_SECRET=$OAUTH2_COOKIE_SECRET" > .env
docker compose up -d

  10. Select compatible Docker image tags for Papermerge

    master

    To ensure version compatibility and avoid unsupported side effects, use the specific image tags listed in the Papermerge version matrix. Using untested combinations of service images may cause issues.

    ### Papermerge 3.5.2 Compatibility Matrix

| Service | Image Tag |
| --- | --- |
| Papermerge | `papermerge/papermerge:3.5.2` |
| Auth Server | `papermerge/auth-server:1.1.3` |
| OCR Worker | `papermerge/ocrworker:0.3.1` |
| Path Template Worker | `papermerge/path-tmpl-worker:0.4` |
| S3 Worker | `papermerge/s3worker:0.5` |
| i3 Worker | `papermerge/i3worker:0.3` |
| DB | `postgres:16.1` |
| Redis | `bitname-redis:7.2` |
| Solr | `solr:9.7` |

  11. Set up the Frontend for development

    master

    The frontend is managed via yarn workspaces. Navigate to the frontend/ directory and ensure the following VITE_ environment variables are set to match your backend configuration:

    • VITE_REMOTE_USER: The username for the remote user.
    • VITE_REMOTE_USER_ID: The UUID of the remote user.
    • VITE_REMOTE_GROUPS: The groups the user belongs to.
    • VITE_BASE_URL: The URL of the backend (e.g., http://localhost:8000).
    • VITE_KEEP_UNUSED_DATA_FOR: Caching duration in seconds (e.g., 1).
    • VITE_REMOTE_ROLES: (Optional) Remote roles.

    Start the development server with yarn workspace ui dev. The UI will be available at http://localhost:5173/.

    cd frontend/
yarn workspace ui dev

  12. Start Papermerge with Docker

    master

    To run a basic instance of Papermerge using Docker, use the docker run command. You must provide a PAPERMERGE__SECURITY__SECRET_KEY and a PAPERMERGE__AUTH__PASSWORD via environment variables. This command maps port 8000 on your host to port 80 in the container.

    docker run -p 8000:80 \
    -e PAPERMERGE__SECURITY__SECRET_KEY=abc \
    -e PAPERMERGE__AUTH__PASSWORD=123 \
    papermerge/papermerge:3.5.3