This article applies to: Self-Hosted

Process Overview

Password Pusher can be installed in the cloud or on bare bones metal.

The process of installing and deploying Password Pusher generally include the following steps:

1. Identify a hosting location, platform or cloud service

2. Choose a Deployment Strategy

3. Chose your preferred database backend

4. Optional: Setup SSL/TLS

5. Optional: Enable the Administration Dashboard

6. Optional: Segmented Feature Set

7. Optional: Configure The Application

All-In-One With Automatic SSL/TLS

If you want to self-host Password Pusher, a common obstacle is setting up SSL in front of Password Pusher.

We now offer an all in one Docker Compose example of hosting Password Pusher and CaddyServer. This setup allows you to launch a Password Pusher instance with automatic SSL/TLS certificate management thanks to Caddy Server & Let’s Encrypt.

Info: Caddy is a proxy that when given a domain, will automatically fetch, update & monitor TLS certificates for that domain in tandem with Let’s Encrypt.

Prerequisites

Before you can run the Password Pusher instance with automatic SSL/TLS certificate management using Caddy server and Let’s Encrypt, you will need to ensure that you have the following prerequisites installed and configured on your system:

  • Docker: You will need to have Docker installed and running on your system. Docker is a containerization platform that allows you to run applications in isolated environments. You can download and install Docker from the official Docker website.
  • Docker Compose: You will also need to have Docker Compose installed on your system. Docker Compose is a tool that allows you to define and run multi-container Docker applications. You can download and install Docker Compose from the official Docker website.

Additionally, you will need to have a basic understanding of how to use the command line and Docker commands.

Instructions

Step 1 - Download

Download the docker-compose-pwpush.yml and Caddyfile files:

Download docker-compose-pwpush.yml Download Caddyfile

Step 2 - Save

Save and put the files into a new directory to keep them together.

Note: Customize the files as needed. The files contain documentation on how to further configure Password Pusher for your needs.

mkdir pwpush-all-in-one
cd pwpush-all-in-one
cp ~/Downloads/docker-compose-pwpush.yml .
cp ~/Downloads/Caddyfile .

Step 3 - Caddyfile

Open the Caddyfile and customize according to instructions:

{
  # Global options block
  email user@example.com  # Replace with your email for Let's Encrypt notifications
  acme_ca https://acme-v02.api.letsencrypt.org/directory  # Use Let's Encrypt production API
}

example.com { # Replace with your domain
  reverse_proxy pwpush:5100

  ...<snip>...
}

Step 4 - Compose

Open the docker-compose-pwpush.yml and customize according to instructions.

Step 5 - Launch

Run the docker compose command to launch the application:

docker-compose -f docker-compose-pwpush.yml

Step 6 - Access

Access your site at https://examle.com (or the domain you added to the `Caddyfile’).

Storage Backends

Password Pusher supports three types of backend databases:

  1. SQLite3 (Ephemeral) - Easiest to launch/maintain. All data is lost on container restart.
  2. PostgreSQL
  3. MariaDB
  4. MySQL

Which database to use is specified by passing the DATABASE_URL environment variable to the Docker container. For details on DATABASE_URL, see the related section under Configuration.

Note: Password Pusher also supports file uploads which require backend configuration of file storage. See the the File Pushes section for more details on configuring this feature.

Here is an expanded and improved version of the documentation:

Docker

The Password Pusher Docker image (pglombardo/pwpush) is available on Docker hub and is built for the linux/amd64 and linux/arm64 platforms.

This image provides a convenient way to run Password Pusher in a containerized environment, allowing you to easily manage and deploy your application.

See Also: For organizations seeking to maintain even greater application security, Password Pusher also provides a public gateway container image that offers a secure, limited interface for push delivery only. This allows you to limit access to the full application while still enabling external users to receive pushes. Learn more about the Public Gateway’s feature segmentation here.

Images

Tags Reference

Password Pusher is updated frequently, and the Docker image is updated accordingly. Below is a reference guide to the different tags used in the release process:

