This article applies to: Self-Hosted

⚡️ Quick Start

Run your own instance with Docker Compose

The recommended way to run Password Pusher is using the provided docker-compose.yml file, which includes persistent database storage, health checks, and is production-ready out of the box.

Steps:

  1. Setup a DNS record to point to your server (e.g. pwpush.example.com)
  2. Clone this repository or download docker-compose.yml
  3. Uncomment and set TLS_DOMAIN: 'pwpush.example.com' in docker-compose.yml
  4. Run:
docker compose up -d

Browse to https://pwpush.example.com - your TLS certificate will be automatically provisioned via Let’s Encrypt.

What’s included:

  • Persistent SQLite database (stored in Docker volumes)
  • Automatic TLS certificate provisioning
  • Health checks
  • Production-ready configuration

For more details on Docker installation options, see the Docker section below.

Docker

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

Images

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.

Image Tags

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

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. Recommended for production.
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. Not recommended for production.

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

Installation Methods

The docker-compose.yml file provides the easiest and most complete setup. See the Quick Start section above for instructions.

Docker Run (Alternative)

For quick testing or when you don’t need persistent storage, you can use docker run directly.

Ephemeral Instance

Run a temporary Password Pusher instance with a database that is wiped on each restart. Useful for testing, development, or temporary use cases like conferences and meetups.

docker run -d -p "80:80" -p "443:443" pglombardo/pwpush:latest

Tip: For automatic TLS certificate management, setup a DNS record that points to your server and set the TLS_DOMAIN environment variable: -e TLS_DOMAIN=pwpush.example.com.

PostgreSQL Backend

Run Password Pusher with a PostgreSQL database backend:

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

Tip: For automatic TLS certificate management, setup a DNS record that points to your server and set the TLS_DOMAIN environment variable: -e TLS_DOMAIN=pwpush.example.com.

Security Note: Providing a PostgreSQL password on the command line is not ideal. Consider using:

Storage Backends

Password Pusher supports multiple database backends:

  • SQLite3 (default) - Persistent database stored in Docker volumes. Perfect for single-server deployments.
  • PostgreSQL - Use when you need a more robust database solution or are running in a distributed environment.

The database backend is specified via the DATABASE_URL environment variable. Learn more about DATABASE_URL here.

Troubleshooting

If you encounter any issues when running Password Pusher with Docker:

  • Check the container logs: docker logs <container_id> or docker compose logs
  • Verify that the database connection is working correctly by checking the database logs
  • Ensure ports 80 and 443 are not already in use on your host system
  • For docker-compose, verify your docker-compose.yml configuration is correct

Other Installation Options

Password Pusher can be installed in various cloud platforms and orchestration systems.

Cloud Platforms

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

Microsoft Azure

To install into Microsoft Azure, please refer to this user contributed documentation.

Thanks to Matt Gosnell for graciously providing this documentation!

There also has been some discussion about Azure installations in this Github issue.

Orchestration Platforms

Kubernetes

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

Helm Charts

A basic helm chart with instructions can be found here.

Terraform Provider

Deploy Password Pusher using infrastructure as code with the Terraform Provider.

Hardware Platforms

Synology NAS

David Andé has graciously put together instructions on how to install into a Synology NAS through the container manager.

The documentation can be found here: https://github.com/davidande/passwordpusher_docker_synology

Advanced Configurations

Nginx Reverse Proxy

Password Pusher can be run behind an Nginx reverse proxy server to provide an additional layer of security and scalability. This is useful when you want to use Nginx for SSL/TLS termination, rate limiting, or other advanced features.

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 HTTP port offered by the Password Pusher Docker container.

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 references the nginx.conf file.

Step 3: 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 4: 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

Public Gateway

For organizations seeking to maintain even greater application security, Password Pusher 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.

See the Public Gateway documentation for more information on feature segmentation and setup.

Next Steps

After installation, you may want to configure additional features:

For a complete list of configuration options, see the documentation sidebar.

Updated: