Open Source

The open source version of Password Pusher can be fully re-branded according to your company needs.

Re-branding consist of the following optional steps:

  1. Selecting a built in theme (or adding your own)
  2. Setting a custom title, tagline, disclaimer
  3. Setting an application logo

The documentation below outlines how to proceed with each option.

Note: This section describes branding for the open source version of Password Pusher. For branding in the Premium & Pro versions of Password Pusher, see those relevant sections.

Themes

Password Pusher supports 26 themes out of the box. These themes are bundled in Password Pusher but come from the great Bootswatch project and are licensed under the MIT License.

As such, themes mostly work although there may be a rare edge cases where fonts may not be clear or something doesn’t display correctly. If this is the case you can add custom CSS styles to fix any such issues. See the next section on how to add custom styling.

Cerulean Cosmo Cyborg Darkly Default Flatly Journal Litera Lumen Lux Materia Minty Morph Pulse Quartz Sandstone Simplex Sketchy Slate Solar Spacelab Superhero United Vapor Yeti Zephyr
The above themes are bundled into the open source edition of Password Pusher.

Setting a Theme

To specify a theme for your Password Pusher instance, you must set two environment variables:the PWP__THEME environment variable to specify the theme and PWP_PRECOMPILE=true environment variable to have CSS assets recompiled on container boot.

Warning: Make sure to set both PWP__THEME=<name> and PWP_PRECOMPILE=true for the selected theme to work. This will recompile assets on container boot with the new theme settings.

Environment Variable Description Possible Values
PWP__THEME Theme used for the application. ‘cerulean’, ‘cosmo’, ‘cyborg’, ‘darkly’, ‘flatly’, ‘journal’, ‘litera’, ‘lumen’, ‘lux’, ‘materia’, ‘minty’, ‘morph’, ‘pulse’, ‘quartz’, ‘sandstone’, ‘simplex’, ‘sketchy’, ‘slate’, ‘solar’, ‘spacelab’, ‘superhero’, ‘united’, ‘vapor’, ‘yeti’, ‘zephyr’
PWP_PRECOMPILE Forces a rebuild of the theme CSS on boot. true

Note: When setting a theme, you also have to set PWP_PRECOMPILE=true so that assets are re-compiled on boot. This can add 30-90 seconds to the boot process (depending on the system). Make sure to allow this time in your health checks before declaring the container as unresponsive.

Warning: Since the theme is a boot level selection, the theme can only be selected by setting the PWP__THEME environment variable (and not modifying settings.yml).

Example

So to set the quartz theme for a Docker container:

docker run --env PWP__THEME=quartz --env PWP_PRECOMPILE=true -p "5100:5100" pglombardo/pwpush:latest

or alternatively for source code:

export PWP__THEME=quartz
bin/pwpush asset:precompile # manually recompile assets
bin/pwpush server

Custom Themes

The PWP__THEME environment variable simply causes the application to load a css file from app/assets/stylesheets/themes/{$PWP__THEME}.css. If you were to place a completely custom CSS file into that directory, you could then set the PWP__THEME environment variable to the filename that you added.

For example:

Add app/assets/stylesheets/themes/mynewtheme.css and set PWP__THEME=mynewtheme.

This would cause that CSS file to be loaded and used as the theme for the site. Please refer to existing themes if you would like to author your theme for Password Pusher.

Remember that after the new theme is configured, assets must be precompiled again. See the the previous section for instructions

Password Pusher allows you to customize your instance with your own branding. You can set your own site title, tagline, and logo to match your organization’s identity.

Rebranding

To rebrand your instance, you can set the following environment variables:

Environment Variable Description Default Value
PWP__BRAND__TITLE Site title Password Pusher
PWP__BRAND__TAGLINE Site tagline Go Ahead. Email Another Password.
PWP__BRAND__DISCLAIMER Site disclaimer Undefined
PWP__BRAND__SHOW_FOOTER_MENU On/Off switch for footer menu true
PWP__BRAND__LIGHT_LOGO Site logo image for light theme logo-transparent-sm-bare.png
PWP__BRAND__DARK_LOGO Site logo image for dark theme logo-transparent-sm-bare.png

Image Paths

You can specify the paths to your logo images using either:

  1. Fully qualified HTTP(s) URLs, such as https://pwpush.fra1.cdn.digitaloceanspaces.com/dev/acme-logo.jpg (easiest)
  2. Relative paths that are mounted inside the container

Example

For the second option, you can mount a directory containing your logo images inside the container. For example, if you place your logo images in /var/lib/pwpush/logos/, you can mount that directory using the following command:

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

Alternatively, you can use a docker-compose.yml file to mount the directory:

volumes:
  # Example of a persistent volume for the storage directory (file uploads)
  - /var/lib/pwpush/logos:/opt/PasswordPusher/public/logos:ro

Once you have mounted the directory, you can set your LOGO environment variables (or settings.yml options) to point to your logo images. For example:

PWP__BRAND__LIGHT_LOGO=/logos/mylogo.png

Favicons

