baldnerd/password-manager-server-appliance

Files

- Replace installation section with a Getting Started, which helps clarify the activation process.
- Clarify security notes with a new section, also including info about Let's Encrypt.
- Add info about backup recommendations.

2025-07-12 17:37:48 +00:00

6.2 KiB

Raw Blame History

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.

🚀 Getting Started

Deploy this appliance on a fresh Debian 12 machine (VM or bare-metal).
Run:
```
./installer.sh
```
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.
Copy the admin token provided and store it somewhere safe.
Visit:
```
https://<your-server-ip>/admin
```
to begin using the Vaultwarden admin interface.
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

Installer creates /opt/vaultwarden/.env (default config)
Admin Token is created by visiting /activation and is stored in /var/lib/vaultwarden/.env.user
vaultwarden-wrapper merges both files into .env.merged
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)

6.2 KiB Raw Blame History Unescape Escape