OSS Self-Hosted Installation

Instructions for installing Password Pusher in the cloud and on hardware.

This article applies to: OSS 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.

Note: If you do not set TLS_DOMAIN, the application is still available over HTTP on port 5100 (e.g. http://your-server-ip:5100). Use that for quick tests or when terminating TLS elsewhere; set TLS_DOMAIN when you want automatic Let’s Encrypt on 80/443 inside the container.

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

DigitalOcean App Platform

The repo includes a DigitalOcean app spec (.do/deploy.template.yaml) for App Platform: web service, optional post-deploy job for db:prepare, database linkage, and placeholders for secrets. Use it as a template—replace placeholder secrets and align the GitHub source branch/repo with your fork if applicable.

Steps (summary):

  1. In the DigitalOcean control panel, create an app from GitHub and paste or import the spec, or use doctl with the template.
  2. Set SECRET_KEY_BASE, PWPUSH_MASTER_KEY, and DATABASE_URL (or use a managed DB component) in the app’s environment; do not commit real secrets.
  3. Review run command and env names so they match your image (spec comments point to the same patterns as docker-compose.yml).

Fly.io

Deploy using the repo’s fly.toml and the production Dockerfile at containers/docker/Dockerfile.

Steps (summary):

  1. Install the Fly CLI and run fly launch --no-deploy --dockerfile containers/docker/Dockerfile from the repo (set app name in fly.toml or when prompted).
  2. Set secrets, e.g. fly secrets set SECRET_KEY_BASE="..." PWPUSH_MASTER_KEY="..." (generate values locally if needed).
  3. Attach or set DATABASE_URL (e.g. fly postgres create then attach).
  4. fly deploy. The image entrypoint runs db:migrate then Foreman (web + worker by default). For web only, set PWP__NO_WORKER=1 via fly secrets set.

Further configuration: Default PWP__... env vars are in fly.toml; override in the Fly dashboard or secrets as needed.

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.

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.

PikaPods

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

Run on PikaPods

Railway

railway.toml in the repo sets the builder to Dockerfile with dockerfilePath = "containers/docker/Dockerfile". The container entrypoint runs migrations then Foreman (web + worker unless you set PWP__NO_WORKER=1).

Steps (summary):

  1. railway init (or connect the repo in the Railway dashboard).
  2. Add a PostgreSQL plugin (or set DATABASE_URL).
  3. In the service variables, set SECRET_KEY_BASE, PWPUSH_MASTER_KEY, and any PWP__... overrides (Railway config-as-code does not define arbitrary env in railway.toml; use the dashboard for secrets).
  4. Deploy; optionally set healthcheck path to /up in the service settings.

Further configuration: See Railway build/deploy docs and the self-hosted configuration guide.

Render

The OSS repository includes a Render Blueprint (render.yaml) you can use to deploy a web service plus PostgreSQL. It sets a sensible default env block (PWP__ALLOW_ANONYMOUS, push toggles, etc.), uses preDeployCommand: bundle exec rails db:prepare, and health-checks /up.

Steps (summary):

  1. Connect the PasswordPusher repo to Render.
  2. Create a Blueprint and select render.yaml, or use the Render CLI (render blueprint apply).
  3. In the dashboard, set secrets: SECRET_KEY_BASE and PWPUSH_MASTER_KEY (generate; do not commit).
  4. Adjust plans/regions in the YAML if needed. Optional: add a worker service running bundle exec rake solid_queue:start if you want Solid Queue on a separate dyno.

Further configuration: All PWP__... options are documented in docker-compose.yml. Upgrading from 1.x? See the upgrade guide.

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.