Quick start variants

The main quick start assumes Tenantry and Teleport share a server. Here are the other layouts.

Your situation	Go to
Teleport on another server, Tenantry in Docker here	Teleport on another server
Teleport on another server, you prefer an identity file	Identity file
No Teleport yet, you want a new cluster and Tenantry	A new Teleport cluster with Tenantry
Tenantry directly on the Teleport host, without Docker	Not supported: use install.sh --teleport-local binary (why)

Teleport on another server

Tenantry cannot use a local tctl here, so you create the role and the Machine ID bot yourself, once, then give the installer the one-time join token.

1. Create the role and the bot

On a machine logged in to the cluster as an administrator (tsh login, tctl works):

1. Get the role file. Open the Security page of an existing Tenantry and use Machine ID (tbot), Set up Machine ID (it shows the commands with your cluster filled in). Switch Fleet locking and Join tokens on to match the permission level you want. Save the file as tenantry-role.yaml.

   No Tenantry yet? The installer of the release you install prints the roles from its own text (read it before applying it):

   git clone --branch v<x.y.z> https://github.com/Verttigo28/tenantry && cd tenantry
   scripts/install.sh --print-tenantry-role minimal > tenantry-role.yaml   # or: full
   scripts/install.sh --print-console-roles > steward-roles.yaml           # steward-admin, steward-helpdesk
   

   minimal (recommended) registers the Steward application and lists the fleet; it cannot create roles, join tokens or locks, so create the Steward console roles yourself (steward-roles.yaml). full also creates roles, enrolment tokens ("Add a proxy") and locks: a compromise of Tenantry is then a compromise of the cluster.

2. Create the roles and the bot:

   tctl create -f tenantry-role.yaml
   tctl create steward-roles.yaml              # minimal role: the console roles are created here, by you
   tctl bots add tenantry --roles=tenantry     # prints a one-time join token
   

2. Save the token

On the Tenantry server, type it into a file only root can read. It never appears on a command line or in your shell history:

(umask 077; read -rsp 'Bot join token: ' t; echo; printf '%s\n' "$t" > /root/tenantry-bot-token)

3. Install

git clone https://github.com/Verttigo28/tenantry.git && cd tenantry
sudo scripts/install.sh

In the wizard, step 1 choose Elsewhere. It asks for the proxy address (teleport.acme.ch:443), checks the cluster version, and asks how Tenantry authenticates: choose Machine ID bot, then paste the token (hidden). Steps 2 to 5 are as in the quick start.

The equivalent command:

sudo scripts/install.sh --name acme --public-url https://tenantry.acme.ch \
  --auth machine-id --auth-server teleport.acme.ch:443 --proxy teleport.acme.ch:443 \
  --bot-token-file /root/tenantry-bot-token --teleport-version 18.11.4 --version <x.y.z> \
  --expose cloudflare-tunnel --tunnel-token-file /root/tenantry-tunnel-token

Replace the last line with the exposure you chose (--expose proxy, or --tls ... for HTTPS on this server).

The script writes tbot.yaml, starts tbot and Tenantry, waits for the first identity, then deletes the join token (both copies). Re-running the script later needs no token.

Teleport behind Cloudflare Access

tbot is a non-browser client: it cannot log in to Cloudflare Access. Point --auth-server at an address it can reach (a private network path, or the auth service on port 3025 with a firewall allow-list). See Teleport behind Cloudflare Tunnel + Access + Duo.

How Machine ID works, what runs and how it is monitored: Machine ID reference.

Identity file (it expires)

Instead of a bot, tctl can use an identity file you create:

tctl auth sign --user=<user> --format=file --out=identity --ttl=720h

sudo scripts/install.sh --name acme --public-url https://tenantry.acme.ch \
  --auth identity --identity-file /var/lib/tenantry/identity \
  --auth-server teleport.acme.ch:443 --teleport-version 18.11.4 --version <x.y.z>

The identity file EXPIRES

When it expires Tenantry can no longer read or change Teleport. The dashboard warns 24 hours ahead. Renew it with the same command and replace the file (same path, same permissions): no restart. Prefer Machine ID, which renews itself.

The container user (uid 1000) must be able to read the file: chown 1000:1000 and chmod 0400 (preferred), or chmod 0444. The installer checks.

A new Teleport cluster with Tenantry

No Teleport yet? Tenantry's Teleport master server page generates a Docker bundle for a single-node cluster (Auth, Proxy and application service in one container). The page can also install Tenantry on that same server in the same run.

1. In an existing Tenantry, open Teleport master server. Enter the public DNS name and a contact e-mail, and generate the bundle.
2. Turn on Install Tenantry on this server. Enter Tenantry's public name and the permission level (full or minimal, same meaning as --bot-role).
3. Optionally turn on Cloudflare Tunnel (no inbound port), with Private address for tsh and agents if you give non-browser clients a private path.
4. Download the zip, copy it to the new server, run ./preflight.sh then ./bootstrap.sh.

At the end bootstrap.sh runs tenantry/scripts/install.sh --teleport-local docker:<container> --expose proxy for you. The role, the bot and the networks are wired automatically. Tenantry is then reached through the same tunnel, or else as the Teleport application tenantry.

Full guide: A new Teleport cluster.

The generator page lives in a running Tenantry. If you have none yet, install one first with the quick start, then use it to generate the new cluster.