# 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

---

## 📂 Important 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) |

---

## 🚀 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 `/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:

```bash
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:

```bash
./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.

---

## 📜 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