Concerns

Overview

OhnePapier is functional (~467 documents processed) but has several operational risks, configuration gaps, and planned-but-unbuilt features. This document captures known issues to inform planning.

Configuration Risks

Hardcoded PostgreSQL Credentials

• Location: docker-compose.yml lines 37-39
• Issue: POSTGRES_USER: paperless, POSTGRES_PASSWORD: paperless are hardcoded directly in the compose file — committed to git
• Risk: Acceptable for local-only deployment (no external access to :5432), but violates secret hygiene if the repo ever goes public
• Mitigation: Move to docker-compose.env

No docker-compose.env Template

• Issue: docker-compose.env is required for startup but not in git, and no .env.example or template exists
• Risk: Fresh installs will fail with no clear guidance on what values are needed
• Mitigation: Create docker-compose.env.example with placeholder values and required keys documented

Unpinned Image Versions (:latest tags)

• Location: docker-compose.yml
• ghcr.io/paperless-ngx/paperless-ngx:latest
• clusterzx/paperless-ai (no tag)
• Risk: Silent breaking changes on docker compose pull; non-reproducible deployments
• Mitigation: Pin to specific digest or semver tags

PostgreSQL 18 Pre-release Risk

• Image: docker.io/library/postgres:18
• Issue: PostgreSQL 18 was pre-release at time of setup — may have instability or behavioral changes
• Risk: Data integrity or query behavior issues on postgres upgrades
• Mitigation: Consider pinning to postgres:17 (stable) or postgres:18-beta for explicit pre-release opt-in

Security Concerns

Port Exposure

• :8000 (Paperless web UI) and :3000 (paperless-ai) exposed to all interfaces by default (0.0.0.0)
• On a home network this is typically fine, but adds risk if the host machine is publicly reachable
• No TLS / reverse proxy configured

API Token in Docker Volume

• Paperless API token is configured inside the paperless-ai container's /app/data volume
• No rotation strategy documented
• If volume is inspected, token is exposed

SECRET_KEY Handling

• Paperless-ngx SECRET_KEY lives in docker-compose.env (not in git) — correct
• No guidance on how to generate a strong key

Operational Risks

No Health Checks

• Docker Compose has no healthcheck directives for any service
• Services report as "running" even if the application layer is broken
• docker compose ps gives false confidence

No Ollama Dependency Probe

• paperless-ai starts immediately after webserver, but has no check that Ollama is reachable on the host
• Known failure mode: If Ollama is not running, paperless-ai silently fails on AI calls with no alerting
• Documented in CLAUDE.md pre-flight, but not enforced

Cold-Start Ordering Risk

• paperless-ai depends_on: webserver but webserver takes 30-60s to become ready after container starts
• paperless-ai may attempt API calls before webserver is fully initialized
• No condition: service_healthy check in depends_on

No Backup Strategy

• PostgreSQL data is in a named Docker volume (pgdata) with no documented backup procedure
• export/ directory exists for Paperless export but no automated schedule
• Loss of pgdata volume = loss of all document metadata and configuration

Missing Features (Planned)

From CLAUDE.md Project Status:

Technical Debt

paperless-ai Configuration Not in docker-compose.yml

• paperless-ai environment (PAPERLESS_API_URL, OLLAMA_MODEL, SCAN_INTERVAL, etc.) is configured inside the container's /app/data volume via the paperless-ai web UI
• This configuration is not version-controlled or reproducible without manual re-entry
• Risk: configuration lost if paperless-ai_data volume is deleted

No Compose Override Files

• No docker-compose.override.yml pattern for local development vs production variants
• All environment differences must be managed via docker-compose.env

Single-User Setup

• Currently assumes a single admin user (token generated from User.objects.first())
• No multi-user or role-based access documented

Fragile Areas

Mapped: 2026-04-17