This article applies to: Self-Hosted

Overview

The quickest way to run Password Pusher is to use one of the prepared Docker Compose files.

Detailed Installation Steps

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: Enable the Administration Dashboard

5. Optional: Segmented Feature Set

6. Optional: Configure The Application

Storage Backends

Password Pusher supports three types of backend databases:

  1. SQLite3 (Ephemeral) - All data is lost on container restart.
  2. PostgreSQL - Default
  3. MariaDB
  4. MySQL

Which database to use is specified by passing the DATABASE_URL environment variable to the Docker container.

Lean more about DATABASE_URL here.

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.

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.

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 "80:80" -p "443:433" pglombardo/pwpush:latest

Tip: If you want 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.

Postgres Backend

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

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

Tip: If you want 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.

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 "80:80" -p "443:443" -e DATABASE_URL=mysql2://pwpush_user:pwpush_passwd@mysql:3306/pwpush_db pglombardo/pwpush:latest

Tip: If you want 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.

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.

Tip: After downloading your chosen Docker Compose file, open it in a text editor to review and customize settings such as environment variables, ports, and service options to best fit your deployment needs

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

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

Thanks to Matt Gosnell for graciously providing this documentation!

Other

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

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

Synology NAS

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

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

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 an 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 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

Updated: