Self-Hosted Configuration

Application General

Environment Variable	Description	Default Value
PWP__SHOW_VERSION	Controls whether the version number is displayed in the footer	`true`
PWP__SHOW_GDPR_CONSENT_BANNER	Controls the display of the GDPR cookie consent banner	`true`
PWP__TIMEZONE	Sets the application-wide timezone using a valid timezone string (see note below)	`America/New_York`
SECRET_KEY_BASE	A secret key used for security features like session cookie encryption and other cryptographic operations. Generate a random key using `/opt/PasswordPusher/bin/pwpush secret`. See the SECRET_KEY_BASE documentation.	Randomly Generated on boot
TURBO_DRIVE_ENABLED	Controls Turbo Drive functionality. Useful when running behind proxy services or WAF configurations that may interfere with Turbo Drive	`true`
PWP__NO_WORKER	Disables the launch of background workers in the `pglombardo/pwpush` Docker container.	Not set

Tip: A list of valid timezone strings can be found at on Wikipedia.

Logins

To enable logins in your instance of Password Pusher, you must have an SMTP server available to send emails. These emails are sent for events such as password resets, account unlocks, and user registration.

To use logins, you should be running a database-backed version of Password Pusher. While logins may technically work in an ephemeral setup, it is not recommended since all data is wiped with each container restart.

All of the following environment variables must be set for application logins to function properly (except SMTP authentication if not required).

Note: As an alternative to environment variables which can become difficult to maintain, Password Pusher supports configuration via YAML file.

Environment Variable	Description	Default
PWP__ENABLE_LOGINS	Master switch to enable/disable logins.	`false`
PWP__ALLOW_ANONYMOUS	When false, requires a login to access the front page (for creating new pushes). Secret URLs remain accessible anonymously.	`true`
PWP__MAIL__RAISE_DELIVERY_ERRORS	Controls whether email delivery errors are displayed in the application.	`true`
PWP__MAIL__SMTP_ADDRESS	The address of your SMTP mail server (default is “localhost”).	`smtp.domain.com`
PWP__MAIL__SMTP_PORT	The port number of your SMTP server.	`587`
PWP__MAIL__SMTP_USER_NAME	Username for SMTP server authentication.	`smtp_username`
PWP__MAIL__SMTP_PASSWORD	Password for SMTP server authentication.	`smtp_password`
PWP__MAIL__SMTP_AUTHENTICATION	Type of SMTP authentication: `:plain` (password sent in clear text), `:login` (password Base64 encoded), or `:cram_md5` (Challenge/Response with MD5 hashing).	`plain`
PWP__MAIL__SMTP_STARTTLS	Requires STARTTLS when connecting to SMTP server.	`true`
PWP__MAIL__SMTP_ENABLE_STARTTLS_AUTO	Automatically detects and enables STARTTLS if supported by SMTP server.	`true`
PWP__MAIL__OPEN_TIMEOUT	Maximum seconds to wait when establishing connection.	`10`
PWP__MAIL__READ_TIMEOUT	Maximum seconds to wait for read operations.	`10`
PWP__HOST_DOMAIN	Domain name used to construct full URLs in emails.	`pwpush.com`
PWP__HOST_PROTOCOL	Protocol (HTTP/HTTPS) used to access your instance. HTTPS recommended.	`https`
PWP__MAIL__MAILER_SENDER	“From” address used in sent emails.	‘“Company Name” «user@example.com»’
PWP__DISABLE_SIGNUPS	When true, prevents new user account creation. Sign up functionality is completely disabled.	`false`
PWP__SIGNUP_EMAIL_REGEXP	Regular expression for validating email addresses during signup. Can be customized to restrict domains. Example: `\A[^@\s]+@(hey\.com\\|gmail\.com)\z`. Test expressions at https://rubular.com.	`\A[^@\s]+@[^@\s]+\z`
PWP__LOGIN_SESSION_TIMEOUT	Duration of user session inactivity before requiring re-authentication. Accepts values like “1 hour”, “2 hours”, “1 day”, “3 weeks”, “1 month”, “1 year”.	“2 hours”

