From 314a2a245f17790d60db0d0e3ec89c109b8d34b6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=81lvaro=20Tejero-Cantero?= <807608+alvorithm@users.noreply.github.com> Date: Thu, 6 Aug 2026 14:14:44 +0200 Subject: [PATCH] :books: Fix the devenv backend-flags instructions (#11077) The section pointed at `docker/devenv/docker-compose.yaml`, which #9906 deleted when it split the devenv compose into `docker-compose.infra.yml` and `docker-compose.main.yml`. The same page names both replacements in its architecture section, so only this one was missed. Setting PENPOT_FLAGS in the container environment would not have worked anyway: `backend/scripts/_env` expands the inherited value before its own list, so its flags win. Document the mechanism that does work, the gitignored `backend/scripts/_env.local` that `start-dev` sources right after `_env`, and the left-to-right last-wins rule that lets an override switch off a flag `_env` enables. --- docs/technical-guide/developer/devenv.md | 26 +++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) diff --git a/docs/technical-guide/developer/devenv.md b/docs/technical-guide/developer/devenv.md index 922ed24f1d..5c3de5254a 100644 --- a/docs/technical-guide/developer/devenv.md +++ b/docs/technical-guide/developer/devenv.md @@ -419,16 +419,28 @@ After creating or modifying this file, **reload the browser** (no need to restar ### Backend flags via PENPOT_FLAGS Backend feature flags are controlled through the `PENPOT_FLAGS` environment -variable using the same `enable-` / `disable-` format. You can set -this in the `docker/devenv/docker-compose.yaml` file under the `main` service -`environment` section: +variable using the same `enable-` / `disable-` format. The devenv +sets its own list in `backend/scripts/_env`. -```yaml -environment: - - PENPOT_FLAGS=enable-access-tokens enable-mcp +To change that list for your checkout, create `backend/scripts/_env.local`. +`backend/scripts/start-dev` sources it immediately after `_env`, and the file +is gitignored, so your override never appears in `git status`: + +```bash +export PENPOT_FLAGS="$PENPOT_FLAGS enable-access-tokens enable-mcp" ``` -This requires **restarting the backend** to take effect. +Flags are applied left to right and the last entry wins, so appending to +`$PENPOT_FLAGS` both adds flags and switches off ones that `_env` enables: +`disable-demo-users` at the end turns off the demo users that `_env` enables +earlier. + +Setting `PENPOT_FLAGS` in the container environment does not work for this, +because `_env` expands the inherited value *before* its own list. Any flag it +sets afterwards wins over yours. + +This requires **restarting the backend** to take effect: stop the process in +the `backend` tmux window and run `./scripts/start-dev` again. > **Note**: Some features (e.g., access tokens, webhooks) need both frontend and > backend flags enabled to work end-to-end. The frontend flag enables the UI, while