Installation

Taranac ships as a set of Docker images orchestrated by a small deployment bundle. You do not build anything from source: you download the bundle, run two scripts, and the installer generates every secret, pulls the images, and brings the whole stack up behind a TLS reverse proxy. This page walks through a clean install on a single host and the first things you do afterwards.

The bundle contains only configuration — a Docker Compose file, an installer, a taranac operations wrapper, and a config/ directory you drop your TLS certificate and (optionally) Firebase key into. The application itself arrives as images pulled at install time.

You also need a hostname or IP that clients will use to reach Taranac. Pick it before you start — the installer asks for it, and your TLS certificate must later cover the same name.

Open inbound only the ports for the protocols you actually use. The admin UI and API are always reached through port 443.

Outbound HTTPS is needed to pull the container images (and, periodically, the IEEE OUI database used to identify endpoint vendors).

Taranac is a multi-container stack on one shared PostgreSQL database. A single public edge reverse proxy terminates TLS and is the only browser-facing service; everything else talks over an internal Docker network.

The api container is the brain: when you change policy in the UI it regenerates the TACACS+, RADIUS, NAC, and captive-portal configuration, writes it to shared volumes, and signals the daemons to reload — no restarts, no hand-edited config files. The protocol daemons run in separate containers so a fault in one engine cannot take down the others.

All services run with restart: unless-stopped and Docker is enabled on boot, so the whole stack comes back automatically after a reboot.

Download and unpack the latest release. There’s no version to pick — latest always resolves to the newest bundle — and the archive expands into its own taranac/ directory:

curl -fsSL -O https://github.com/TaranacLabs/taranac/releases/latest/download/taranac-bundle.tar.gz
tar xf taranac-bundle.tar.gz
cd taranac

Prefer to track the bundle scripts with git instead? git clone https://github.com/TaranacLabs/taranac.git && cd taranac gives you the same deployment files (the clone contains no product source — the app still arrives as images pulled at install time).

The bundle is a flat archive of deployment files — the install.sh and bootstrap.sh scripts, the taranac operations wrapper, docker-compose.yml and the config/ templates. All releases are published on the project releases page.

If the host already has Docker Engine and the Compose plugin, skip this. Otherwise the bundle ships a bootstrap script:

sudo bash bootstrap.sh

It installs Docker, the Compose plugin, enables the engine on boot, and adds your user to the docker group.

./install.sh

The installer asks just three questions (press Enter for the default in brackets):

Everything else is a bundle property, not an operator choice: the image registry (ghcr.io/taranaclabs/taranac) and the version tag are fixed by the release you downloaded — the tag is read from the bundle’s VERSION file, so the installer never asks for it and the images can’t drift from the bundle. If you mirror the images (air-gapped installs) or want to pin the MFA push to its own hostname, pass them as environment variables instead of answering a prompt:

IMAGE_PREFIX=registry.local/taranac TARANAC_MFA_DOMAIN=mfa.example.com ./install.sh

With no MFA push domain set, push registration defaults to https://<primary domain>:8443/ttype/push.

The installer then generates every secret for you — the PostgreSQL password, the JWT signing key (SECRET_KEY), the encryption master key (MASTER_KEY), the internal API keys, and a strong admin password — writes them to a .env file (mode 600), pulls the images, and starts the stack.

When it finishes it prints the admin login: URL, username, and the generated password.

The master key (a Fernet key) is the root of all secret encryption. The installer puts it in .env as MASTER_KEY with MASTER_KEY_SOURCE=env, which is the simplest model: the key lives in the environment file and is loaded at start. Without it the API still starts but runs sealed — any operation touching an encrypted field fails until the key is supplied. Treat .env as a sensitive credential and store a copy somewhere safe and offline.

Open https://<your-domain>/ and sign in with the printed admin credentials.

The dashboard is the landing page once you are authenticated.

Until you install a trusted certificate (next step), the edge serves a temporary self-signed certificate, so the browser shows a security warning — that is expected on a fresh install. Change the admin password right after logging in.

Taranac does not automate Let’s Encrypt — you bring your own certificate (commercial CA, your organization’s internal CA, or a manually issued one). Drop two files into config/tls/, using exactly these names:

The certificate’s Subject Alternative Name must cover your primary domain (and the MFA push domain, if you set one). Then apply it without rebuilding anything:

./taranac restart edge

Reload the page and the warning is gone. If files are absent the edge keeps serving its self-signed certificate, so the stack always boots either way.

Out of the box, MFA works in free poll-only mode — the app checks for pending approvals periodically. To enable instant push notifications, drop your Firebase service-account JSON at config/firebase/firebase-credentials.json, then:

./taranac up -d taranac-mfa

A single host is the default and the right choice for most deployments. If you later need authentication to survive the loss of a node, the same bundle can be converted into a multi-node high-availability cluster (Postgres streaming replication with automatic failover). Conversion is out-of-band and driven by the ha-convert.sh script shipped in the bundle; HA is a Pro feature and is license-gated. You do not need to decide this at install time — start single-host and scale out when required.

See High availability for the architecture, prerequisites and the step-by-step conversion, and Licensing for enabling the Pro feature.

Use the taranac wrapper from the bundle directory — it is a thin shortcut for the full docker compose --env-file .env -f docker-compose.yml … invocation, so any Compose subcommand works too.

./taranac ps                # service status
./taranac logs -f api       # follow a service's logs
./taranac restart edge      # restart one service (e.g. to apply a new cert)
./taranac down              # stop everything (data is preserved in volumes)
./taranac up -d             # start again

After MAX_LOGIN_ATTEMPTS failed logins (5 by default) an account is locked. The lock does not auto-expire, so a locked-out admin cannot recover through the web UI — common on an internet-facing host once someone starts guessing passwords. Recover from the server console:

./taranac unlock                 # list locked accounts
./taranac unlock admin           # unlock one account
./taranac unlock --all           # unlock every locked account
./taranac reset-password admin   # reset a forgotten password (prints a new one)
./taranac create-admin           # create-or-repair an admin login when none works

Re-running the installer is itself the upgrade path: when .env already exists, install.sh never regenerates secrets — it just pulls newer images and restarts. The taranac wrapper adds a self-maintaining update that refreshes both the images and the bundle files (wrapper, Compose file, installer, docs):

./taranac version    # installed version + check for a newer one
./taranac update     # update to the latest (or: --version 1.1.0)

update leaves your .env and config/ untouched and bumps the pinned version; database migrations run automatically when api starts. Take a backup from the in-app Backup & Recovery tools before upgrading.

• A service shows unhealthy in ./taranac ps — read its logs: ./taranac logs --tail=100 <service>.
• Browser still warns after Step 5 — confirm config/tls/tls.crt is the full chain and its SAN matches your domain, then ./taranac restart edge.
• docker ps needs sudo — you didn’t start a new login shell after bootstrap.sh; log out/in or run newgrp docker.

• Quick start — first policies after install
• Introduction — what Taranac is and where it fits
• Architecture — the containers and how a request flows
• High availability — converting a single host into an HA cluster
• Project repository — releases and the deployment bundle