Shell Example

export PWP__ENABLE_LOGINS=true
export PWP__MAIL__RAISE_DELIVERY_ERRORS=true
export PWP__MAIL__SMTP_ADDRESS=smtp.mycompany.org
export PWP__MAIL__SMTP_PORT=587
export PWP__MAIL__SMTP_USER_NAME=yolo
export PWP__MAIL__SMTP_PASSWORD=secret
export PWP__MAIL__SMTP_AUTHENTICATION=plain
export PWP__MAIL__SMTP_STARTTLS=true
export PWP__MAIL__OPEN_TIMEOUT=10
export PWP__MAIL__READ_TIMEOUT=10
export PWP__HOST_DOMAIN=pwpush.mycompany.org
export PWP__HOST_PROTOCOL=https
export PWP__MAIL__MAILER_SENDER='"Spiderman" <thespider@mycompany.org>'

Manually Adding Users

Generally you can use the Administration Dashboard to manage users through your browser but it is also possible to do this manually.

You can manually add users by opening an application console and running the following command:

User.create(email: 'user@example.com', password: 'mypassword', password_confirmation: 'mypassword')

This creates a new user account in the application ready to use.

Other Actions

To manually confirm an account:

user = User.find_by(email: 'user@example.com')
user.confirm

To send the user their confirmation instructions email:

user = User.find_by(email: 'user@example.com')
user.send_confirmation_instructions

To send a reset password insructions email:

user = User.find_by(email: 'user@example.com')
user.send_reset_password_instructions

To irrevocably delete a user:

user = User.find_by(email: 'user@example.com')
user.destroy

Warning: This is destructive and cannot be reversed. Make a backup of your database as a safety precaution.

Pushes

Text Pushes

The Push Expiration settings control the behavior of push expiration in your application. These settings are used to configure the default values and limits for expiration, as well as enable or disable features related to push deletion and retrieval.

The following environment variables are used to configure Push Expiration settings:

Environment Variable	Description	Default Value
PWP__PW__EXPIRE_AFTER_DAYS_DEFAULT	Controls the “Expire After Days” default value in Password#new	`7`
PWP__PW__EXPIRE_AFTER_DAYS_MIN	Controls the “Expire After Days” minimum value in Password#new	`1`
PWP__PW__EXPIRE_AFTER_DAYS_MAX	Controls the “Expire After Days” maximum value in Password#new	`90`
PWP__PW__EXPIRE_AFTER_VIEWS_DEFAULT	Controls the “Expire After Views” default value in Password#new	`5`
PWP__PW__EXPIRE_AFTER_VIEWS_MIN	Controls the “Expire After Views” minimum value in Password#new	`1`
PWP__PW__EXPIRE_AFTER_VIEWS_MAX	Controls the “Expire After Views” maximum value in Password#new	`100`
PWP__PW__ENABLE_DELETABLE_PUSHES	Can passwords be deleted by viewers? When true, passwords will have a link to optionally delete the password being viewed	`false`
PWP__PW__DELETABLE_PUSHES_DEFAULT	When the above is `true`, this sets the default value for the option.	`true`
PWP__PW__ENABLE_RETRIEVAL_STEP	When `true`, adds an option to have a preliminary step to retrieve passwords.	`true`
PWP__PW__RETRIEVAL_STEP_DEFAULT	Sets the default value for the retrieval step for newly created passwords.	`false`
PWP__PW__ENABLE_BLUR	Enables or disables the ‘blur’ effect when showing a push payload to the user.	`true`

Note: Remember that instead of environment variables, which can get hard to maintain, Password Pusher also supports configuration by YAML file.

File Pushes

To enable file uploads (File Pushes) in your instance of Password Pusher, there are a few requirements:

