Vaulthalla Logo

First Run

Bootstrap Vaulthalla after installation, bind the CLI admin Linux UID, configure database access, and expose the web console.

First Run

After installation, finish the host-specific setup: database access, CLI ownership, group membership, service health, and optional Nginx/TLS exposure.

First-Run Checklist

    1. Confirm the package installed and services exist with vh status and systemctl status.
    2. Bootstrap a local or remote PostgreSQL connection.
    3. Add the operator Linux user to the vaulthalla group.
    4. Bind the initial CLI admin user to that Linux UID.
    5. Configure Nginx and TLS if the web console should be reachable by domain.
    6. Open the web console and create the first operational vault. :::

  2. Database Setup

    For local PostgreSQL:

    1sudo vh setup db

    For remote PostgreSQL:

    1sudo vh setup remote-db \2  --host db.example.com \3  --port 5432 \4  --user vaulthalla \5  --database vaulthalla \6  --password-file /root/vaulthalla-db-password

    Use VH_SKIP_DB_BOOTSTRAP=1 during package install when you want to configure database access after the package is installed.

  3. CLI Admin Linux UID

    Vaulthalla's local CLI is intentionally tied to Linux identity. The CLI talks to /run/vaulthalla/cli.sock, which is owned for Vaulthalla use. Non-root CLI users must be in the vaulthalla group and must be mapped to an application user by Linux UID.

    The initial admin binding is handled by:

    1vh setup assign-admin

    Run this as the Linux account that should operate Vaulthalla. The command binds the built-in admin user to that Linux UID when it is still unbound. If the admin user is already bound to the same UID, the command reports that it is already assigned. If it is bound to a different UID, it refuses to rebind.

    The first non-root CLI user can become the CLI owner

    If setup is skipped and the admin UID is still unbound, the first eligible non-root user that reaches the CLI socket can claim the initial CLI ownership. Choose the operator user intentionally during install or immediately run vh setup assign-admin as the intended user.

  4. Group Membership

    The installer can add an operator to the vaulthalla group. If you do it manually:

    1sudo usermod -aG vaulthalla <linux-user>

    Then refresh the login session:

    1newgrp vaulthalla

    or log out and back in. Confirm membership:

    1id2getent group vaulthalla

  5. Lifecycle Commands Require Sudo

    Runtime lifecycle commands modify host services or privileged configuration and must be run with sudo:

    1sudo vh setup db2sudo vh setup remote-db --host <host> --user <user> --database <name> --password-file <path>3sudo vh setup nginx --domain vault.example.com4sudo vh teardown nginx5sudo vh teardown db

    Most day-to-day commands, such as vh vaults, vh user, vh api-key, and vh vault sync, are normal CLI commands that use the local control socket.

    For unattended lifecycle automation, set:

    1VAULTHALLA_NONINTERACTIVE=1

    or pass lifecycle helper options such as --non-interactive or --yes where supported.

  6. Configure The Web Console

    If Nginx was not configured during package install:

    1sudo vh setup nginx --domain vault.example.com

    For managed TLS:

    1sudo vh setup nginx --domain vault.example.com --certbot

    Then check:

    1systemctl status vaulthalla-web.service2systemctl status vaulthalla.service3sudo nginx -t

    The web service listens locally and is intended to be exposed through Nginx.

  7. Health Checks

    Use these after any setup change:

    1vh status2journalctl -fu vaulthalla.service3journalctl -fu vaulthalla-web.service

    Check the CLI socket when vh cannot connect:

    1ls -l /run/vaulthalla/cli.sock2systemctl status vaulthalla-cli.socket3systemctl status vaulthalla-cli.service

  8. Next Steps

    Create an API key if you plan to use S3/R2 vaults, create a vault, and then review backup and key export procedures before putting important data into the system: