Installing VeiraHub
From an empty host to the three tools logging in through it, with Docker Compose.
What you need
- A Linux host with Docker and Docker Compose.
- An HTTPS address for the hub, e.g.
https://hub.example.com, and a reverse proxy with TLS in front of it. - LDAP or Active Directory, and a service account that can read people and groups.
- An authenticator app for the hub's emergency admin.
Configure it
git clone https://github.com/Codeveira/veirahub-deploy.git
cd veirahub-deploy
cp .env.example .env| Setting | What it is |
|---|---|
VEIRAHUB_PUBLIC_URL | The hub's address as people reach it, through your TLS proxy. It must be https://. |
VEIRAHUB_MASTER_KEY | Encrypts the directory's password, the hub's signing key, licence keys and other secrets at rest: openssl rand -hex 32. Keep a copy with your backups. |
POSTGRES_PASSWORD | The bundled database's password. |
IMAGE_TAG | The VeiraHub version to run, e.g. v0.9.0. |
VEIRAHUB_SYNC_INTERVAL | How often to sync with the directory; 15m by default, 0 for only by hand. |
VEIRAHUB_SYNC_MAX_DISABLE_PERCENT | The most of the accounts one sync may disable before it waits for an admin; 20 by default. |
VEIRAHUB_AUDIT_RETENTION | How long to keep the audit log; 8760h (a year) by default, 0 for ever. |
Start it
make up-release # pulls and starts IMAGE_TAG
make admin-create USERNAME=rescue # the emergency admin: asks for a password, prints its authenticator secretThe hub listens on 127.0.0.1:8500. Point your TLS proxy at it, open VEIRAHUB_PUBLIC_URL and log in as the emergency admin with the password and a code from your authenticator app.
Connect the directory
Under Directory, give the hub your LDAP or Active Directory servers, the service account and where people and groups are, and test the connection. From then on people log in to the hub with their directory password; the hub never keeps it.
Connect the tools
Under Tools, add each tool with its address as people reach it, to get a one-time enrollment token (good for an hour). Then, in the tool:
| Tool | Where |
|---|---|
| Codeveira | Settings → VeiraHub, on any licence. Logging in through the hub needs Extended. |
| Veira Seal | veira veirahub connect -url https://hub.example.com -token vhe_..., with -sso-public-base-url set on its server for Log in with VeiraHub. |
| VeiraForge | Settings → VeiraHub, with its public URL set. |
Compare the signing key fingerprint the tool shows with the one under Tools in the hub: they must be the same. Each tool then publishes the roles it can give, checks in every minute, and gets a Log in with VeiraHub button. A tool connected before it could log people in through the hub gets it by connecting again with a new token.
Give groups their roles
Under Roles, give a directory group a role in a tool — across the tool, or in one project, repository or team. Each change is previewed (who gains, who loses access) and refused if it would leave a tool without an admin from the directory. Accounts are made before a first login and disabled, never deleted, when the directory no longer gives someone a role.
While the hub is down, each tool logs people in against the directory itself, from the last settings the hub signed.
Licences
Under Tools → Codeveira or Veira Seal → Licence, paste the tool's licence key. The tool takes it with its settings at its next sync and checks it itself; while it comes from the hub, it's changed in the hub. VeiraForge has no licence. The hub itself is free.
Upgrades and backups
make backup # dumps the database; keep VEIRAHUB_MASTER_KEY with it
# set a newer IMAGE_TAG in .env, then
make up-releaseA new version upgrades its database by itself when it starts. Back up first.