CODE_GUIDELINES.md

@@ -1277,7 +1277,8 @@ mix hex.outdated
 
 **SMTP configuration:**
 
-- SMTP can be configured via **ENV variables** (`SMTP_HOST`, `SMTP_PORT`, `SMTP_USERNAME`, `SMTP_PASSWORD`, `SMTP_PASSWORD_FILE`, `SMTP_SSL`) or via **Admin Settings** (database: `smtp_host`, `smtp_port`, `smtp_username`, `smtp_password`, `smtp_ssl`). ENV takes priority (same pattern as OIDC/Vereinfacht).
+- SMTP can be configured via **ENV variables** (`SMTP_HOST`, `SMTP_PORT`, `SMTP_USERNAME`, `SMTP_PASSWORD`, `SMTP_PASSWORD_FILE`, `SMTP_SSL`) or via **Admin Settings** (database: `smtp_host`, `smtp_port`, `smtp_username`, `smtp_password`, `smtp_ssl`).
+- **ENV-only policy:** If `SMTP_HOST` is set, SMTP is treated as environment-managed only. All SMTP fields in Settings are read-only, SMTP save action is hidden, and the UI shows a warning when required ENV values are missing (`SMTP_USERNAME`, and `SMTP_PASSWORD` or `SMTP_PASSWORD_FILE`).
 - **Sensitive settings in DB:** `smtp_password` and `oidc_client_secret` are excluded from the default read of the Setting resource; they are loaded only via explicit select when needed (e.g. `Mv.Config.smtp_password/0`, `Mv.Config.oidc_client_secret/0`). This avoids exposing secrets through `get_settings()`.
 - **Settings cache:** `Mv.Membership.get_settings/0` uses `Mv.Membership.SettingsCache` when the cache process is running (not in test). Cache has a short TTL and is invalidated on every settings update. This avoids repeated DB reads on hot paths (e.g. `RegistrationEnabled` validation, `Layouts.public_page`). In test, the cache is not started so all callers use `get_settings_uncached/0` in the test process (Ecto Sandbox).
 - **Join emails (domain → web):** The domain calls `Mv.Membership.JoinNotifier` (config `:join_notifier`, default `MvWeb.JoinNotifierImpl`) for sending join confirmation, already-member, and already-pending emails. This keeps the domain independent of the web layer; tests can override the notifier.

docs/smtp-configuration-concept.md