You can customize the application favicons by replacing the default icons with your own assets. Favicon icons are used in various places, including:

  • Browser tabs
  • Bookmarks
  • Browser history

To ensure proper functionality, we recommend setting at least two essential favicon sizes: icon_57x57 and icon_96x96. These sizes are critical for displaying correctly in various browsers and devices.

To create your own favicons, you can use online icon generators such as:

Environment Variables

Environment Variable Default Value
PWP__BRAND__ICON_57x57 apple-icon-57x57.png
PWP__BRAND__ICON_60x60 apple-icon-60x60.png
PWP__BRAND__ICON_72x72 apple-icon-72x72.png
PWP__BRAND__ICON_76x76 apple-icon-76x76.png
PWP__BRAND__ICON_114x114 apple-icon-114x114.png
PWP__BRAND__ICON_120x120 apple-icon-120x120.png
PWP__BRAND__ICON_144x144 apple-icon-144x144.png
PWP__BRAND__ICON_152x152 apple-icon-152x152.png
PWP__BRAND__ICON_180x180 apple-icon-180x180.png
PWP__BRAND__ICON_192x192 android-icon-192x192.png
PWP__BRAND__ICON_32x32 favicon-32x32.png
PWP__BRAND__ICON_96x96 favicon-96x96.png
PWP__BRAND__ICON_16x16 favicon-16x16.png
ms_icon_144x144 ms-icon-144x144.png

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

Custom CSS

Password Pusher supports adding custom CSS to the application. The application hosts a custom.css file located at app/assets/stylesheets/custom.css. This file is loaded last so it take precedence over all built in themes and styling.

This file can either be modified directly or in the case of Docker containers, a new file mounted over the existing one.

When changing this file inside a Docker container, make sure to set the precompile option PWP_PRECOMPILE=true. This will assure that the custom CSS is incorporated correctly.

An example Docker command to override that file would be:

docker run -e PWP_PRECOMPILE=true --mount type=bind,source=/path/to/my/custom.css,target=/opt/PasswordPusher/app/assets/stylesheets/custom.css -p 5100:5100 pglombardo/pwpush:latest

or the docker-compose.yml equivalent:

version: '2.1'
services:

  pwpush:
    image: docker.io/pglombardo/pwpush:latest
    ports:
      - "5100:5100"
    environment:
      PWP_PRECOMPILE: 'true'
    volumes:
      - type: bind
        source: /path/to/my/custom.css
        target: /opt/PasswordPusher/app/assets/stylesheets/custom.css

Warning: Remember that when applying custom CSS, this new CSS code has to be precompiled. Set the PWP_PRECOMPILE=true environment variable for your application. For source code, run bin/pwpush assets:precompile. This compilation process will incorporate the custom CSS into the updated site theme.

Premium

The Premium version of Password Pusher allows you to attach files to pushes and fully brand your Push delivery pages. These pages are:

  1. 1-Click Retrieval
  2. Passphrase
  3. Push Delivery
  4. Push Expired

Once you are subscribed to the Premium plan, you can then access the Branding configuration page:

From there you can configure and customize all of the Push pages according to your needs. Below is an example of a customized push delivery page.

For more screenshots of the features included with the Premium plan, see the Pipeline: New Features page.

Pro

Custom Domain

As a Pro subscriber, you can work in teams and deliver pushes with a custom company or organization domain. This feature allows you to further customize your pushes, improve end user confidence and enhance your brand identity.

Adding a Custom Domain

To add a custom domain, navigate to the account edit page and look for the option to add a custom domain. Enter only the fully qualified domain name without the protocol or path.

For this documentation, we’ll use the example pwp.yourdomain.com. This is a custom top level domain with a subdomain dedicated to Password Pusher.

Configuring DNS

Before your custom domain can be used, you must configure the DNS settings for your domain to point to domain.pwpush.com with an ALIAS or CNAME record - either will work. This will ensure that your pushes are delivered correctly.

The following screenshot is of a correctly created ALIAS record:

Custom domain with ALIAS record
Custom domain with an ALIAS record.

This is another example but with a CNAME record instead:

Custom domain with CNAME record
Custom domain with an CNAME record.

Not all DNS providers support ALIAS records. In such cases use a CNAME record instead. Either will work but use only one or the other.

Note: It can take up to 24 hours for the DNS settings to propagate. Once you have configured the DNS settings, you can test the domain by visiting https://pwp.yourdomain.com/up in your browser.

Testing Your Domain

Once you have your DNS record setup and the new DNS record has propagated, you can enter your custom domain in your browser and append the path /up to test the setup.

https://pwp.yourdomain.com/up

Upon success, you will see a green screen as follows:

This green screen signals that DNS (and SSL/TLS) has been properly configured and is ready for use.

SSL/TLS

The SSL/TLS setup and configuration is automatic - no steps are required by you. The Password Pusher servers uses Let’s Encrypt to generate automatic SSL certificates for your custom domain.

The green screen shown in the previous section also indicates a successful SSL/TLS connection using your custom domain.

Note: If you have any issues, questions or problems, feel free to contact me anytime.

Updated: