Password Pusher is highly customizable, allowing you to configure everything from defaults, features, branding, languages, and much more.

Overview

Password Pusher uses a centralized configuration system based on a settings.yml file. All settings can be configured using one of two methods:

  1. Environment Variables (recommended for most use cases) - Override settings via environment variables
  2. Custom settings.yml File - Replace the default configuration file with your own

Configuration Priority: Environment variables always take precedence over values in settings.yml. This allows you to use a base configuration file and override specific settings as needed.

Tip: For a few modifications, environment variables are the easiest route. For more extensive configuration, maintaining your own custom settings.yml file across updates is recommended.

Environment Variables

Environment variables are the recommended method for configuring Password Pusher. They provide flexibility, are easy to manage, and work well with containerized deployments.

Environment Variable Naming Convention

All Password Pusher configuration environment variables follow this pattern:

PWP__<SECTION>__<SUBSECTION>__<SETTING>

Key points:

  • Prefix: PWP__ (required)
  • Separator: __ (double underscore)
  • Case: Environment variables are case-insensitive and converted to lowercase
  • Nested settings: Use __ to represent nested YAML structure

Example mapping:

  • YAML: mail.smtp.address → Environment: PWP__MAIL__SMTP__ADDRESS
  • YAML: default_locale → Environment: PWP__DEFAULT_LOCALE

Setting Environment Variables

Docker Run

docker run -d \
  --env PWP__DEFAULT_LOCALE=fr \
  --env PWP__ENABLE_LOGINS=true \
  -p "80:80" -p "443:443" \
  pglombardo/pwpush:latest

Docker Compose

Add environment variables to your docker-compose.yml:

services:
  pwpush:
    image: docker.io/pglombardo/pwpush:stable
    environment:
      PWP__DEFAULT_LOCALE: 'fr'
      PWP__ENABLE_LOGINS: true
      PWP__THEME: 'Darkly'

Using .env File with Docker Compose

Create a .env file in the same directory as your docker-compose.yml:

PWP__DEFAULT_LOCALE=fr
PWP__ENABLE_LOGINS=true
PWP__THEME=Darkly
PWPUSH_MASTER_KEY=your-generated-key-here

Then reference it in docker-compose.yml:

services:
  pwpush:
    image: docker.io/pglombardo/pwpush:stable
    env_file:
      - .env

Note: The .env file is automatically loaded by Docker Compose, but explicitly listing it in env_file makes it clear and allows multiple files.

Docker Env File

For docker run, you can use a dedicated environment file:

Download pwpush-docker-env-file

Create or download the example file, add your environment variables, and pass it to Docker:

docker run -d \
  --env-file ./pwpush-docker-env-file \
  -p "80:80" -p "443:443" \
  pglombardo/pwpush:latest

Tip: Using an env file is especially useful when you have many environment variables to configure. See the Docker Environment File documentation for more details.

Shell/System Environment

For non-Docker deployments, set environment variables in your shell:

export PWP__DEFAULT_LOCALE='fr'
export PWP__ENABLE_LOGINS=true

Or in your system’s environment configuration (e.g., /etc/environment, systemd service files, etc.).

Common Configuration Examples

Change default language:

PWP__DEFAULT_LOCALE=fr

Enable user logins:

PWP__ENABLE_LOGINS=true

Set application theme:

PWP__THEME=Darkly

Configure SMTP for email:

PWP__MAIL__SMTP_ADDRESS=smtp.example.com
PWP__MAIL__SMTP_PORT=587
PWP__MAIL__SMTP_USER_NAME=username
PWP__MAIL__SMTP_PASSWORD=password

Enable file pushes:

PWP__ENABLE_FILE_PUSHES=true
PWP__FILES__STORAGE=local

For a complete list of available settings, see the settings.yml file in the repository.

Custom settings.yml File

If you prefer to manage configuration through a YAML file rather than environment variables, you can create a custom settings.yml file and mount it into the container.

Download Default Configuration

Download settings.yml

Download the default settings.yml file, modify it to your needs, and apply it to your container.

File Location in Container

Inside the Password Pusher Docker container:

  • Application code: /opt/PasswordPusher/
  • Configuration file: /opt/PasswordPusher/config/settings.yml

Mounting a Custom settings.yml File

Docker Run

Replace the default file with your custom version using a bind mount:

docker run -d \
  --mount type=bind,source=/path/to/your/settings.yml,target=/opt/PasswordPusher/config/settings.yml \
  -p "80:80" -p "443:443" \
  pglombardo/pwpush:latest

Docker Compose

services:
  pwpush:
    image: docker.io/pglombardo/pwpush:stable
    volumes:
      - type: bind
        source: /path/to/your/settings.yml
        target: /opt/PasswordPusher/config/settings.yml
    ports:
      - "80:80"
      - "443:443"

Benefits of Custom settings.yml

  • Version control: Keep your configuration in Git
  • Bulk changes: Easier to manage many settings at once
  • Documentation: Comments in YAML help document your choices
  • Consistency: Same configuration across all environments

Note: Even when using a custom settings.yml file, environment variables will still override any matching settings. This allows you to use a base configuration file and override specific values as needed.

Configuration Reference

The complete list of available configuration options is documented in the settings.yml file in the repository. Each setting includes:

  • Default value
  • Description
  • Environment variable override format
  • Example values

Finding Configuration Options

  1. Browse settings.yml: View the default settings file online
  2. Download settings.yml: Get a local copy to see all available options
  3. Check environment variable format: Look for comments showing the PWP__ environment variable format

Configuration Categories

Common configuration areas include:

  • Application Settings: Default language, timezone, host domain
  • Feature Flags: Enable/disable logins, file pushes, URL pushes, QR pushes
  • Email/SMTP: Mail server configuration for user authentication
  • File Storage: Local storage or S3 configuration
  • Theming: Choose from 26+ Bootswatch themes
  • Expiration Defaults: Default expiration times and view limits
  • Security: Encryption keys, allowed hosts, GDPR settings

Best Practices

Choosing a Configuration Method

Use Environment Variables when:

  • You have a few settings to change
  • You’re using Docker Compose or container orchestration
  • You want to keep configuration separate from code
  • You need different settings per environment (dev/staging/prod)

Use Custom settings.yml when:

  • You have many settings to configure
  • You want to version control your configuration
  • You prefer YAML syntax and comments
  • You want a single source of truth for configuration

Security Considerations

Never commit secrets to version control:

  • Use environment variables or secrets management for sensitive values
  • Keep .env files out of Git (add to .gitignore)
  • Use Docker secrets or external secret management for production

Recommended approach:

  • Store non-sensitive defaults in settings.yml or docker-compose.yml
  • Use environment variables or .env files for secrets (passwords, API keys)
  • Use Docker secrets or external secret management for production deployments

Managing Configuration Across Updates

When updating Password Pusher:

  1. Environment Variables: No changes needed - they continue to work
  2. Custom settings.yml: Review the default settings.yml for new settings or changes
  3. Backup: Always backup your configuration before major updates

See Also

Updated: