Maltonoloco/paperless

[maltonoloco]

Feature

Description

Adds a provider-neutral accounting document service backed by Paperless-ngx.

The service exposes an admin-only API for integrating document accounting workflows into the OpenTaberna admin frontend. Paperless-ngx handles document storage, OCR, full-text search, classification, previews, and asynchronous processing while its API token remains exclusively in the backend.

Included functionality:

• Upload and asynchronously process accounting documents
• Search, filter, paginate, update, and delete documents
• Download original files, previews, and thumbnails
• Track document-processing tasks
• Perform bulk document operations
• Manage tags, correspondents, document types, storage paths, and custom fields
• Check Paperless configuration and connectivity
• Translate Paperless errors into OpenTaberna’s standardized error responses
• Enforce upload-size limits
• Protect all accounting endpoints using the existing Keycloak admin authorization

The development environment now includes:

• Paperless-ngx 2.20.15
• Dedicated PostgreSQL database
• Dedicated Redis instance
• Persistent volumes for documents, media, consumption, database, and Redis data
• Authentication-compatible healthcheck
• Documented Paperless configuration variables
• Consolidated and regrouped .env.example configuration

Motivation

OpenTaberna needs a central accounting document archive that can be integrated into the admin frontend without implementing OCR, document indexing, preview generation, and classification from scratch.

Paperless-ngx provides these capabilities as a mature self-hosted service. The adapter boundary keeps the OpenTaberna API provider-neutral and prevents the admin frontend from directly handling Paperless credentials.

API Changes

• New endpoints added
• Existing endpoints modified
• Breaking changes

New admin-only base path:

/v1/admin/accounting

Endpoints:

• GET /status
• GET /documents
• POST /documents
• POST /documents/bulk-edit
• GET /documents/{document_id}
• PATCH /documents/{document_id}
• DELETE /documents/{document_id}
• GET /documents/{document_id}/file
• GET /tasks
• GET /resources/{resource}
• POST /resources/{resource}
• PATCH /resources/{resource}/{resource_id}
• DELETE /resources/{resource}/{resource_id}

Supported resource types:

• tags
• correspondents
• document-types
• storage-paths
• custom-fields

Document uploads return 202 Accepted with a Paperless task ID. Clients can poll /tasks?task_id=... until processing completes.

Database Changes

• New OpenTaberna tables/columns added
• OpenTaberna migrations required
• No OpenTaberna database changes

Paperless uses its own PostgreSQL service and persistent volume. Its schema and migrations are managed internally by Paperless-ngx.

Configuration Changes

New API environment variables:

• PAPERLESS_URL=http://localhost:8010
• PAPERLESS_TOKEN=
• PAPERLESS_TIMEOUT_SECONDS=30
• PAPERLESS_MAX_UPLOAD_BYTES=52428800

New Paperless container variables:

• PAPERLESS_ADMIN_USER=admin
• PAPERLESS_ADMIN_PASSWORD=admin
• PAPERLESS_DB_PASSWORD=paperless
• PAPERLESS_SECRET_KEY=CHANGE_ME_IN_PRODUCTION

For Docker Compose, the API receives the internal Paperless address:

http://opentaberna-paperless:8000

The Paperless UI is available locally at:

http://localhost:8010

Documentation

• API documentation updated (docs/)
• README updated if necessary
• Code comments added

Added:

docs/accounting.md

The documentation covers:

• Development setup
• API token configuration
• Available admin endpoints
• Asynchronous upload/task workflow
• Required environment variables
• Production security considerations

Testing

• Unit tests added/updated
• Paperless integration tests added
• All tests passing with default .env

Added unit coverage for:

• Document search and filter forwarding
• Provider-neutral status handling
• Partial document updates
• Upload-size enforcement
• Resource name translation and CRUD routing
• Dependency injection and response wrapping

Focused accounting and configuration verification:

40 passed

Full-suite result with telemetry disabled:

838 passed, 27 skipped, 8 failed

The eight failures are existing live telemetry integration tests that require:

OTEL_ENABLED=true

They are unrelated to the Paperless implementation. The collector and Prometheus were running, but the API and worker intentionally exported no metrics while telemetry was disabled.

Related Issues

Closes #

Checklist

• Code follows project style guidelines
• Environment variables documented in .env.example
• Provider integration is isolated behind an adapter interface
• Admin authorization is enforced
• Paperless credentials are not exposed to the frontend
• Upload limits are enforced before forwarding files
• Upstream errors use standardized OpenTaberna responses
• Ruff checks pass
• Docker Compose configuration validates
• Focused unit tests pass
• Development healthchecks verified
• No breaking API or OpenTaberna database changes