deploy/compose/README.md

Rama main · réplica de lectura del repositorio original.

# Run with Docker Compose

```sh
docker compose up -d
```

Open <http://localhost:8000> and a setup wizard takes it from there: it asks
where to keep the data, creates your account (the first one is the
administrator), and writes `config.yaml` for you.

## Volumes

| Volume | Mounted at | Holds |
| --- | --- | --- |
| `stocktake-config` | `/config` | `config.yaml`, which the setup wizard writes |
| `stocktake-data` | `/data` | The database and any formats you add — **back this up** |

Both are named volumes, which Docker creates with the right owner. To use
folders on the host instead, replace the two volume lines with bind mounts and
run `chown -R 1000:1000` on those folders first: the app runs as uid 1000.

## The annotated config

The `config.yaml` in this directory is the annotated default — every option
documented, almost every line commented out. You do not need to edit it before
starting; it is there to read, and to edit afterwards if you would rather
change something by hand than through the admin page.

## Before you expose it

Nothing here terminates TLS, and the app will not pretend otherwise. Put a
reverse proxy in front (Caddy, Traefik, nginx). The wizard's **Environment**
step asks for the HTTPS URL and your proxy's address, and sets the two settings
below from them; to do it by hand afterwards, in `config.yaml`:

```yaml
auth:
  cookie_secure: true          # the session cookie stops travelling in clear
  trusted_proxies:
    - 172.16.0.0/12            # your proxy, and nothing wider
```

`trusted_proxies` matters more than it looks. Without it the app cannot tell
that a TLS-terminating proxy's connection was encrypted: the login page warns
about plain HTTP when you are not on it, passkeys are not offered, and every
sign-in is recorded against the proxy's address. Set too wide, and a caller can
choose the address recorded against their own.

## Upgrading

```sh
docker compose pull && docker compose up -d
```

The app migrates its own database at startup. **[Back up](https://jarrodruggiero.github.io/stocktake/deploy/#backing-up-and-restoring) first** — migrations
roll forward, and rolling an image back after one has run is not supported.

## Backups

The database, any formats you added and `config.yaml`, copied while the app
runs: [Backing up and restoring](https://jarrodruggiero.github.io/stocktake/deploy/#backing-up-and-restoring).
Restoring SQLite has one step that is easy to miss, so read that part too.

## Useful commands

```sh
docker compose logs -f app
docker compose exec app python -m app.recover --list      # locked out
docker compose exec app python -m app.pricefeed           # fetch prices now
```