First-run setup

Citadel does not ship with a default administrator username or password.

For a Docker Compose installation, prepare the production environment before starting Core. See Docker Compose configuration.

Interactive setupCopy Anchor Link

Start Citadel and open its normal browser URL. A new installation redirects to /setup.

Enter:

1. The administrator username.
2. The administrator email address.
3. A password meeting the configured length requirement (15 to 128 characters by default).
4. The same password again.

The password field shows a character count and an estimated strength. The estimate uses a lightweight check of length, variety, and repetition in your browser. It is advisory and does not check breached-password lists or a comprehensive dictionary; the configured length limits still apply. Longer, uncommon passphrases can help you choose a stronger password. Repetitive passwords with small variations are rated conservatively; adding a symbol or space does not automatically make them strong.

MFA is optional by default. You and other users can enable it later in Profile → Security → Two-factor authentication. If the server requires MFA, enrollment starts after the administrator account is created.

Setup uses the server-provided installation settings. Update checks are enabled by default and can be changed later in Updates → Config. They send no Citadel telemetry and never install updates. Core waits until setup is complete before making a release-check request. See update checks and privacy.

Select Create administrator. Citadel creates the account with the built-in Admin role and signs you in. Setup cannot be opened again after it succeeds.

After creating the account, enable in-app updates on the Docker host to finish setting up the supported Compose installation. This verifies installation ownership and briefly restarts Core; creating an account or enabling release checks alone does not grant the updater installation access.

The password should be unique to Citadel and stored in a password manager. After setup, use Profile for personal settings, password changes, and active browser sessions.

Configure password lengthCopy Anchor Link

Set the minimum password length in your Docker Compose .env file:

CITADEL_PASSWORDS_MINIMUM_LENGTH=15

The minimum defaults to 15 and accepts values from 8 to 128. The maximum password length remains 128 characters. After changing .env, run docker compose up -d from your installation directory, including all proxy, TLS, and Edge overlays used by your installation, then reload the setup page.

Two-factor authenticationCopy Anchor Link

Two-factor authentication is optional by default. It can be enabled later from Profile → Security. Administrators can change the installation-wide policy in Administration → Instance; MFA changes save when selected.

To enforce a minimum policy through deployment configuration, set:

CITADEL_MFA_POLICY=RequiredForAdministrators

The available policies are:

• Optional
• RequiredForAdministrators
• RequiredForAllUsers

See Two-factor authentication for enrollment and recovery-code instructions.

Unattended setupCopy Anchor Link

Automated installations can initialize Citadel from a password file. The password is not accepted directly through an environment variable.

Set all three options:

CITADEL_BOOTSTRAP_ADMIN_NAME=citadel-admin
CITADEL_BOOTSTRAP_ADMIN_EMAIL=admin@example.com
CITADEL_BOOTSTRAP_ADMIN_PASSWORD_FILE=/run/secrets/citadel-admin-password

Mount the password file read-only into the server container:

services:
  server:
    volumes:
      - ./secrets/citadel-admin-password:/run/secrets/citadel-admin-password:ro

The path must be absolute inside the container. The file must contain only the password, may end with one newline, must not contain other line breaks, and must not exceed 1 KiB.

If only some bootstrap options are configured, Citadel refuses to start. If setup is already complete, Citadel ignores the bootstrap options and does not read the file.

After the first successful start:

1. Confirm that the administrator can sign in.
2. Remove the three bootstrap settings.
3. Remove the password-file mount.
4. Delete the local password file securely.

RecoveryCopy Anchor Link

Clearing browser cookies, deleting sessions, or restarting Citadel does not reopen first-run setup. The setup endpoint is not a password-recovery feature.

Use another administrator account to restore access. Directly deleting or editing the setup-state database row is unsupported.

Development builds can have incompatible database baselines. Preserve a matched database-and-keys backup before changing builds or rebuilding an installation; deleting the database is not a password-recovery procedure.