56 lines
2.4 KiB
Markdown
56 lines
2.4 KiB
Markdown
# 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`. |
|
|
|
|
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 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:
|
|
|
|
```bash
|
|
docker compose --env-file .env.portainer.example config
|
|
```
|
|
|
|
Use real secrets only in Portainer or in a local, untracked `.env` file.
|