Paperless-Contracts/docs/portainer-stack.md

Portainer Stack Deployment

This repository can be deployed as a Portainer-managed Docker Compose stack. The stack builds the backend and frontend images from this Git repository, stores SQLite data in a named volume, and exposes the API and UI on configurable host ports.

Recommended Portainer Setup

1. In Portainer, create a new stack from a Git repository.
2. Use this repository as the Git source and set the Compose path to docker-compose.yml.
3. Set the stack name in Portainer, for example paperless-contracts.
4. Add the required environment variables from .env.portainer.example under Environment variables.
5. Deploy the stack.

Portainer should own the stack lifecycle after deployment. Avoid setting container_name values manually; Portainer and Docker Compose will namespace containers, networks, and volumes through the stack.

Required Variables

Set these values in Portainer before deploying:

Variable	Purpose
AUTH_PASSWORD	Login password for the admin user.
AUTH_JWT_SECRET	Long random secret used to sign login tokens.

AUTH_USERNAME defaults to admin when it is not set.

Important Optional Variables

Variable	Default	Purpose
FRONTEND_PORT	8113	Host port for the web UI.
BACKEND_PORT	8112	Host port for direct API access.
APP_EXTERNAL_URL	unset	Public app URL used in generated links and iCal entries.
PAPERLESS_BASE_URL	unset	Internal paperless-ngx API URL.
PAPERLESS_EXTERNAL_URL	unset	Public paperless-ngx URL for browser links.
PAPERLESS_TOKEN	unset	paperless-ngx API token.
WATCHTOWER_ENABLE	false	Enables Watchtower updates when set to true.
AI_ENABLED	false	Enables AI document analysis when provider settings are complete.
AI_PROVIDER	unset	openai, openai-compatible, or gemini.
AI_BASE_URL	provider default	Optional endpoint for OpenAI-compatible providers or custom gateways.
AI_MODEL	unset	Model name used for extraction.
AI_API_KEY	unset	API key for the selected AI provider.
PAPERLESS_WEBHOOK_SECRET	unset	Shared secret Paperless sends to /api/integrations/paperless/webhook.

Leave optional variables unset when they are not used. The backend treats blank optional variables as absent, which keeps Portainer edits from breaking URL validation.

Paperless Webhook

Create a Paperless workflow for newly consumed documents and add an HTTP webhook action pointing to:

https://your-contract-app.example.com/api/integrations/paperless/webhook

Send the document id in the JSON body as document_id and include the shared secret as header x-contract-companion-secret. The app will enqueue the document, analyze it with the configured AI provider, and wait for manual approval before writing tags/custom fields back to Paperless.

Data and Networking

• Contract data is stored in the named Docker volume contracts-data.
• Backend and frontend communicate on the private Compose network contract-companion.
• The frontend proxies /api/* requests to the backend service name contract-companion.
• Both services include healthchecks so Portainer can show container health.

Local Validation

Before deploying, you can validate the rendered Compose file locally:

docker compose --env-file .env.portainer.example config

Use real secrets only in Portainer or in a local, untracked .env file.