you must have logins enabled (see above)
specify a place to store uploaded files
If you use cloud storage, configure the CORS configuration in your buckets (detailed below)

The following settings enable/disable the feature and specify where to store uploaded files.

This feature can store uploads on local disk (not valid for Docker containers), Amazon S3, Google Cloud Storage or Azure Storage.

Note: Remember that instead of environment variables, which can get hard to maintain, Password Pusher also supports configuration by YAML file.

Environment Variable	Description	Value(s)
PWP__ENABLE_FILE_PUSHES	On/Off switch for File Pushes.	`false`
PWP__FILES__STORAGE	Chooses the storage area for uploaded files.	`local`, `amazon`, `google` or `microsoft`
PWP__FILES__ENABLE_BLUR	Enables or disables the ‘blur’ effect when showing a text payload to the user.	`true`
PWP__FILES__ENABLE_DELETABLE_PUSHES	Can passwords be deleted by viewers? When true, passwords will have a link to optionally delete the password being viewed	`false`
PWP__FILES__DELETABLE_PUSHES_DEFAULT	When the above is `true`, this sets the default value for the option.	`true`
PWP__FILES__ENABLE_RETRIEVAL_STEP	When `true`, adds an option to have a preliminary step to retrieve passwords.	`true`
PWP__FILES__RETRIEVAL_STEP_DEFAULT	Sets the default value for the retrieval step for newly created passwords.	`false`
PWP__FILES__MAX_FILE_UPLOADS	Sets the maximum number of files that can be added to a single push.	`10`
PWP__FILES__EXPIRE_AFTER_DAYS_DEFAULT	Controls the “Expire After Days” default value in Password#new	`7`
PWP__FILES__EXPIRE_AFTER_DAYS_MIN	Controls the “Expire After Days” minimum value in Password#new	`1`
PWP__FILES__EXPIRE_AFTER_DAYS_MAX	Controls the “Expire After Days” maximum value in Password#new	`90`
PWP__FILES__EXPIRE_AFTER_VIEWS_DEFAULT	Controls the “Expire After Views” default value in Password#new	`5`
PWP__FILES__EXPIRE_AFTER_VIEWS_MIN	Controls the “Expire After Views” minimum value in Password#new	`1`
PWP__FILES__EXPIRE_AFTER_VIEWS_MAX	Controls the “Expire After Views” maximum value in Password#new	`100`

Choosing a Backend Storage Mechanism

When files are attached to a push and uploaded to Password Pusher, they have to be stored somewhere publicly accessible. The four options are:

Local Disk
Amazon S3
Google Cloud
Microsoft Azure

The following sections explain how to configure each. Only one configuration can be active at any time.

Local Storage

PWP__FILES__STORAGE=local

The default location for local storage is ./storage.

If using containers and you prefer local storage, you can add a volume mount to the container at the path /opt/PasswordPusher/storage:

docker run -d -p "5100:5100" -v /var/lib/pwpush/files:/opt/PasswordPusher/storage pglombardo/pwpush:latest

Note: Please make sure that the directory is writeable by the docker container.

Note: A CORS configuration is not required for local storage.

Amazon S3

To configure the application to store files in an Amazon S3 bucket, you have to:

set the required environment variables detailed below (or the equivalent values in settings.yml)
apply a CORS configuration to your S3 bucket (see next section)

Environment Variable	Description	Value(s)
PWP__FILES__STORAGE	Storage Provider Selection	`amazon`
PWP__FILES__S3__ENDPOINT	S3 Endpoint	None
PWP__FILES__S3__ACCESS_KEY_ID	Access Key ID	None
PWP__FILES__S3__SECRET_ACCESS_KEY	Secret Access Key	None
PWP__FILES__S3__REGION	S3 Region	None
PWP__FILES__S3__BUCKET	The S3 bucket name	None

CORS Configuration

The application performs direct uploads from the browser to your Amazon S3 bucket. This provides better performance and reduces load on the application itself.