Tag Purpose
vX.X.X Versioned tags, where X.X.X represents the version number of the release.
stable The most stable tag for proven releases, which have been thoroughly tested and validated.
latest The latest (most recent) released version, which may include new features and bug fixes.
nightly The nightly development build, which includes the latest changes and may not be fully tested.

If you’re unsure which tag to use, we recommend starting with the latest or stable tag, as they are the most well-tested and reliable options.

Examples

Ephemeral

The ephemeral example demonstrates how to run a temporary Password Pusher instance with a database that is wiped on each restart. This is useful for testing or development purposes.

Secure Data Sharing: This instance can be used as a convenient and secure way to share sensitive information, such as at conferences, meetups, or other events. By shutting down and securely deleting the container, you can ensure that no trace of the shared data is left behind, providing an added layer of security and confidentiality.

docker run -d -p "5100:5100" pglombardo/pwpush:latest

Tip: See also this discussion if you want to persist data across container restarts: How to Add Persistence? (Since this link refers to an outdated ephemeral image keep in mind to use current image pglombardo/pwpush)

Postgres Backend

The Postgres example demonstrates how to run a Password Pusher instance with a Postgres database backend.

docker run -d -p "5100:5100" pglombardo/pwpush:latest -e DATABASE_URL=postgres://pwpush_user:pwpush_passwd@postgres:5432/pwpush_db

Better Security with Password Files

Providing a PostgreSQL password on the command line such as in the preceding is less than ideal. The Postgres Docker image also supports the idea of password files.

See the Docker Secrets documentation on how to avoid passing credentials on the command line.

Tip: Also consider this example provided by Viajaz or using a Docker environment file.

MariaDB (MySQL) Backend

The MariaDB example demonstrates how to run a Password Pusher instance with a MariaDB database backend.

docker run -d -p "5100:5100" pglombardo/pwpush:latest -e DATABASE_URL=mysql2://pwpush_user:pwpush_passwd@mysql:3306/pwpush_db

Important: When running Password Pusher with a database backend, it’s important to note that putting passwords in a command line is a security risk. Instead, consider using environment variables or a secure configuration file to store your database credentials.

Additional Options

Here are some additional options you can use when running Password Pusher with Docker:

  • -p <port>:<port>: Maps a port from the container to your host machine.
  • -e <environment_variable>=<value>: Sets an environment variable for the container.
  • -d: Runs the container in detached mode, allowing you to continue using your terminal.

Troubleshooting

If you encounter any issues when running Password Pusher with Docker, you can try the following troubleshooting steps:

  • Check the container logs using docker logs <container_id>.
  • Verify that the database connection is working correctly by checking the database logs.
  • Try running the container with the --rm flag to remove the container when it exits.

By following these examples and guidelines, you should be able to successfully run Password Pusher with Docker and take advantage of its many features and benefits.

See Also

Docker Compose

Password Pusher can be easily launched and managed using Docker Compose, a great tool for defining and running multi-container Docker applications. This section provides examples of how to use Docker Compose to launch Password Pusher with different database backends.

Getting Started

To use Docker Compose with Password Pusher, you’ll need to download the relevant configuration file and then start the containers. Here’s a step-by-step guide:

  1. Download the desired configuration file in the next sections.
  2. Start the containers in detached mode using docker compose up -d. This will launch the containers in the background and allow you to continue using your terminal.

Configuration Files

The configuration files used by Docker Compose are available on the Password Pusher GitHub repository. Each file defines the services and dependencies required to run Password Pusher with a specific database backend.

Ephemeral Backend

The docker-compose-ephemeral.yml file defines a service for the Postgres database and another service for the Password Pusher application. This configuration uses the official Postgres image and sets the database password to password.

Download docker-compose-ephemeral.yml

Postgres Backend

The docker-compose-postgres.yml file defines a service for the Postgres database and another service for the Password Pusher application. This configuration uses the official Postgres image and sets the database password to password.

Download docker-compose-postgres.yml

MariaDB Backend

The docker-compose-mariadb.yml file defines a service for the MariaDB database and another service for the Password Pusher application. This configuration uses the official MariaDB image and sets the database password to password.

