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

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

---

## 📂 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](https://www.apache.org/licenses/LICENSE-2.0).  
© Robbie Ferguson – Open Source Appliance Project