@@ -25,7 +25,10 @@ Enable configurable SMTP for sending transactional emails (join confirmation, us
 | ENV      | 1        | Production, Docker, 12-factor     |
 | Settings | 2        | Admin UI, dev without ENV          |
 
-When an ENV variable is set, the corresponding Settings field is read-only in the UI (with hint "Set by environment").
+When `SMTP_HOST` is set, SMTP runs in **ENV-only mode**:
+- all SMTP fields in Settings are read-only,
+- saving SMTP settings in the UI is disabled,
+- and the UI shows a warning block if required SMTP ENV values are missing.
 
 ---
 
@@ -63,6 +66,14 @@ Support **SMTP_PASSWORD_FILE** (path to file containing the password), same patt
   - Show a warning in the Settings UI.
   - Delivery attempts silently fall back to the Local adapter (no crash).
 
+### 6.1 Behaviour in ENV-only mode (`SMTP_HOST` set)
+
+- The SMTP source of truth is environment variables only.
+- The UI does not allow editing SMTP fields in this mode.
+- The Settings page shows a warning block when required values are missing:
+  - `SMTP_USERNAME`
+  - `SMTP_PASSWORD` or `SMTP_PASSWORD_FILE`
+
 ---
 
 ## 7. Test Email (Settings UI)

lib/mv/config.ex

@@ -478,48 +478,61 @@ defmodule Mv.Config do
   end
 
   @doc """
-  Returns SMTP port as integer. ENV `SMTP_PORT` (parsed) overrides Settings.
-  Returns nil when neither ENV nor Settings provide a valid port.
+  Returns SMTP port as integer.
+
+  Policy:
+  - ENV-only mode (`SMTP_HOST` set): read from ENV `SMTP_PORT`
+  - Settings mode: read from Settings only
   """
   @spec smtp_port() :: non_neg_integer() | nil
   def smtp_port do
-    case System.get_env("SMTP_PORT") do
-      nil ->
-        get_from_settings_integer(:smtp_port)
-
-      value when is_binary(value) ->
-        case Integer.parse(String.trim(value)) do
-          {port, _} when port > 0 -> port
-          _ -> nil
-        end
+    if smtp_env_mode?() do
+      parse_smtp_port_env(System.get_env("SMTP_PORT"))
+    else
+      get_from_settings_integer(:smtp_port)
     end
   end
 
   @doc """
-  Returns SMTP username. ENV `SMTP_USERNAME` overrides Settings.
+  Returns SMTP username.
+
+  Policy:
+  - ENV-only mode (`SMTP_HOST` set): read from ENV `SMTP_USERNAME`
+  - Settings mode: read from Settings only
   """
   @spec smtp_username() :: String.t() | nil
   def smtp_username do
-    smtp_env_or_setting("SMTP_USERNAME", :smtp_username)
+    if smtp_env_mode?() do
+      System.get_env("SMTP_USERNAME") |> trim_nil()
+    else
+      get_from_settings(:smtp_username)
+    end
   end
 
   @doc """
   Returns SMTP password.
 
-  Priority: `SMTP_PASSWORD` ENV > `SMTP_PASSWORD_FILE` (file contents) > Settings.
+  Policy:
+  - ENV-only mode (`SMTP_HOST` set): `SMTP_PASSWORD` > `SMTP_PASSWORD_FILE`
+  - Settings mode: read from Settings only
+
   Strips trailing whitespace/newlines from file contents.
   """
   @spec smtp_password() :: String.t() | nil
   def smtp_password do
-    case System.get_env("SMTP_PASSWORD") do
-      nil -> smtp_password_from_file_or_settings()
-      value -> trim_nil(value)
+    if smtp_env_mode?() do
+      case System.get_env("SMTP_PASSWORD") do
+        nil -> smtp_password_from_file_or_settings()
+        value -> trim_nil(value)
+      end
+    else
+      get_smtp_password_from_settings()
     end
   end
 
   defp smtp_password_from_file_or_settings do
     case System.get_env("SMTP_PASSWORD_FILE") do
-      nil -> get_smtp_password_from_settings()
+      nil -> nil
       path -> read_smtp_password_file(path)
     end
   end
@@ -533,11 +546,18 @@ defmodule Mv.Config do
 
   @doc """
   Returns SMTP TLS/SSL mode string (e.g. 'tls', 'ssl', 'none').
-  ENV `SMTP_SSL` overrides Settings.
+
+  Policy:
+  - ENV-only mode (`SMTP_HOST` set): read from ENV `SMTP_SSL`
+  - Settings mode: read from Settings only
   """
   @spec smtp_ssl() :: String.t() | nil
   def smtp_ssl do
-    smtp_env_or_setting("SMTP_SSL", :smtp_ssl)
+    if smtp_env_mode?() do
+      System.get_env("SMTP_SSL") |> trim_nil()
+    else
+      get_from_settings(:smtp_ssl)
+    end
   end
 
   @doc """
@@ -549,12 +569,39 @@ defmodule Mv.Config do
   end
 
   @doc """
-  Returns true when any SMTP ENV variable is set (used in Settings UI for hints).
+  Returns true when SMTP ENV mode is active.
   """
   @spec smtp_env_configured?() :: boolean()
   def smtp_env_configured? do
-    smtp_host_env_set?() or smtp_port_env_set?() or smtp_username_env_set?() or
-      smtp_password_env_set?() or smtp_ssl_env_set?()
+    smtp_env_mode?()
+  end
+
+  @doc """
+  Returns true when SMTP is managed by environment variables.
+
+  Policy: if `SMTP_HOST` is set, SMTP is treated as ENV-only.
+  """
+  @spec smtp_env_mode?() :: boolean()
+  def smtp_env_mode? do
+    smtp_host_env_set?()
+  end
+
+  @doc """
+  Returns missing required SMTP ENV keys for ENV-only mode warnings.
+
+  Required in ENV-only mode:
+  - `SMTP_USERNAME`
+  - one of `SMTP_PASSWORD` or `SMTP_PASSWORD_FILE`
+  """
+  @spec smtp_missing_required_env_keys() :: [String.t()]
+  def smtp_missing_required_env_keys do
+    if smtp_env_mode?() do
+      []
+      |> maybe_add_missing("SMTP_USERNAME", smtp_username_env_set?())
+      |> maybe_add_missing("SMTP_PASSWORD/SMTP_PASSWORD_FILE", smtp_password_env_set?())
+    else
+      []
+    end
   end
 
   @doc "Returns true if SMTP_HOST ENV is set."
@@ -618,6 +665,17 @@ defmodule Mv.Config do
   @spec mail_from_email_env_set?() :: boolean()
   def mail_from_email_env_set?, do: env_set?("MAIL_FROM_EMAIL")
 
+  defp parse_smtp_port_env(nil), do: nil
+
+  defp parse_smtp_port_env(value) when is_binary(value) do
+    case Integer.parse(String.trim(value)) do
+      {port, _} when port > 0 -> port
+      _ -> nil
+    end
+  end
+
+  defp parse_smtp_port_env(_), do: nil
+
   # Reads a plain string SMTP setting: ENV first, then Settings.
   defp smtp_env_or_setting(env_key, setting_key) do
     case System.get_env(env_key) do
@@ -626,6 +684,9 @@ defmodule Mv.Config do
     end
   end
 
+  defp maybe_add_missing(acc, _label, true), do: acc
+  defp maybe_add_missing(acc, label, false), do: acc ++ [label]
+
   # Reads an integer setting attribute from Settings.
   defp get_from_settings_integer(key) do
     case Mv.Membership.get_settings() do

lib/mv_web/live/global_settings_live.ex

@@ -86,6 +86,8 @@ defmodule MvWeb.GlobalSettingsLive do
       |> assign(:oidc_client_secret_set, Mv.Config.oidc_client_secret_set?())
       |> assign(:registration_enabled, settings.registration_enabled != false)
       |> assign(:smtp_env_configured, Mv.Config.smtp_env_configured?())
+      |> assign(:smtp_env_mode, Mv.Config.smtp_env_mode?())
+      |> assign(:smtp_missing_required_env_keys, Mv.Config.smtp_missing_required_env_keys())
       |> assign(:smtp_host_env_set, Mv.Config.smtp_host_env_set?())
       |> assign(:smtp_port_env_set, Mv.Config.smtp_port_env_set?())
       |> assign(:smtp_username_env_set, Mv.Config.smtp_username_env_set?())
@@ -321,12 +323,25 @@ defmodule MvWeb.GlobalSettingsLive do
         </.form_section>
         <%!-- SMTP / E-Mail Section --%>
         <.form_section title={gettext("SMTP / E-Mail")}>
-          <%= if @smtp_env_configured do %>
+          <%= if @smtp_env_mode do %>
             <p class="text-sm text-base-content/70 mb-4">
-              {gettext("Some values are set via environment variables. Those fields are read-only.")}
+              {gettext(
+                "SMTP is fully managed via environment variables. All SMTP fields are read-only."
+              )}
             </p>
           <% end %>
 
+          <%= if @smtp_env_mode and @smtp_missing_required_env_keys != [] do %>
+            <div class="mb-4 flex items-start gap-2 p-3 rounded-lg border border-warning bg-warning/10 text-warning-aa text-sm">
+              <.icon name="hero-exclamation-triangle" class="size-5 shrink-0 mt-0.5" />
+              <span>
+                {gettext("SMTP environment configuration appears incomplete. Missing: %{keys}",
+                  keys: Enum.join(@smtp_missing_required_env_keys, ", ")
+                )}
+              </span>
+            </div>
+          <% end %>
+
           <%= if @environment == :prod and not @smtp_configured do %>
             <div class="mb-4 flex items-start gap-2 p-3 rounded-lg border border-warning bg-warning/10 text-warning-aa text-sm">
               <.icon name="hero-exclamation-triangle" class="size-5 shrink-0 mt-0.5" />
@@ -345,7 +360,7 @@ defmodule MvWeb.GlobalSettingsLive do
                   field={@form[:smtp_host]}
                   type="text"
                   label={gettext("Host")}
-                  disabled={@smtp_host_env_set}
+                  disabled={@smtp_env_mode}
                   placeholder={
                     if(@smtp_host_env_set,
                       do: gettext("From SMTP_HOST"),
@@ -357,14 +372,14 @@ defmodule MvWeb.GlobalSettingsLive do
                   field={@form[:smtp_port]}
                   type="number"
                   label={gettext("Port")}
-                  disabled={@smtp_port_env_set}
+                  disabled={@smtp_env_mode}
                   placeholder={if(@smtp_port_env_set, do: gettext("From SMTP_PORT"), else: "587")}
                 />
                 <.input
                   field={@form[:smtp_ssl]}
                   type="select"
                   label={gettext("TLS/SSL")}
-                  disabled={@smtp_ssl_env_set}
+                  disabled={@smtp_env_mode}
                   options={[
                     {gettext("TLS (port 587, recommended)"), "tls"},
                     {gettext("SSL (port 465)"), "ssl"},
@@ -379,7 +394,7 @@ defmodule MvWeb.GlobalSettingsLive do
                   field={@form[:smtp_username]}
                   type="text"
                   label={gettext("Username")}
-                  disabled={@smtp_username_env_set}
+                  disabled={@smtp_env_mode}
                   placeholder={
                     if(@smtp_username_env_set,
                       do: gettext("From SMTP_USERNAME"),
@@ -391,7 +406,7 @@ defmodule MvWeb.GlobalSettingsLive do
                   field={@form[:smtp_password]}
                   type="password"
                   label={gettext("Password")}
-                  disabled={@smtp_password_env_set}
+                  disabled={@smtp_env_mode}
                   placeholder={
                     if(@smtp_password_env_set,
                       do: gettext("From SMTP_PASSWORD"),
@@ -410,7 +425,7 @@ defmodule MvWeb.GlobalSettingsLive do
                   field={@form[:smtp_from_email]}
                   type="email"
                   label={gettext("Sender email (From)")}
-                  disabled={@smtp_from_email_env_set}
+                  disabled={@smtp_env_mode}
                   placeholder={
                     if(@smtp_from_email_env_set,
                       do: gettext("From MAIL_FROM_EMAIL"),
@@ -422,7 +437,7 @@ defmodule MvWeb.GlobalSettingsLive do
                   field={@form[:smtp_from_name]}
                   type="text"
                   label={gettext("Sender name (From)")}
-                  disabled={@smtp_from_name_env_set}
+                  disabled={@smtp_env_mode}
                   placeholder={
                     if(@smtp_from_name_env_set, do: gettext("From MAIL_FROM_NAME"), else: "Mila")
                   }
@@ -436,9 +451,10 @@ defmodule MvWeb.GlobalSettingsLive do
             </p>
             <.button
               :if={
-                not (@smtp_host_env_set and @smtp_port_env_set and @smtp_username_env_set and
-                       @smtp_password_env_set and @smtp_ssl_env_set and @smtp_from_email_env_set and
-                       @smtp_from_name_env_set)
+                not @smtp_env_mode and
+                  not (@smtp_host_env_set and @smtp_port_env_set and @smtp_username_env_set and
+                         @smtp_password_env_set and @smtp_ssl_env_set and @smtp_from_email_env_set and
+                         @smtp_from_name_env_set)
               }
               phx-disable-with={gettext("Saving...")}
               variant="primary"

priv/gettext/de/LC_MESSAGES/default.po

@@ -3917,3 +3917,13 @@ msgstr "Offen"
 #, elixir-autogen, elixir-format
 msgid "join page URL in a new tab"
 msgstr "Beitrittslink in einem neuen Tab"
+
+#: lib/mv_web/live/global_settings_live.ex
+#, elixir-autogen, elixir-format
+msgid "SMTP environment configuration appears incomplete. Missing: %{keys}"
+msgstr "Die SMTP-Umgebungs-Konfiguration ist unvollständig. Fehlend: %{keys}"
+
+#: lib/mv_web/live/global_settings_live.ex
+#, elixir-autogen, elixir-format
+msgid "SMTP is fully managed via environment variables. All SMTP fields are read-only."
+msgstr "SMTP wird vollständig über Umgebungsvariablen verwaltet. Alle SMTP-Felder sind schreibgeschützt."

priv/gettext/default.pot

@@ -3917,3 +3917,13 @@ msgstr ""
 #, elixir-autogen, elixir-format
 msgid "join page URL in a new tab"
 msgstr ""
+
+#: lib/mv_web/live/global_settings_live.ex
+#, elixir-autogen, elixir-format
+msgid "SMTP environment configuration appears incomplete. Missing: %{keys}"
+msgstr ""
+
+#: lib/mv_web/live/global_settings_live.ex
+#, elixir-autogen, elixir-format
+msgid "SMTP is fully managed via environment variables. All SMTP fields are read-only."
+msgstr ""

priv/gettext/en/LC_MESSAGES/default.po

@@ -3917,3 +3917,13 @@ msgstr "Open"
 #, elixir-autogen, elixir-format
 msgid "join page URL in a new tab"
 msgstr "join page URL in a new tab"
+
+#: lib/mv_web/live/global_settings_live.ex
+#, elixir-autogen, elixir-format
+msgid "SMTP environment configuration appears incomplete. Missing: %{keys}"
+msgstr ""
+
+#: lib/mv_web/live/global_settings_live.ex
+#, elixir-autogen, elixir-format
+msgid "SMTP is fully managed via environment variables. All SMTP fields are read-only."
+msgstr ""

test/mv/config_smtp_test.exs

@@ -23,7 +23,8 @@ defmodule Mv.ConfigSmtpTest do
   end
 
   describe "smtp_port/0" do
-    test "returns parsed integer when SMTP_PORT ENV is set" do
+    test "returns parsed integer when SMTP_PORT ENV is set in ENV-only mode" do
+      set_smtp_env("SMTP_HOST", "smtp.example.com")
       set_smtp_env("SMTP_PORT", "587")
       assert Mv.Config.smtp_port() == 587
     after
@@ -52,13 +53,21 @@ defmodule Mv.ConfigSmtpTest do
   end
 
   describe "smtp_env_configured?/0" do
-    test "returns true when any SMTP ENV variable is set" do
+    test "returns true when SMTP_HOST is set" do
       set_smtp_env("SMTP_HOST", "smtp.example.com")
       assert Mv.Config.smtp_env_configured?() == true
     after
       clear_smtp_env()
     end
 
+    test "returns false when SMTP_HOST is not set even if other SMTP ENV variables are set" do
+      set_smtp_env("SMTP_USERNAME", "user@example.com")
+      set_smtp_env("SMTP_PASSWORD", "secret")
+      refute Mv.Config.smtp_env_configured?()
+    after
+      clear_smtp_env()
+    end
+
     test "returns false when no SMTP ENV variables are set" do
       clear_smtp_env()
       refute Mv.Config.smtp_env_configured?()
@@ -66,15 +75,17 @@ defmodule Mv.ConfigSmtpTest do
   end
 
   describe "smtp_password/0 and SMTP_PASSWORD_FILE" do
-    test "returns value from SMTP_PASSWORD when set" do
+    test "returns value from SMTP_PASSWORD when set in ENV-only mode" do
+      set_smtp_env("SMTP_HOST", "smtp.example.com")
       set_smtp_env("SMTP_PASSWORD", "env-secret")
       assert Mv.Config.smtp_password() == "env-secret"
     after
       clear_smtp_env()
     end
 
-    test "returns content of file when SMTP_PASSWORD_FILE is set and SMTP_PASSWORD is not" do
+    test "returns content of file when SMTP_PASSWORD_FILE is set in ENV-only mode and SMTP_PASSWORD is not" do
       clear_smtp_env()
+      set_smtp_env("SMTP_HOST", "smtp.example.com")
       path = Path.join(System.tmp_dir!(), "mv_smtp_test_#{System.unique_integer([:positive])}")
       File.write!(path, "file-secret\n")
       Process.put(:smtp_password_file_path, path)
@@ -85,7 +96,8 @@ defmodule Mv.ConfigSmtpTest do
       if path = Process.get(:smtp_password_file_path), do: File.rm(path)
     end
 
-    test "SMTP_PASSWORD overrides SMTP_PASSWORD_FILE when both are set" do
+    test "SMTP_PASSWORD overrides SMTP_PASSWORD_FILE in ENV-only mode when both are set" do
+      set_smtp_env("SMTP_HOST", "smtp.example.com")
       path = Path.join(System.tmp_dir!(), "mv_smtp_test_#{System.unique_integer([:positive])}")
       File.write!(path, "file-secret")
       Process.put(:smtp_password_file_path, path)

test/mv_web/live/global_settings_live_test.exs

@@ -124,6 +124,71 @@ defmodule MvWeb.GlobalSettingsLiveTest do
       {:ok, _view, html} = live(conn, ~p"/settings")
       assert html =~ "SMTP" or html =~ "E-Mail" or html =~ "Settings"
     end
+
+    @tag :ui
+    test "disables all SMTP inputs when SMTP_HOST is set", %{conn: conn} do
+      clear_smtp_env()
+      System.put_env("SMTP_HOST", "smtp.env-only.example")
+      on_exit(fn -> clear_smtp_env() end)
+
+      {:ok, view, _html} = live(conn, ~p"/settings")
+
+      assert has_element?(view, "#setting_smtp_host[disabled]")
+      assert has_element?(view, "#setting_smtp_port[disabled]")
+      assert has_element?(view, "#setting_smtp_ssl[disabled]")
+      assert has_element?(view, "#setting_smtp_username[disabled]")
+      assert has_element?(view, "#setting_smtp_password[disabled]")
+      assert has_element?(view, "#setting_smtp_from_email[disabled]")
+      assert has_element?(view, "#setting_smtp_from_name[disabled]")
+    end
+
+    @tag :ui
+    test "does not render SMTP save action when SMTP_HOST is set", %{conn: conn} do
+      clear_smtp_env()
+      System.put_env("SMTP_HOST", "smtp.env-only.example")
+      on_exit(fn -> clear_smtp_env() end)
+
+      {:ok, view, _html} = live(conn, ~p"/settings")
+      refute has_element?(view, "#smtp-form button", "Save SMTP Settings")
+    end
+
+    @tag :ui
+    test "shows explicit ENV-only mode hint when SMTP_HOST is set", %{conn: conn} do
+      clear_smtp_env()
+      System.put_env("SMTP_HOST", "smtp.env-only.example")
+      on_exit(fn -> clear_smtp_env() end)
+
+      {:ok, _view, html} = live(conn, ~p"/settings")
+      assert html =~ "SMTP is fully managed via environment variables"
+    end
+
+    @tag :ui
+    test "shows warning block for missing required SMTP ENV values in ENV-only mode", %{
+      conn: conn
+    } do
+      clear_smtp_env()
+      System.put_env("SMTP_HOST", "smtp.env-only.example")
+      on_exit(fn -> clear_smtp_env() end)
+
+      {:ok, _view, html} = live(conn, ~p"/settings")
+      assert html =~ "SMTP environment configuration appears incomplete"
+      assert html =~ "SMTP_USERNAME"
+      assert html =~ "SMTP_PASSWORD/SMTP_PASSWORD_FILE"
+    end
+
+    @tag :ui
+    test "does not enter ENV-only mode when SMTP_HOST is not set", %{conn: conn} do
+      clear_smtp_env()
+      System.put_env("SMTP_USERNAME", "leftover@example.com")
+      on_exit(fn -> clear_smtp_env() end)
+
+      {:ok, view, html} = live(conn, ~p"/settings")
+
+      refute html =~ "SMTP is fully managed via environment variables"
+      refute html =~ "SMTP environment configuration appears incomplete"
+      refute has_element?(view, "#setting_smtp_host[disabled]")
+      refute has_element?(view, "#setting_smtp_username[disabled]")
+    end
   end
 
   describe "Authentication section when OIDC-only is enabled" do