Dashboard Access and Recovery

Docker dashboard access

For a fresh standalone Docker volume, open 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

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

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.

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

docker compose run --rm --no-deps \
  -e KUBEMQ_API_ADMIN_USERNAME \
  -e KUBEMQ_API_ADMIN_PASSWORD \
  kubemq /kubemq/kubemq-run --reset-admin-password

docker compose up -d
unset KUBEMQ_API_ADMIN_PASSWORD KUBEMQ_API_ADMIN_USERNAME

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 if no valid backup is available.

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 or use a trial key 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 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.

spec:
  api:
    allowOrigins:
      - https://dashboard.example.com
    auth:
      enable: true
      trustedTLSProxy: true

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 and 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.

For help, email support@kubemq.io or open an issue in the KubeMQ community repository.