Self-Hosted Configuration

Logins

To enable logins in your instance of Password Pusher, you must have an SMTP server available to send emails through. These emails are sent for events such as password reset, unlock, registration etc..

To use logins, you should be running a database backed version of Password Pusher. Logins will likely work in an ephemeral setup but doesn’t make much sense given that data is wiped with every container restart.

All of the following environments need to be set (except SMTP authentication if none) for application logins to function properly.

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
PWP__ENABLE_LOGINS	On/Off switch for logins.	`false`
PWP__ALLOW_ANONYMOUS	When false, requires a login for the front page (to push new passwords). Secret URLs can still be accessed anonymously.	`true`
PWP__MAIL__RAISE_DELIVERY_ERRORS	Email delivery errors will be shown in the application	`true`
PWP__MAIL__SMTP_ADDRESS	Allows you to use a remote mail server. Just change it from its default “localhost” setting.	`smtp.domain.com`
PWP__MAIL__SMTP_PORT	Port of the SMTP server	`587`
PWP__MAIL__SMTP_USER_NAME	If your mail server requires authentication, set the username in this setting.	`smtp_username`
PWP__MAIL__SMTP_PASSWORD	If your mail server requires authentication, set the password in this setting.	`smtp_password`
PWP__MAIL__SMTP_AUTHENTICATION	If your mail server requires authentication, you need to specify the authentication type here. This is a string and one of :plain (will send the password in the clear), :login (will send password Base64 encoded) or :cram_md5 (combines a Challenge/Response mechanism to exchange information and a cryptographic Message Digest 5 algorithm to hash important information)	`plain`
PWP__MAIL__SMTP_STARTTLS	Use STARTTLS when connecting to your SMTP server and fail if unsupported.	`true`
PWP__MAIL__SMTP_ENABLE_STARTTLS_AUTO	Detects if STARTTLS is enabled in your SMTP server and starts to use it	`true`
PWP__MAIL__OPEN_TIMEOUT	Number of seconds to wait while attempting to open a connection.	`10`
PWP__MAIL__READ_TIMEOUT	Number of seconds to wait until timing-out a read(2) call.	`10`
PWP__HOST_DOMAIN	Used to build fully qualified URLs in emails. Where is your instance hosted?	`pwpush.com`
PWP__HOST_PROTOCOL	The protocol to access your Password Pusher instance. HTTPS advised.	`https`
PWP__MAIL__MAILER_SENDER	This is the “From” address in sent emails.	‘“Company Name” «user@example.com»’
PWP__DISABLE_SIGNUPS	Once your user accounts are created, you can set this to disable any further user account creation. Sign up links and related backend functionality is disabled when `true`.	`false`
PWP__SIGNUP_EMAIL_REGEXP	The regular expression used to validate emails for new user signups. This can be modified to limit new account creation to a subset of domains. e.g. `\A[^@\s]+@(hey\.com\\|gmail\.com)\z`. Tip: use https://rubular.com to test out your regular expressions. It includes a guide to what each component means in regexp.	`\A[^@\s]+@[^@\s]+\z`

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.

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