baldnerd/password-manager-server-appliance
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
909e8317cc8e23aa5b1163bfc72d06e0749e3f8f
password-manager-server-app…/README.md
baldnerd 909e8317cc Update README.md
2025-07-13 14:29:17 +00:00

7.6 KiB
Raw Blame History

Password Management Appliance

An Open Source Appliance from Robbie Ferguson

A hardened, self-hosted password manager appliance based on Vaultwarden and compatible with official Bitwarden apps and browser plugins. 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

🤔 Why Vaultwarden Instead of Bitwarden?

Vaultwarden is a lightweight, open-source implementation of the Bitwarden server API. It offers:

  • ✅ Full compatibility with Bitwarden official clients (web, mobile, desktop, browser extensions)
  • ✅ Extremely low system resource usage - perfect for self-hosted appliances
  • ✅ Easy customization and backup
  • ✅ No proprietary licensing restrictions

Bitwarden's official server requires more complex infrastructure and higher resource consumption. Vaultwarden offers nearly identical functionality in a compact, open-source form.

🌐 Using Clients and Accessing Your Vault

This server is compatible with the official Bitwarden clients, including:

  • 📱 Mobile apps (iOS, Android)
  • 🖥️ Desktop apps (Windows, macOS, Linux)
  • 🌐 Browser extensions (Chrome, Firefox, Edge, etc.)
  • 💻 Web vault (via this appliance's built-in web UI)

To use mobile or remote clients outside your local network, your appliance must be publicly accessible (e.g., via a domain name with port 443 open and a valid SSL certificate).

For example:

  • ✅ https://vault.yourdomain.com – accessible anywhere
  • ❌ https://192.168.1.100 – works only on your LAN

Make sure your router/firewall allows inbound HTTPS traffic and that your DNS is configured correctly if using Let's Encrypt.

⚠️ 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.

🚀 Getting Started

  1. Deploy this appliance on a fresh Debian 12 machine (VM or bare-metal).

  2. Run:

    ./installer.sh

  3. Once complete, open a browser and visit:

    https://<your-server-ip>/activate

    DO NOT omit this step. Doing so would be an extreme security risk.

  4. Copy the admin token provided and store it somewhere safe.

  5. Visit:

    https://<your-server-ip>/admin

    to begin using the Vaultwarden admin interface.

  6. Visit:

    https://<your-server-ip>/

    to begin using Vaultwarden.

🔐 Security Notes

  • This appliance uses self-signed SSL certificates by default. If hosting on a domain, Let's Encrypt certbot is included. You can run certbot --nginx to obtain and install HTTPS certificates automatically. Make sure your domain points to this server before running the command.
  • Accessing the web interface requires HTTPS — HTTP requests are automatically redirected.
  • The admin token is hashed using Argon2ID and cannot be retrieved later. If lost, delete /opt/vaultwarden/.setup-complete to regenerate using /activate.
  • Ensure you complete /activate immediately after setup to prevent unauthorized configuration.

💾 Backup Recommendations

To safely back up your Vaultwarden appliance, include the following:

  • /opt/vaultwarden/ — Vaultwarden binary, web-vault, and persistent config.
  • /var/lib/vaultwarden/ — Environment file (.env.user) and state flag (.setup-complete).
  • Database backup: Use mysqldump to regularly export the vaultwarden database, and then backup that file to your backup set. Example dump: 
    mysqldump vaultwarden > /root/vaultwarden-backup.sql

Backups should be performed routinely and securely stored.

🧠 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