Prepare Portainer stack deployment

docs/portainer-stack.md

@@ -0,0 +1,55 @@
+# 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.