For this to work, you have to add a CORS configuration to your bucket.

This direct upload functionality is done using a library called ActiveStorage. For the full documentation on configuring CORS for ActiveStorage, see here.

[
  {
    "AllowedHeaders": [
      "Content-Type",
      "Content-MD5",
      "Content-Disposition"
    ],
    "AllowedMethods": [
      "PUT"
    ],
    "AllowedOrigins": [
      "https://www.example.com"  << Change to your URL
    ],
    "MaxAgeSeconds": 3600
  }
]

Google Cloud Storage

To configure the application to store files in Google Cloud Storage, you have to:

set the required environment variables detailed below (or the equivalent values in settings.yml)
apply a CORS configuration (see next section)

Environment Variable	Description	Value(s)
PWP__FILES__STORAGE	Storage Provider Selection	`google`
PWP__FILES__GCS__PROJECT	GCS Project	None
PWP__FILES__GCS__CREDENTIALS	GCS Credentials	None
PWP__FILES__GCS__BUCKET	The GCS bucket name	None

CORS Configuration

The application performs direct uploads from the browser to Google Cloud Storage. This provides better performance and reduces load on the application itself.

For this to work, you have to add a CORS configuration.

This direct upload functionality is done using a library called ActiveStorage. For the full documentation on configuring CORS for ActiveStorage, see here.

[
  {
    "origin": ["https://www.example.com"],
    "method": ["PUT"],
    "responseHeader": ["Content-Type", "Content-MD5", "Content-Disposition"],
    "maxAgeSeconds": 3600
  }
]

Azure Storage

To configure the application to store files in Azure Storage, you have to:

set the required environment variables detailed below (or the equivalent values in settings.yml)
apply a CORS configuration (see next section)

Environment Variable	Description	Value(s)
PWP__FILES__STORAGE	Storage Provider Selection	`microsoft`
PWP__FILES__AS__STORAGE_ACCOUNT_NAME	Azure Storage Account Name	None
PWP__FILES__AS__STORAGE_ACCESS_KEY	Azure Storage Account Key	None
PWP__FILES__AS__CONTAINER	Azure Storage Container Name	None

CORS Configuration

The application performs direct uploads from the browser to Azure Storage. This provides better performance and reduces load on the application itself.

For this to work, you have to add a CORS configuration.

This direct upload functionality is done using a library called ActiveStorage. For the full documentation on configuring CORS for ActiveStorage, see here.

<Cors>
  <CorsRule>
    <AllowedOrigins>https://www.example.com</AllowedOrigins>
    <AllowedMethods>PUT</AllowedMethods>
    <AllowedHeaders>Content-Type, Content-MD5, x-ms-blob-content-disposition, x-ms-blob-type</AllowedHeaders>
    <MaxAgeInSeconds>3600</MaxAgeInSeconds>
  </CorsRule>
</Cors>

URL Pushes

Similar to file pushes, URL pushes also require logins to be enabled.

Note: Remember that instead of environment variables, which can get hard to maintain, Password Pusher also supports configuration by YAML file.

Environment Variable	Description	Default Value
PWP__ENABLE_URL_PUSHES	On/Off switch for URL Pushes.	`false`
PWP__URL__EXPIRE_AFTER_DAYS_DEFAULT	Controls the “Expire After Days” default value in Password#new	`7`
PWP__URL__EXPIRE_AFTER_DAYS_MIN	Controls the “Expire After Days” minimum value in Password#new	`1`
PWP__URL__EXPIRE_AFTER_DAYS_MAX	Controls the “Expire After Days” maximum value in Password#new	`90`
PWP__URL__EXPIRE_AFTER_VIEWS_DEFAULT	Controls the “Expire After Views” default value in Password#new	`5`
PWP__URL__EXPIRE_AFTER_VIEWS_MIN	Controls the “Expire After Views” minimum value in Password#new	`1`
PWP__URL__EXPIRE_AFTER_VIEWS_MAX	Controls the “Expire After Views” maximum value in Password#new	`100`
PWP__URL__ENABLE_DELETABLE_PUSHES	Can passwords be deleted by viewers? When true, passwords will have a link to optionally delete the password being viewed	`false`
PWP__URL__DELETABLE_PUSHES_DEFAULT	When the above is `true`, this sets the default value for the option.	`true`
PWP__URL__ENABLE_RETRIEVAL_STEP	When `true`, adds an option to have a preliminary step to retrieve passwords.	`true`
PWP__URL__RETRIEVAL_STEP_DEFAULT	Sets the default value for the retrieval step for newly created passwords.	`false`

