baldnerd
d8fe90dc3e
- 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.
171 lines
6.2 KiB
Markdown
171 lines
6.2 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 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
|
||
|
||
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
|
||
|