121 lines
4.1 KiB
Markdown
121 lines
4.1 KiB
Markdown
# 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:
|
||
|
||
```bash
|
||
./installer.sh
|
||
```
|
||
|
||
After installation:
|
||
- Access the appliance at `http://<your-appliance-ip>/`
|
||
- Go to `/setup` 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. User config is stored via `/setup` 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 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:
|
||
|
||
```bash
|
||
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 `--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:
|
||
|
||
```bash
|
||
./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](https://www.apache.org/licenses/LICENSE-2.0).
|
||
© Robbie Ferguson – Open Source Appliance Project
|
||
|