2.4 KiB
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
- In Portainer, create a new stack from a Git repository.
- Use this repository as the Git source and set the Compose path to
docker-compose.yml. - Set the stack name in Portainer, for example
paperless-contracts. - Add the required environment variables from
.env.portainer.exampleunder Environment variables. - 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. |
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.
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 namecontract-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.