First [not yet working] version
This commit is contained in:
120
README.md
120
README.md
@ -1,2 +1,120 @@
|
||||
# password-manager
|
||||
# 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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user