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 administration
• 🌐 NGINX reverse proxy + PHP-based first-time activation wizard
• 🔑 Multi-user access, browser extensions, mobile app compatibility

---

⚠️ Disclaimer

This installer is intended only for use on a dedicated appliance or virtual machine running a clean installation of Debian 12. It will make system-wide changes, including user/group creation, file permission changes, service overrides, firewall configuration, and package installations. Do not run this script on an existing server or computer system. It does not validate your environment or attempt to preserve existing configurations - doing so may cause data loss or render your system unusable.

---

🚀 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 /activate to complete first-time configuration
• After submitting the form, Vaultwarden will use your custom settings

---

🧠 Configuration Flow

1. Installer creates /opt/vaultwarden/.env (default config)
2. Admin Token is created by visiting /activation and is stored in /var/lib/vaultwarden/.env.user
3. vaultwarden-wrapper merges both files into .env.merged
4. Systemd launches Vaultwarden using the wrapper

---

🔁 To Re-run Activation

To prevent a bad actor from modifying your configuration by re-running the /activate 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 /activate 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 --purge option 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 activation 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.

---

📂 File Paths

Path	Purpose
/opt/vaultwarden/.env	Core Vaultwarden environment settings
/var/lib/vaultwarden/.env.user	User-defined config written via the activation tool
/var/lib/vaultwarden/.setup-complete	Flag file that disables the activation 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/activate/	First-time activation tool, served via PHP
/var/www/html/vaultinfo/index.html	Installer-complete welcome page (not currently used)

---

📜 License

This project is licensed under the Apache License 2.0.
© Robbie Ferguson – Open Source Appliance Project