# 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.