# Deploy the management app

Configure the management browser application, reverse proxy, public API URL and authentication callbacks.

## Outcome and prerequisites

Deploy the management app at `https://dicto.example.org/management/` against
`https://dicto.example.org/api`, matching the maintained path layout. You need
an initialized backend/database, HTTPS routing, registry pull access and an
administrator account. The [reference archive](/install/reference.md) pins the
management image by digest and includes the service in `compose.yaml`.

The management app is a static browser application served by its container.
Its `API_URL` is used by users' browsers, so the value must be reachable from
their networks. Do not set it to `http://server:3000`.

## Runtime configuration

Edit [app-management/public.env](/examples/reference/app-management/public.env):

```dotenv
API_URL=https://dicto.example.org/api
BASE_HREF=/management/
```

Use a leading and trailing slash in `BASE_HREF`. For a dedicated hostname,
set `BASE_HREF=/` and route that hostname to the management container. Recreate
the container after changing runtime configuration. A compiled API URL override
may take precedence; verify the effective URL in browser network requests.

Browser configuration is public. Keep database passwords, auth secrets and
inference keys on the backend, never in this environment file or browser assets.

## Routing and authentication

The reference proxy sends `/management/*` to `management:80` **without stripping
the prefix**. It sends `/api/*` to `server:3000` after stripping `/api`.
Use the same host in:

- `api.url`: `https://dicto.example.org/api`.
- `auth.base_url`: `https://dicto.example.org/api/auth`.
- `auth.trusted_origins`: `https://dicto.example.org` (origin, with no path).
- `auth.web_redirect_uris`: `https://dicto.example.org/management/auth.html`.

For a dedicated management hostname, add that origin and its actual callback
URL instead. SSO providers additionally need their server callback registered
with the identity provider; see [authentication](/configure/authentication.md).

## Start or update

From the reference root, use your selected recipe's complete Compose prefix.
For the core profile:

```sh
docker compose --env-file secrets.env config --quiet
docker compose --env-file secrets.env up --build -d
docker compose --env-file secrets.env logs --tail 100 management server
```

Migrations and bucket initialization must finish before the API is usable.
To apply only a browser configuration edit after initialization:

```sh
docker compose --env-file secrets.env up -d --no-deps --force-recreate management
```

For updates, review the new image digest alongside the API/client compatibility
notes; pulling an unchanged digest does not update the application.

## Verify in a browser

1. Open `/management/` over HTTPS and check the runtime configuration/asset
   requests load successfully.
2. Confirm API calls use the public `/api` URL, not an internal container name.
3. Sign in with an authorized account and inspect an administration page.
4. Reload a nested route and complete the actual sign-in callback flow.
5. Verify a non-administrator does not gain administration access.

If the shell loads but sign-in fails, inspect actual callback URLs, trusted
origins and the API auth logs. If assets return 404 or HTML instead of JavaScript,
check `BASE_HREF` and proxy prefix handling. After bootstrap, disable the server's
admin seeder and recreate API/jobs. Never publish working bootstrap credentials.