Configuration Strategies

How to configure self-hosted Password Pusher: recommended path, env vars, and when to use settings.yml.

This article applies to: OSS Self-Hosted

Which path should I use?

Your situation What to do
Typical self-hosted install Use docker-compose.yml and edit the environment block. Easiest and most supported.
Kubernetes / Helm Use the Helm chart or pass the same PWP__... vars into your deployment.
Render, Fly.io, Railway, DigitalOcean Apps Use the repo’s blueprint/spec files (see Installation) and set secrets in the platform UI.
Large YAML in Git, or legacy 1.x file You can still mount a custom settings.yml; env vars always override YAML when both are set. Prefer moving new options to env over time.
Upgrading from 1.x Read the upgrade guide—some old settings are removed; compose documents the current names.

Rule of thumb: If you’re not sure, stay on docker-compose + env vars. Custom settings.yml is optional, not required.

Recommended path: docker-compose + env vars

  1. Download or clone the repo’s docker-compose.yml (or keep a copy beside your install).
  2. Uncomment and set only the variables you need. The file lists TLS, database, anonymous vs login policy, file pushes, mail, and more with short comments.
  3. Run docker compose up -d as in the installation guide.

New releases add or change options in that file first, so upgrades are straightforward. You don’t need a separate YAML file unless you choose to.

Without TLS in the container: If you don’t set TLS_DOMAIN, the app is available on port 5100 over HTTP (see Installation Quick Start).

How environment variables work

  • Prefix: PWP__ (double underscore between segments).
  • Nesting: YAML keys become segments—e.g. mail.smtp.address → PWP__MAIL__SMTP__ADDRESS.
  • Priority: Env always wins over values in settings.yml.

Example:

# In docker-compose.yml under services.pwpush.environment:
PWP__DEFAULT_LOCALE: 'fr'
PWP__THEME: 'Darkly'

For many variables at once, use an env file (see Docker environment file) and reference it with env_file: in compose. Never commit secrets—use .gitignore and platform secrets for production.

Full list of keys and defaults: config/settings.yml in the repo (each block shows the matching PWP__... form in comments where applicable).

Optional: custom settings.yml

Still supported: bind-mount your file to /opt/PasswordPusher/config/settings.yml inside the container. Env vars continue to override.

Use this when you already maintain a big commented YAML file or need one file shared across environments (with secrets still in env). For new installs, starting from compose only is simpler.

Mount example (Compose):

volumes:
  - type: bind
    source: /path/to/your/settings.yml
    target: /opt/PasswordPusher/config/settings.yml

Download a default settings.yml as a starting point if you go this route.

Security and upgrades (short)

  • Secrets: Keep PWPUSH_MASTER_KEY, SMTP passwords, and similar values out of Git—use env, .env (ignored), or your platform’s secret store.
  • Upgrades: After pulling a new image, check the upgrade guide and the latest docker-compose.yml for renamed or removed settings. Back up the database and config before major updates.

See also