> ## Documentation Index
> Fetch the complete documentation index at: https://docs.casebender.com/llms.txt
> Use this file to discover all available pages before exploring further.

# First-run Setup

> Activate a new on-premises CaseBender installation and create its first administrator

CaseBender uses one-time browser activation so every new installation starts
with its own administrator credentials. Activation is local to the customer's
CaseBender server and does not require deployment to the public internet.

## Deployment states

* `UNINITIALIZED` — the database has not prepared an activation challenge.
* `ACTIVATION_PENDING` — a short-lived activation code is available to the
  installation operator.
* `ACTIVE` — the first administrator exists and setup endpoints are closed.

Protected web, tRPC, REST API, and ingestion operations remain unavailable until
the deployment is active.

## Activate a new installation

1. Download, verify, and extract the public Community release bundle as described
   in the [Quickstart Guide](/en/quickstart). The private source repository is
   not required.

2. Initialize and start the release from the extracted bundle directory:

   ```bash theme={null}
   ./casebender init
   ./casebender preflight
   ./casebender up
   ```

3. Display the short-lived code in the installation terminal:

   ```bash theme={null}
   ./casebender activation-code
   ```

4. From a browser that can reach the on-premises server, open:

   ```text theme={null}
   https://casebender.your-company.example/setup
   ```

5. Enter the activation code and the initial administrator's email, name, and
   unique password.

6. Store the administrator credential in your enterprise password manager and
   enroll MFA immediately.

The activation code expires after 30 minutes, permits at most five failed
attempts, and is invalidated after successful use.

## Air-gapped environments

The browser communicates only with the customer's own CaseBender URL. No
external CaseBender activation service is involved. The code is generated and
verified by the local installation.

## Existing installations

The upgrade migration classifies a database containing existing users as
`ACTIVE`. It does not:

* show the activation wizard;
* change an existing password;
* recreate the default administrator;
* change roles, organizations, or API keys; or
* reset application data.

Test the upgrade using a sanitized copy of the client database before
production rollout.

## Recovering an expired code

Generate a replacement while the deployment remains activation-pending:

```bash theme={null}
./casebender activation-code
```

Rotating a code invalidates the previous code. Do not place activation codes in
tickets, chat, shell history, or application logs.

## Legacy bootstrap compatibility

Legacy shared credentials are disabled by default. A time-limited compatibility
exception requires both:

```bash theme={null}
CASEBENDER_LEGACY_BOOTSTRAP=true
ACCEPT_LEGACY_BOOTSTRAP_RISK=true
```

The production preflight rejects legacy mode without the explicit risk
acknowledgement. If an existing customer temporarily depends on it:

1. obtain written approval with an owner and expiry date;
2. restrict network access to trusted administrators;
3. require password change at first sign-in;
4. disable both variables after migration to one-time activation.

Legacy mode is not an alternative setup path for new production installations.