# Dashboard Access and Recovery (/operate/dashboard-access)



## Docker dashboard access [#docker-dashboard-access]

<Callout type="warn" title="Pending a KubeMQ image release">
  This page describes the Docker first-login behavior in the next KubeMQ image. Existing
  images and existing storage retain their configured administrator behavior.
</Callout>

For a fresh standalone Docker volume, open
[`http://localhost:8080`](http://localhost:8080). The first visitor creates the
administrator username and a password of at least 12 bytes. KubeMQ signs that user in
immediately after the matching password confirmation. No setup token, generated password,
reverse proxy, or second password change is required for this local HTTP flow.

The default Docker and Compose commands publish port `8080` as
`127.0.0.1:8080:8080`. The dashboard and management API stay on your local machine.
Messaging traffic remains available through its configured ports and authentication.

## Returning users and seeded accounts [#returning-users-and-seeded-accounts]

Sign in with the username and password created on the first visit. The `kubemq-data`
named volume persists that account across restarts and container replacement. Keep the
volume mounted at `/kubemq/store`.

For the fresh Docker first-login flow, leave `API_AUTH_ENABLE` unset and create the
administrator in the browser. To use the older explicit seeded-account configuration, set
`API_AUTH_ENABLE=true`, `API_ALLOW_ORIGINS=https://dashboard.example.com`, and
`API_AUTH_TRUSTED_TLS_PROXY=true` behind a TLS-terminating proxy for that exact HTTPS origin.
Also set `KUBEMQ_API_ADMIN_PASSWORD` (or `KUBEMQ_API_ADMIN_PASSWORD_FILE`) and optionally
`KUBEMQ_API_ADMIN_USERNAME`; an unset username is `admin`. A seeded administrator must
change its password after the first sign-in. On later starts an existing administrator
remains authoritative; seed variables do not overwrite it unless you use recovery.

Set `API_AUTH_ENABLE=false` only when you intentionally need an unauthenticated
management API and dashboard. An explicit value is honored. Existing unconfigured storage
keeps its prior authentication mode.

## Reset a forgotten password [#reset-a-forgotten-password]

Stop the regular Compose container, then run a one-off server against the same named
volume. Set `KUBEMQ_API_ADMIN_USERNAME` to the exact username you originally chose.

<Steps>
  <Step>
    ```bash title="Terminal"
    export KUBEMQ_API_ADMIN_USERNAME=YOUR_EXISTING_USERNAME
    read -rsp 'New dashboard password: ' KUBEMQ_API_ADMIN_PASSWORD; echo
    export KUBEMQ_API_ADMIN_PASSWORD
    docker compose stop kubemq
    ```
  </Step>

  <Step>
    ```bash title="Terminal"
    docker compose run --rm --no-deps \
      -e KUBEMQ_API_ADMIN_USERNAME \
      -e KUBEMQ_API_ADMIN_PASSWORD \
      kubemq /kubemq/kubemq-run --reset-admin-password
    ```

    Wait for the `admin password force-reset applied` message and for the one-off server to
    become ready. It stays in the foreground because the reset flag starts a server. Press
    Control+C only after that, then start the normal container.
  </Step>

  <Step>
    ```bash title="Terminal"
    docker compose up -d
    unset KUBEMQ_API_ADMIN_PASSWORD KUBEMQ_API_ADMIN_USERNAME
    ```
  </Step>
</Steps>

The command passes `--reset-admin-password` to the KubeMQ image and preserves the named
volume. For a mounted secret file, export `KUBEMQ_API_ADMIN_PASSWORD_FILE` with its
in-container path, then replace `KUBEMQ_API_ADMIN_PASSWORD` with
`KUBEMQ_API_ADMIN_PASSWORD_FILE` in the command and its `-e` argument. The username must
still match the existing administrator. Do not run `docker compose down -v` or delete
`/kubemq/store` to recover access.

If the authentication database is missing, restore the original `/kubemq/store` volume
or a backup when available. Without a backup, stop the regular container and repeat the
one-off command above with `--clean-accounts --reset-admin-password` in place of
`--reset-admin-password`. Set the administrator username and a new password first.
This rebuilds administrator access without deleting broker messages, but any previous
management accounts and service-account keys must be recreated. Stop the one-off server
after it becomes ready, then start the regular container. Never delete the volume or
onboarding state to reset access.

For a corrupt onboarding marker or database, restore a valid volume or backup. Contact
[support@kubemq.io](mailto:support@kubemq.io) if no valid backup is available.

## License, port, and access problems [#license-port-and-access-problems]

A keyless 14-day Docker evaluation and a trial or paid license are separate from
dashboard credentials. A license error can stop the server before it exposes the dashboard.
Check `docker logs kubemq`, then follow [evaluation troubleshooting](/licensing/evaluation#startup-messages)
or use a [trial key](/licensing/trial) while keeping the same volume.

The dashboard can create a `read_write` service-account key for `kmq` or other management
automation. That `kmq_...` Bearer key is separate from `KUBEMQ_LICENSE_KEY`; a license key
does not authenticate a management client.

The dashboard and management API use port `8080`. Messaging clients use ports such as
gRPC `50000` and REST `9090`; a dashboard sign-in problem does not by itself stop those
clients.

## Kubernetes dashboard access [#kubernetes-dashboard-access]

Kubernetes keeps management authentication explicit. Set `spec.api.auth.enable: true`.
Without `spec.api.auth.adminSecretRef`, the operator creates and retains a Secret named
`<cluster>-api-admin`. Its password key defaults to `admin-password`.

Use the exact browser-facing HTTPS origin in `spec.api.allowOrigins`. Wildcard or empty
origins are rejected when management authentication is enabled.

```yaml title="kubemqcluster.yaml"
spec:
  api:
    allowOrigins:
      - https://dashboard.example.com
    auth:
      enable: true
      trustedTLSProxy: true
```

```bash title="Terminal"
kubectl get secret -n YOUR_NAMESPACE YOUR_CLUSTER-api-admin \
  -o jsonpath='{.data.admin-password}' | base64 --decode; echo
```

Sign in as `spec.api.auth.adminUsername`, or `admin` when that field is unset. If you set
`spec.api.auth.adminSecretRef`, read that supplied Secret using its configured
`spec.api.auth.adminSecretKey` instead. The operator does not overwrite a supplied Secret.

Browser session sign-in requires HTTPS. Put the API behind a TLS-terminating proxy and set
`spec.api.auth.trustedTLSProxy: true`; this allows the server to issue its secure session
cookie for the browser-facing HTTPS origin. A plain `kubectl port-forward` is useful for
probes, but it does not provide a secure browser session. See
[Kubernetes with Helm](/deploy/kubernetes-helm) and [Security](/configure/reference/security).

Browser sessions are currently local to one pod. Route a browser consistently to the same
pod after sign-in. Log in again after that pod is replaced. If a load balancer sends the
browser to different pods and creates repeated login loops, configure its session affinity
or contact [support@kubemq.io](mailto:support@kubemq.io).

For help, email [support@kubemq.io](mailto:support@kubemq.io) or open an issue in the
[KubeMQ community repository](https://github.com/kubemq-io/kubemq-community).