Password Management Appliance
An Open Source Appliance from Robbie Ferguson
A hardened, self-hosted password manager appliance based on Vaultwarden. Designed for secure deployment in business or personal environments.
✅ Features
- 🛡️ Fully self-hosted on Debian 12
- 🔐 Vaultwarden (Bitwarden-compatible)
- 💾 MariaDB backend
- 🧠 Supports .env override system via web-based setup
- 🌐 NGINX reverse proxy + PHP-based first-time setup wizard
- 🔑 Multi-user access, browser extensions, mobile app compatibility
📂 Important File Paths
| Path | Purpose |
|---|---|
/opt/vaultwarden/.env |
Core Vaultwarden environment settings |
/var/lib/vaultwarden/.env.user |
User-defined config written via the setup wizard |
/var/lib/vaultwarden/.setup-complete |
Flag file that disables the setup wizard after first-time config |
/opt/vaultwarden/.env.merged |
Combined environment used by the wrapper |
/usr/local/bin/vaultwarden |
Vaultwarden binary |
/usr/local/bin/vaultwarden-wrapper |
Wrapper that merges .env and .env.user |
/etc/systemd/system/vaultwarden.service |
Systemd unit to manage Vaultwarden as a service |
/var/www/html/setup/ |
First-time setup wizard served via PHP |
/var/www/html/vaultinfo/index.html |
Installer-complete welcome page served on / |
🚀 Installation
On a fresh Debian 12 system, clone the password-manager repository and then run:
./installer.sh
After installation:
- Access the appliance at
http://<your-appliance-ip>/ - Go to
/setupto complete first-time configuration - After submitting the form, Vaultwarden will use your custom settings
🧠 Configuration Flow
- Installer creates
/opt/vaultwarden/.env(default config) - User config is stored via
/setupin/var/lib/vaultwarden/.env.user vaultwarden-wrappermerges both files into.env.merged- Systemd launches Vaultwarden using the wrapper
🔁 To Re-run Setup
To prevent a bad actor from modifying your configuration by re-running the /setup tool, a file .setup-complete is created to tell the system to no longer allow the configuration to be saved. You can, if needed, delete the .setup-complete file to re-run the configuration:
rm /var/lib/vaultwarden/.setup-complete
Then visit /setup in your browser again.
🖥️ System Requirements
To successfully build and run the Password Management Appliance, your system must meet the following minimum requirements:
Minimum Requirements (suitable for testing and light use)
- Operating System: Debian 12 (Bookworm) x86_64
- CPU: Dual-core processor (2 vCPUs)
- RAM: 4 GB
- Disk Space: 5 GB free disk space
- Network: Internet access for package installation and updates
- Privileges: Root access required to run the installer
Recommended Requirements (for smoother experience and production use)
- CPU: Quad-core processor (4 vCPUs)
- RAM: 8 GB or more
- Disk Space: 10 GB+ free disk space
- Swap: At least 2 GB swap space to prevent build crashes
- Persistent Hostname/IP: Recommended for SSL setup and accessibility
⚠️ Note: The Vaultwarden build process is resource-intensive and may fail on underpowered systems or single-core CPUs. Be sure to allocate enough CPU and RAM, or use the
--purgeoption to clean up failed attempts before retrying.
🔁 --purge Option
If you need to reset your environment to retry installing after a failed installation, run the installer with the --purge flag:
./installer.sh --purge
This will:
- Remove Vaultwarden and its related system user
- Delete configuration files and setup data
- Uninstall MariaDB and clear its databases
- Remove any sudo rules added by the installer
Use this to clean the system before running a fresh install. Note: This does not perform a complete system rollback - only what's necessary to allow a successful reinstallation.
📜 License
This project is licensed under the Apache License 2.0.
© Robbie Ferguson – Open Source Appliance Project