Download docker-compose-mariadb.yml

MySQL Backend

The docker-compose-mysql.yml file defines a service for the MariaDB database and another service for the Password Pusher application. This configuration uses the official MariaDB image and sets the database password to password.

Download docker-compose-mysql.yml

Tips and Variations

  • To stop the containers, use docker compose stop.
  • To restart the containers, use docker compose restart.
  • To view the logs, use docker compose logs.
  • You can customize the configuration files to suit your specific needs. For example, you can change the database password or add additional services.

By following these examples and tips, you should be able to successfully launch and manage Password Pusher using Docker Compose.

Kubernetes

Instructions and explanation of a Kubernetes setup can be found here.

Helm Charts

A basic helm chart with instructions can be found here.

Microsoft Azure

There used to be a 3rd party blog post with instructions but it’s been deleted. If anyone has instructions they would like to contribute, it would be greatly appreciated.

See issue #277

Heroku

One click deploy to Heroku Cloud without having to set up servers.

Deploy

Warning: This option will deploy a production Password Pusher instance backed by a postgres database to Heroku. Heroku used to offer free dynos but that is no longer the case from November 28, 2022. Hosting charges will be incurred.

PikaPods

One click deploy to PikaPods from $1/month. Start free with $5 welcome credit.

Run on PikaPods

Nginx

Password Pusher can be run behind an Nginx reverse proxy server to provide an additional layer of security and scalability. This guide will walk you through the steps to set up Password Pusher with Nginx.

Prerequisites

  • Password Pusher installed and running
  • Nginx installed and configured
  • A domain name or subdomain pointing to your Nginx server

Step 1: Configure Nginx

Download the example nginx.conf file.

Download nginx.conf

This configuration sets up Nginx to listen on port 80 and proxy requests to http://pwpush:5100, which is the default port used by Password Pusher.

Step 2: Configure Docker Compose

Download the example docker-compose-nginx.yml file.

Download docker-compose-nginx.yml

This file tells Docker Compose to launch Password Pusher with nginx and points out the nginx.conf file.

Step 4: Start Password Pusher

Start the Password Pusher server by running the following command:

docker-compose up -d

This will start the Password Pusher server in detached mode.

Step 5: Test the Setup

Open a web browser and navigate to http://127.0.0.1. You should see the Password Pusher front page.

Tips and Variations

  • You can customize the Nginx configuration to suit your specific needs. For example, you can add additional security measures such as SSL/TLS encryption or rate limiting.
  • You can also use environment variables to pass configuration options to the Password Pusher server.

See Also

From Source

I generally don’t suggest building this application from source code for casual use. The is due to the complexities in the tool set across platforms. Running from source code is best when you plan to develop the application.

For quick and easy, use the Docker containers instead.

But if you’re resolute & brave, continue on!

Dependencies

  • Ruby 3.0 or greater
  • Recent Node.js stable & Yarn
  • Compiler tools: gcc g++ make
  • Other: git

SQLite3 backend

  • Make sure to install sqlite3 development libraries: apt install libsqlite3-dev sqlite3
git clone git@github.com:pglombardo/PasswordPusher.git
cd PasswordPusher
gem install bundler

bundle config set --local deployment 'true'
bundle install --without development production test
./bin/pwpush assets:precompile
./bin/pwpush db:setup
./bin/pwpush server

Then view the site @ http://localhost:5100/.

Postgres, MySQL or Mariadb backend

  • Make sure to install related database driver development libraries: e.g. postgres-dev or libmariadb-dev
git clone git@github.com:pglombardo/PasswordPusher.git
cd PasswordPusher
gem install bundler

export RAILS_ENV=production

# Update the following line to point to your Postgres (or MySQL/Mariadb) instance
DATABASE_URL=postgresql://passwordpusher_user:passwordpusher_passwd@postgres:5432/passwordpusher_db

bundle install --without development test
./bin/pwpush assets:precompile
./bin/pwpush db:setup
./bin/pwpush server --environment=production

Then view the site @ http://localhost:5100/.

Updated: