Skip to content

fix(docker): forward AUTO_START_SESSIONS to the container - #985

Merged
rmyndharis merged 1 commit into
mainfrom
fix/compose-forward-auto-start-sessions
Jul 29, 2026
Merged

fix(docker): forward AUTO_START_SESSIONS to the container#985
rmyndharis merged 1 commit into
mainfrom
fix/compose-forward-auto-start-sessions

Conversation

@rmyndharis

Copy link
Copy Markdown
Owner

Problem

docker-compose.yml never forwarded AUTO_START_SESSIONS into the openwa-api service. Not in the
current file, and not in any revision of it — git log -S 'AUTO_START_SESSIONS' -- docker-compose.yml
returns nothing. There is no env_file: entry either, and .dockerignore excludes .env* from the
build context, so there was no path by which the value could reach the process.

On a stock Docker Compose deployment the flag was therefore inert. SessionService.onModuleInit()
resets previously authenticated sessions to disconnected at boot, and with the flag never arriving,
onApplicationBootstrap() returned early and left them there. The operator got no error, because from
the application's point of view nothing was misconfigured — the variable simply was not present.

What made this hard to notice is that every other signal said the feature worked:

  • .env.example:25 documents AUTO_START_SESSIONS=false as a setting operators are meant to change.
  • docker-compose.dev.yml:58 does forward it, so it behaves correctly in development.
  • The application reads it correctly (feature-flags.ts) and validates it at boot (env.validation.ts).

Only the production compose file, where most deployments actually run, dropped it.

Change

One forward added next to the existing engine options, blank-defaulted to match them:

- AUTO_START_SESSIONS=${AUTO_START_SESSIONS:-}

Blank-defaulting matters for correctness here. AUTO_START_SESSIONS is opt-in and read as an exact
string comparison against "true", so an unset value rendering blank resolves to the documented
default of off. Only an explicit true starts sessions at boot, which keeps the behaviour of every
existing deployment unchanged.

The key is deliberately not added to BLANK_SHADOWED_ENV_KEYS. That list exists for keys the
compose file blank-forwards and the dashboard writes to data/.env.generated, where a blank forward
would shadow a saved dashboard value. AUTO_START_SESSIONS is not dashboard-managed, so it follows the
same pattern as WWEBJS_AUTH_TIMEOUT_MS and BODY_SIZE_LIMIT: forwarded blank, not cleared.

Verification

Rendered config before and after, with AUTO_START_SESSIONS=true present in .env:

before (main):  docker compose config -> variable absent from the service environment
after:          docker compose config -> AUTO_START_SESSIONS: "true"

The feature-flags spec now asserts the forward is present, so the gap cannot silently reopen. The
assertion was checked against a known-negative as well as the current file — it fails both when the
line is removed and when the variable name is misspelled, so it is not a vacuous match.

Full local gate: format:check, lint, tsc --noEmit -p tsconfig.json (including specs), build,
and the src/config suite (13 files, 182 tests) all pass. docker compose config -q parses. No
dashboard files are touched.

Scope

This is a packaging fix and does not change application behaviour.

It came out of triage on #981, where sessions come back as qr_ready after an upgrade, but it is not
a fix for that issue
— a missing flag leaves sessions idle at disconnected rather than presenting a
QR. It is relevant there only because it means the reporter's flag may never have been effective, which
changes how their report should be read. That investigation continues separately.

Follow-up worth tracking separately

The same audit found that the production compose forwards none of the runtime feature flags:
STORE_EPHEMERAL_MESSAGES, RESOLVE_LID_TO_PHONE, SIMULATE_TYPING, SIMULATE_TYPING_MAX_MS,
QUEUE_ENABLED, MCP_ENABLED, SERVE_DASHBOARD, SEARCH_ENABLED and SEARCH_PROVIDER are all
absent as well, and most are documented in .env.example.

They are left out of this PR on purpose. Several carry precedence considerations this one does not —
QUEUE_ENABLED in particular is written by the dashboard to data/.env.generated, so forwarding it
blank without adding it to BLANK_SHADOWED_ENV_KEYS would shadow a saved dashboard value and trade one
silent bug for another. Each deserves that judgement made explicitly rather than swept in here.

docker-compose.yml never passed AUTO_START_SESSIONS through to openwa-api —
not in any revision of the file — so on a stock Docker Compose deployment the
flag was inert. Sessions were reset to disconnected at boot and left there,
with no error to work from: from the application's point of view nothing was
misconfigured, the variable simply never arrived.

The omission was easy to miss because every other signal said the feature
worked. .env.example documents the setting, docker-compose.dev.yml forwards
it, and the application reads and validates it correctly.

Forward it blank-defaulted, matching the neighbouring engine options, so an
unset value still resolves to the documented opt-out default and only an
explicit "true" starts sessions at boot. It is deliberately not added to
BLANK_SHADOWED_ENV_KEYS: that list is for keys the dashboard writes to
data/.env.generated, and this one is not dashboard-managed.

The feature-flags spec now asserts the forward exists, so the same silent gap
cannot reopen.
@rmyndharis
rmyndharis merged commit a67902a into main Jul 29, 2026
8 checks passed
@rmyndharis
rmyndharis deleted the fix/compose-forward-auto-start-sessions branch July 29, 2026 06:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant