Installation Guide

This guide installs the sos-vault appliance on a fresh host. Plan on 30–60 minutes the first time. The installer is interactive but every destructive step supports --dry-run so you can rehearse before committing.

1. Acquire the package

Download sos-vault.deb (Debian/Ubuntu) or sos-vault.rpm (RHEL/Rocky/AlmaLinux) from the Customer Portal. Verify the SHA-256 against the published SHA256SUMS manifest.

2. Install the package

# Ubuntu/Debian
sudo apt-get install ./sos-vault.deb

# RHEL/Rocky/AlmaLinux
sudo dnf install ./sos-vault.rpm

The package unpacks to /opt/sos-vault and marks the four privileged helpers under sysadmin/ as executable. It does not start any service yet — the postinst script intentionally avoids running the installer non-interactively.

3. Run the installer

sudo /opt/sos-vault/sysadmin/installer.sh

The installer walks 17 steps:

1. Verify supported OS
2. Verify hardware (RAM, CPU)
3. Install Docker + Compose if missing
4. Prompt for admin display name, email, and password
5. Prompt for the GPG keyring passphrase — store this in a vault, it cannot be recovered
6. Select the block device for the ZFS pool (lsblk output is shown)
7. Create the ZFS pool, mount it at /vault
8. Initialise the GPG keyring (sysadmin/init.sh)
9. Load bundled docker images from build/docker-images/
10. docker compose up -d
11. Generate a self-signed TLS cert at docker-compose/nginx/ssl/sos-vault.com/
12. Optionally pull the bot LLM model
13. Install /etc/systemd/system/sos-vault.service and enable it
14. Configure UFW (allow 80/443; --force enable)
15. Run php artisan migrate and the ApplianceAdminSeeder
16. Capture an initial sosreport of the host
17. Print connection details

4. Sign in and upload your license

Visit https://<host>/admin and sign in with the admin credentials you entered in step 4. You will see a browser warning until you replace the self-signed cert — that is normal.

Go to Manage License in the admin sidebar and upload the .lic file you received from the Customer Portal. Until a license is installed, the seat guard refuses to create any user beyond the admin.

5. Replace the TLS certificate (optional)

From Certificate Manager upload your real fullchain.pem + privkey.pem. The helper reloads nginx in the container for you. If your environment uses an internal CA, upload the root cert under "Corporate Root CA" first.

6. Create users and teams

Use Groups to create teams. Each team owns its own vault. Add users from the admin panel — the seat guard enforces the count from your installed license.

Environment overrides

The installer honours these env vars when defaults do not fit:

• SOS_VAULT_DIR — install root. Default /opt/sos-vault.
• SOS_VAULT_ZFS_POOL — zpool name. Default sosvault.
• SOS_VAULT_NAS_MOUNTPOINT — vault mount. Default /vault.
• SOS_VAULT_NGINX_CONTAINER — docker container. Default sos-vault-nginx.