Documentation by ClonePartner

Start typing to search.

Getting Started

First-time setup

View Markdown

Create the administrator account on the setup screen, enroll a TOTP authenticator, and sign in for the first time.

First-time setup

What this screen is for

A fresh Envoy deployment has no users. The first visit to the web UI redirects to the /setup screen, where you create the administrator account. This account is created with the superadmin role — the highest of Envoy's roles — and setup is only available while the user table is empty. Once any account exists, /setup refuses with "Setup already completed".

Create the administrator account

The screen greets you with "Welcome to Envoy" (or your deployment's configured application name) and a Create Account card.

  1. Enter a Username. The field is prefilled with admin; you can keep or change it.
  2. Enter a Password of at least 8 characters, and repeat it under Confirm Password. The form blocks submission when the two do not match.
  3. Select Create Account.

What happens next depends on whether two-factor authentication is required. It is required by default; a deployment can disable it with auth.totp_required: false in envoy-server.yaml (or the ENVOY_AUTH_TOTP_REQUIRED environment variable for generated Docker configs).

Enroll your authenticator (TOTP)

When two-factor authentication is required, setup continues with a Two-Factor Setup card:

  1. Scan the QR code with your authenticator app (any TOTP app works — the code is issued as Envoy with your username as the label). If you cannot scan, copy the secret shown under "Or manually enter this secret:" into the app instead.
  2. Select I've scanned the code.
  3. On the Verify Code card, enter the 6-digit TOTP Code from your app and select Complete Setup.

A successful verification signs you in and opens the home dashboard. Repeated wrong codes lock verification; the screen asks you to sign in again to continue.

Signing in afterwards

Later visits use the /login screen: enter the username and password, then the TOTP code when prompted, and select Sign in. Deployments with OAuth configured also show Sign in with Microsoft or Sign in with Google buttons; those providers are set up under auth.providers in the server configuration — see OAuth redirect URIs.

Additional users are not created on this screen. The administrator invites them from the Users page — see Users and settings.

Tips