Self-Hosted Installation
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
- Docker Containers
- Docker Compose
- Kubernetes / Helm Charts
- A Cloud Platform (Heroku, App Platform, PikaPods or other)
- From Source (Not Recommended)
3. Chose your preferred database backend
4. Optional: Setup SSL/TLS
- All-in-One Installation with Automatic SSL/TLS
- Custom SSL with Nginx, Apache or others
5. Optional: Enable the Administration Dashboard
6. Optional: Segmented Feature Set
- See the Public Gateway for External Push Delivery
7. Optional: Configure The Application
- Enable Logins and Email
- File Uploads
- …and much more. See left sidebar.
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://example.com
(or the domain you added to the `Caddyfile’).
Storage Backends
Password Pusher supports three types of backend databases:
- SQLite3 (Ephemeral) - All data is lost on container restart.
- PostgreSQL - Default
- MariaDB
- 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.
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:
- Download the desired configuration file in the next sections.
- 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
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.
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.
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.
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
- This great Youtube video by sass drew on how to setup Password Pusher with nginx.
- All-In-One setup with pre-configured SSL/TLS
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.3 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/.