sos - vault#sos#sos#sos#sos
Open-Core Model back to the blog Open-Core Model

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 through these steps (plus a few sub-steps such as provisioning the app user and capturing the host fingerprint):

  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. Initialise the GPG keyring (sysadmin/init.sh)
  7. Load bundled docker images from build/docker-images/
  8. Write the application .env (generated APP_KEY, DB path, and a commented outbound-proxy block — see Outbound proxy below)
  9. docker compose up -d
  10. Generate a self-signed TLS cert at docker-compose/nginx/ssl/sos-vault.com/
  11. Prepare the AI model directory — the ~1.1 GB bot LLM model is not downloaded here; you fetch it later from the admin Software Updates page (see section 7)
  12. Install /etc/systemd/system/sos-vault.service and enable it
  13. Configure UFW (allow 80/443; --force enable)
  14. Run php artisan migrate and the ApplianceAdminSeeder
  15. Ensure the plain vault directory (default /vault) exists
  16. 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.

Two-factor authentication: administrator accounts must set up TOTP 2FA. On the first sign-in the admin is redirected to Settings → Security to enrol — have an authenticator app (Google Authenticator, Authy, 1Password, etc.) ready to scan the QR code. 2FA is optional for non-admin users. It is fully offline; no internet access is needed to enrol or sign in. If an admin is ever locked out, see the Troubleshooting Guide for the break-glass command.

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.

7. Enable the AI assistant (optional)

The in-app assistant relies on a local LLM model that is not shipped with the package, keeping the download small. The installer no longer prompts for it; instead you enable the assistant on demand from the admin panel.

Go to Software Updates in the admin sidebar and click Download AI model in the top section. The ~1.1 GB model is fetched in the background — the assistant becomes available automatically once the download finishes. Everything runs locally on the appliance; no data is sent to any third party. You only need to do this once. The host needs outbound HTTPS for the duration of the download.

The bundled model answers questions about sos-vault, the sos command, and Linux commands in general. It does not analyse sosreport data — it cannot read, parse, or draw conclusions from the contents of a captured sosreport. If you need sosreport data analysis, connect your own access to a more capable model by configuring an external AI provider (model and API key) on the AI Assistant settings page; the assistant then uses that provider for analysis.

Asking effective questions. Start a question with a topic label so the assistant focuses on the right area and answers more accurately: SosVault: for using the app, SosCommand: for the sos command, Linux: for general Linux, and Case: for the sosreport you have open (external provider only). For example: SosCommand: how do I limit log size to 10MB?. Type /help in the chat for the full list of commands and labels.

Outbound proxy (private networks)

If this host reaches the internet only through a corporate proxy, the installer leaves a commented proxy block at the bottom of /opt/sos-vault/.env. Uncomment HTTPS_PROXY (and adjust NO_PROXY) only if you enable an integration that calls out (Jira/ITSM, Telegram, remote AI) or download the AI model, then run sudo systemctl restart sos-vault. The web UI and command-line upload are LAN-local and never need the proxy. See the Administration Guide → Outbound proxy for the full details (including the SMTP and TLS-interception caveats).

Environment overrides

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

  • SOS_VAULT_DIR — install root. Default /opt/sos-vault.
  • SOS_VAULT_VAULT_DIR — vault directory. Default /vault.
  • SOS_VAULT_NGINX_CONTAINER — docker container. Default sos-vault-nginx.
Open-Core Model back to the blog Open-Core Model