Docker Compose SMTP configuration behavior does not match documentation

[jlcolli79]

Environment

• OpenProject 17 Community Edition
• Official Docker Compose deployment
• Debian 12 LXC
• Internal SMTP relay with STARTTLS
• FreeIPA internal CA

Observed behavior

The outbound email documentation implies SMTP settings can be configured through:

• .env
• Docker Compose environment variables
• or the Administration UI

However, in practice:

1. SMTP variables defined only in .env are NOT injected into containers unless explicitly mapped into x-op-app -> environment (or override files).

2. The SMTP configuration UI is hidden even when SMTP runtime settings are not actually active.

3. Rails silently falls back to:

   localhost:25

4. Existing database-backed settings prevent environment-seeded SMTP settings from being applied after initial bootstrap.

5. The documentation does not clearly explain:

   • precedence order
   • bootstrap-only behavior
   • DB persistence behavior
   • requirement for explicit environment injection

Evidence

Running:

bundle exec rails runner "pp ActionMailer::Base.smtp_settings"

continued to show:

{address: "localhost", port: 25}

despite SMTP variables existing in .env.

Additional findings

The Docker Compose deployment required explicit environment injection through docker-compose.override.yml such as:

• OPENPROJECT_SMTP__ADDRESS
• OPENPROJECT_SMTP__PORT
• OPENPROJECT_SMTP__USER__NAME
• OPENPROJECT_SMTP__PASSWORD
• OPENPROJECT_EMAIL__DELIVERY__METHOD

Otherwise the application never consumed the SMTP configuration.

Additionally, internal SMTP over STARTTLS with private/internal PKI required manual CA injection into the containers because container trust stores do not inherit host trust stores automatically.

Resolution required

The deployment only partially functioned after:

• explicit environment injection in compose override
• container recreation
• SSRF allowlist overrides
• container CA trust injection
• repeated DB/settings resets

Even after these steps, SMTP configuration persistence behavior remained unclear because existing DB settings continued overriding environment-provided values.

Documentation concerns

This behavior was extremely difficult to diagnose because the documentation strongly suggests .env is sufficient.

The current documentation does not clearly communicate:

• .env alone is not enough
• variables must be explicitly injected into service environment sections
• settings may persist in the DB after first initialization
• SMTP UI behavior changes depending on configuration mode
• configuration precedence order

Related issue

This appears closely related to:

• openproject-docker-compose issue Please add SMTP Options in docker-compose.yml #134

#134

[jameskimmel]

SMTP variables defined only in .env are NOT injected into containers unless explicitly mapped into x-op-app -> environment (or override files).

This is what the default .env files states in the first line:

##
# All environment variables defined here will only apply if you pass them
# to the OpenProject container in docker-compose.yml under x-op-app -> environment.
# For the examples here this is already the case.

and the documentation states, that docker-compose.yml can be overwritten and you should use a docker-compose.override.yml instead.

So AFAIK it is probably best to change the .env defaults to your liking and add further configurations to the docker-compose.yml file. That could be mentioned better in the docs IMHO.

[jlcolli79]

Thanks, this makes sense and clarifies the Docker Compose behavior a lot.

I did test explicitly mapping the SMTP variables into x-op-app -> environment during troubleshooting, but still observed inconsistent SMTP behavior at runtime.

What made the situation especially confusing from an operator perspective was that:

• the UI allowed SMTP settings to be entered and saved
• the settings appeared valid
• but the runtime behavior did not consistently reflect those values
• and the precedence/order between DB settings, runtime env vars, and bootstrap behavior was not obvious

Interestingly, I also reproduced very similar SMTP/runtime behavior in the packaged binary/LXC deployment (non-Docker), where SMTP settings appeared configured but mail delivery still behaved inconsistently until switching to local sendmail relay instead.

So I think the underlying issue may be broader than just Compose env injection alone — more around configuration precedence, persistence semantics, and runtime expectations not being very clear in the documentation/UI.

Your explanation about .env only applying when explicitly injected into x-op-app -> environment definitely helped clarify part of the confusion though.