Password Generator

The Password Pusher password generator is a tool for creating strong, unique, and memorable passwords. This generator allows you to customize the password generation process through a set of environment variables, providing you with complete control over the output.

The following environment variables can be used to customize the password generation process:

Environment Variable	Description	Default Value
PWP__GEN__HAS_NUMBERS	Controls whether generated passwords have numbers	`true`
PWP__GEN__TITLE_CASED	Controls whether generated passwords will be title cased	`true`
PWP__GEN__USE_SEPARATORS	Controls whether generated passwords will use separators between syllables	`true`
PWP__GEN__CONSONANTS	The list of consonants to generate from	`bcdfghklmnprstvz`
PWP__GEN__VOWELS	The list of vowels to generate from	`aeiouy`
PWP__GEN__SEPARATORS	If `use_separators` is enabled above, the list of separators to use (randomly)	`-_=`
PWP__GEN__MAX_SYLLABLE_LENGTH	The maximum length of each syllable that a generated password can have	`3`
PWP__GEN__MIN_SYLLABLE_LENGTH	The minimum length of each syllable that a generated password can have	`1`
PWP__GEN__SYLLABLES_COUNT	The exact number of syllables that a generated password will have	`3`

By adjusting these environment variables, you can fine-tune the password generation process to suit your specific needs. For example, you can choose to exclude numbers, use a specific set of consonants and vowels, or control the length and number of syllables in the generated password.

Google Analytics

Environment Variable	Description
GA_ENABLE	The existence of this variable will enable the Google Analytics for the application. See `app/views/layouts/_ga.html.erb`.
GA_ACCOUNT	The Google Analytics account id. E.g. `UA-XXXXXXXX-X`
GA_DOMAIN	The domain where the application is hosted. E.g. `pwpush.com`

Throttling

Throttling enforces a minimum time interval between subsequent HTTP requests from a particular client, as well as by defining a maximum number of allowed HTTP requests per a given time period (per second, minute, hourly, or daily).

Environment Variable	Description	Default Value
PWP__THROTTLING__MINUTE	The maximum number of allowed HTTP requests per minute	`120`
PWP__THROTTLING__SECOND	The maximum number of allowed HTTP requests per second	`60`

Logging

Environment Variable	Description
PWP__LOG_LEVEL	Set the logging level for the application. Valid values are: `debug`, `info`, `warn`, `error` and `fatal`. Note: lowercase.
PWP__LOG_TO_STDOUT	Set to ‘true’ to have log output sent to STDOUT instead of log files. Default: `false`

Forcing SSL Links

Warning: This is a legacy setting and is no longer suggested for use. If using a proxy, make sure to have your proxy forward the X-Forwarded-Host, X-Forwarded-Port and X-Forwarded-Proto HTTP headers. See the “Proxies” section for more information and instructions.

Environment Variable	Description
FORCE_SSL	(Deprecated) The existence of this variable will set `config.force_ssl` to `true` and generate HTTPS based secret URLs

Application General

Logins

Shell Example

See Also

Manually Adding Users

Other Actions

Pushes

Text Pushes

File Pushes

Choosing a Backend Storage Mechanism

Local Storage

Amazon S3

Google Cloud Storage

Azure Storage

URL Pushes

Password Generator

Google Analytics

Throttling

Logging

Forcing SSL Links