# Settings

*Since 0.5.0.*

Every setting is an environment variable. Brick Work reads `data/.env` (or, if that file does not exist, a `.env` in the app folder) at start; a variable set in the environment wins over the file. Change a setting, then restart the app.

On/off settings take `1` for on. Where a setting accepts more spellings, the table says so.

## Login and security

| Variable | Default | What it does |
|---|---|---|
| `BW_AUTHENTICATION_PASSWORD` | none | The browser login password. Without it the server refuses to start, unless `BW_ALLOW_NO_LOGIN=1`. |
| `BW_ALLOW_NO_LOGIN` | off | `1` (or `true`, `yes`) runs without a password on purpose: anyone who can reach the app can edit the collection, export the database and create API tokens. |
| `BW_AUTHENTICATION_KEY` | generated | Signs browser sessions. When empty, a key is generated into `session.key` beside the database. Changing it ends every session. |
| `BW_SECURE_COOKIES` | off | `1` sends the session cookie only over HTTPS. Set it when the app is served over HTTPS. |
| `BW_TRUSTED_PROXIES` | `0` | How many reverse proxies in front of the app are trusted for their `X-Forwarded-*` headers (client address, scheme, host). Usually `1` behind a proxy; `0` trusts none, which is right when clients reach the app directly. |
| `BW_LOGIN_MAX_FAILURES` | `5` | Failed logins or API token checks per client address before the back-off starts. A value that is not a positive whole number falls back to the default. |
| `BW_LOGIN_MAX_DELAY` | `300` | Longest back-off, in seconds. The wait starts at 1 s and doubles up to this; a successful login resets it. |
| `BW_SECRET_KEY` | generated into `data/secret.key` on first use | Fernet key that encrypts the source keys you enter in **Tools & Admin → Catalogues & keys**. When set, it always wins and no file is made. When unset, Brick Work makes a key once and keeps it in `secret.key` beside `brickwork.db` (mode 600). If the data folder is not writable, key entry stays disabled and keys come from the environment only; set `BW_SECRET_KEY` to a key made with `python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"`, or make the folder writable. Keep the key safe: stored keys cannot be read without it. |
| `BW_API_TOKEN` | none | A bootstrap API token with admin scope, also used by `brickwork mcp` when no `--token-file` is given. Optional: stored tokens are created in the app or with `brickwork token create`. It cannot be revoked through the API. |
| `BW_MCP_WRITE` | off | `1` turns on the MCP server's write tools, as `brickwork mcp --allow-write` does. Only `1` counts. |

## Serving

| Variable | Default | What it does |
|---|---|---|
| `BW_HOST` | `0.0.0.0` | Address the server listens on (inside the container). |
| `BW_PORT` | `3333` | Port the server listens on. |
| `BW_READ_ONLY` | off | `1` (or `true`, `yes`, `on`) refuses changes in the browser and the API. In the CLI it covers the `token` and `wishlist` commands and the database export; other CLI commands, such as `settings set`, still write. |
| `BW_DEBUG` | off | `1` shows the exception and traceback on error pages and logs at debug level. Never on a reachable install. |
| `BW_DARK_MODE` | off | `1` makes dark the default theme; each browser can still choose. |
| `BW_IMPORT_MAX_MB` | `200` | Largest database import upload, in MB. It is also the cap for any request body; smaller per-upload limits (photos, PDFs, order files) stay as they are. |
| `BW_HIDE_ADD_SET` | off | `1` hides **Add** from the navigation and the header. |
| `BW_HIDE_ALL_SETS` | off | `1` hides **Sets** and **Set Inspector** from the navigation. |
| `BW_HIDE_ALL_MINIFIGURES` | off | `1` hides **Minifigures** from the navigation. |
| `BW_HIDE_ALL_PARTS` | off | `1` hides **Parts** from the navigation. |
| `BW_HIDE_ALL_PROBLEMS_PARTS` | off | `1` hides **Complete sets** from the navigation. |
| `BW_HIDE_ALL_STORAGES` | off | `1` hides **Storage** from the navigation. |
| `BW_HIDE_WISHES` | off | `1` hides **Wishlist** from the navigation. |

The `BW_HIDE_*` settings only remove the entry; the pages still open from a link.

## Storage and media

| Variable | Default | What it does |
|---|---|---|
| `BW_DB_PATH` | `data/brickwork.db` | The database file. The catalogue (`catalogue.db`), the session key, import and sync plans live in the same folder. |
| `BW_MEDIA_PATH` | the database folder | Where pictures, thumbnails, your own photos, identification thumbnails and instruction PDFs live, under its `data/` folder. Moving media means moving `data/images`, `data/thumbs`, `data/instructions` and `data/identifications` there; nothing in the database changes. |
| `BW_MIGRATION_REPORT` | `migration-report/` beside the database | The folder Tools & Admin reads the migration report from (`summary.md`, `proof.json` and the CSV files a 3.3 to 4.0 migration writes). Read only; the report download links serve only files in this folder. |

## Sources and budgets

| Variable | Default | What it does |
|---|---|---|
| `BW_BRICKLINK_CONSUMER_KEY` | none | BrickLink API consumer key. |
| `BW_BRICKLINK_CONSUMER_SECRET` | none | BrickLink API consumer secret. |
| `BW_BRICKLINK_TOKEN_VALUE` | none | BrickLink API access token. |
| `BW_BRICKLINK_TOKEN_SECRET` | none | BrickLink API token secret. All four together override the BrickLink key stored in the app. |
| `BW_REBRICKABLE_API_KEY` | none | Rebrickable API key; overrides the stored one. |
| `BW_BRICKSET_API_KEY` | none | Brickset API key; overrides the stored one. |
| `BW_REBRICKABLE_USER_TOKEN` | none | Your Rebrickable account token for collection sync, instead of connecting it in the app. |
| `BW_BRICKSET_USER_HASH` | none | Your Brickset account hash for collection sync, instead of connecting it in the app. |
| `BW_BRICKLINK_DAILY_BUDGET` | `4400` | BrickLink API calls per day. BrickLink allows 5,000; the rest is a margin for other tools on the same key. Must be a positive whole number. |
| `BW_REBRICKABLE_DAILY_BUDGET` | `1000` | Rebrickable API calls per day. Must be a positive whole number. |
| `BW_BRICKOGNIZE_DAILY_BUDGET` | `100` | Photo identifications per day. |
| `BW_PRICE_SETTINGS_LOCK` | on | Refuses changes to the BrickLink region and currency, which every stored price depends on. Only `0` unlocks them. |

## Workers

| Variable | Default | What it does |
|---|---|---|
| `BW_EMBEDDED_WORKER` | on | The app works through queued imports itself. `0` (or `false`, `no`, `off`) leaves them to `brickwork worker`, for headless installs. |

## Development only

| Variable | Default | What it does |
|---|---|---|
| `BW_PRIVATE_PATTERNS_FILE` | none | A file of extra regular expressions, one per line, that the private-material scans of the source tree, the demo and the documentation site also reject, such as your own host names. |

See also: [Command line](cli.md).