Login sessions depend on a signing key that survives container replacement. Open WebUI uses WEBUI_SECRET_KEY for that purpose, and an explicit key lets a Docker Compose deployment keep users signed in when its container is recreated.

The standard container can generate a key in /app/backend/.webui_secret_key, outside the usual /app/backend/data volume. A protected environment file in the Compose project supplies the same value to each replacement container without printing it in the terminal.

This method fits a new deployment or an existing deployment whose active key is already saved in that environment file. Replacing an existing key invalidates login sessions and can make stored OAuth or MCP credentials unreadable when their encryption keys depend on it. A retained copy of the original key provides the recovery path; separately configured OAuth encryption keys must also remain unchanged.

Steps to set WEBUI_SECRET_KEY for Open WebUI with Docker Compose:

  1. Change into the Open WebUI Compose project directory.
    $ cd ~/open-webui
  2. Create a protected webui-secret.env file for a new deployment.
    $ python3 - <<'PYTHON'
    import os, secrets
    os.umask(0o077)
    with open("webui-secret.env", "x") as key_file:
        key_file.write("WEBUI_SECRET_KEY=" + secrets.token_hex(32) + "\n")
    PYTHON

    For an existing deployment, this step is skipped when webui-secret.env already contains its active key. An unknown generated key must be recovered before the container is replaced; generating a new value would rotate it. The command refuses to overwrite an existing file. The generated value goes straight into the file; it never appears in the command or terminal output.

  3. Restrict the key file to its owner.
    $ chmod 600 webui-secret.env

    The file belongs in private backups and outside version control. Anyone with access to the file or the Docker daemon can retrieve the key.

  4. Add webui-secret.env to the existing open-webui service in compose.yaml.
    compose.yaml
    services:
      open-webui:
        env_file:
          - webui-secret.env

    This fragment adds to the existing service, including its image, ports and /app/backend/data volume. It does not replace the full Compose file. The environment-file path is relative to compose.yaml.

  5. Remove any WEBUI_SECRET_KEY entry from that service's environment section.

    An environment entry overrides env_file, even when the entry is empty. If multiple environment files define the key, the last file wins. The retained active value must be the one in webui-secret.env before recreation.

  6. Validate the Compose configuration without displaying its resolved secrets.
    $ docker compose config --services
    open-webui

    The full output from docker compose config includes environment values, so it can disclose the key.

  7. Recreate the open-webui service with the protected key.
    $ docker compose up -d --force-recreate --wait open-webui

    The existing data volume stays attached. A Compose plugin supporting --wait waits for the container health check before returning.

  8. Confirm that the running key matches the protected file without displaying either value.
    $ docker compose exec -T open-webui python -c '
    import os, sys
    key = os.environ.get("WEBUI_SECRET_KEY", "")
    if not key or sys.stdin.read() != "WEBUI_SECRET_KEY=" + key + "\n":
        sys.exit("Key mismatch")
    print("Running key matches protected file")
    ' < webui-secret.env
    Running key matches protected file

    A mismatch returns a nonzero exit status and prints Key mismatch. A length check alone cannot establish that two keys are identical.

  9. Open the Open WebUI sign-in page in a separate signed-out browser window.

    A new deployment needs its initial account created before this session check. The browser window must stay open through the next container recreation.

  10. Enter the account email in the Email field.
  11. Enter the account password in the Password field.
  12. Select Sign in.
  13. Confirm that the chat workspace opens for the signed-in account.
  14. Recreate the service again with the same environment file.
    $ docker compose up -d --force-recreate --wait open-webui
  15. Compare the running key with the protected file again.
    $ docker compose exec -T open-webui python -c '
    import os, sys
    key = os.environ.get("WEBUI_SECRET_KEY", "")
    if not key or sys.stdin.read() != "WEBUI_SECRET_KEY=" + key + "\n":
        sys.exit("Key mismatch")
    print("Running key matches protected file")
    ' < webui-secret.env
    Running key matches protected file
  16. Reload the existing browser window to confirm that the session remains signed in.

    The chat workspace should reopen without another sign-in. A sign-in prompt after recreation indicates that the old session was lost; the key comparison must succeed before investigating session expiry or other authentication settings.

Share this guide