Skip to content
Docs BETA

Deploy the dashboard

Goal

For platform teams. In this task you run the service of the Platform dashboard, and you give people an address where they sign in and use the dashboard. Use the Platform dashboard describes the pages.

The dashboard has one service. It signs people in, it forwards their calls to the control plane, and it serves the pages of the dashboard.

Before you start

This is not available yet. Joomiz has no public download for the image of the dashboard service or for the pages of the dashboard. Ask the team that gives you the Joomiz platform for them, and use the image name where this page says <dashboard image>.

Steps

Know the settings

Every setting begins with joomiz.dashboard. The service checks them at the start. A missing or wrong value stops the start, and the report names the setting.

Setting Environment variable Required What it is
public-url JOOMIZ_DASHBOARD_PUBLICURL Yes The address that people type. It uses https. It has no path.
control-plane.url JOOMIZ_DASHBOARD_CONTROLPLANE_URL Yes The address of the API of the control plane. It has no path.
control-plane.management-url JOOMIZ_DASHBOARD_CONTROLPLANE_MANAGEMENTURL Yes The address of the management port of the control plane. It has no path. The dashboard reads the readiness check there.
oauth.issuer-uri JOOMIZ_DASHBOARD_OAUTH_ISSUERURI Yes The issuer of your identity provider.
oauth.client-id JOOMIZ_DASHBOARD_OAUTH_CLIENTID Yes The client ID of the dashboard.
oauth.client-secret JOOMIZ_DASHBOARD_OAUTH_CLIENTSECRET Yes The client secret of the dashboard. See the next step.
oauth.scope JOOMIZ_DASHBOARD_OAUTH_SCOPE Yes The scopes to ask for, separated by spaces. Ask for the scope of the API of Joomiz and offline_access. Do not write openid.
oauth.audience JOOMIZ_DASHBOARD_OAUTH_AUDIENCE Yes The audience of the control plane. It is the value of joomiz.auth.audience there.
static-location JOOMIZ_DASHBOARD_STATICLOCATION No The folder of the pages. See "Serve the pages".
session.idle-timeout JOOMIZ_DASHBOARD_SESSION_IDLETIMEOUT No How long a person may be idle before the sign-in ends. The default is 30m.
session.absolute-timeout JOOMIZ_DASHBOARD_SESSION_ABSOLUTETIMEOUT No The longest time of one sign-in. The default is 8h.

Each timeout is from 1 minute to 24 hours. The idle time must not be longer than the absolute time.

The service listens on port 8090 for the site, and on port 8091 for the health paths /health, /health/liveness and /health/readiness. The settings server.port and management.server.port change them.

Use https addresses for the control plane and for the issuer. For an http address that is not on the same machine, the service writes a warning to its log.

This is the report of a start with no setting. The text is cut to the lines that name the settings:

Reason: joomiz.dashboard.public-url is required
Reason: joomiz.dashboard.control-plane.url is required
Reason: joomiz.dashboard.control-plane.management-url is required
Reason: joomiz.dashboard.oauth.issuer-uri is required
Reason: joomiz.dashboard.oauth.client-id is required
Reason: joomiz.dashboard.oauth.client-secret is required
Reason: joomiz.dashboard.oauth.scope is required
Reason: joomiz.dashboard.oauth.audience is required

Give the client secret

The client secret has no default. Give it to the service in one of two ways, from your secret store:

Do not write the secret in a file of a project, in an image, or on a command line. The service never prints it.

Start the service

This command takes the values from the environment of the shell. DASHBOARD_SECRETS_DIR is the folder on the host that holds the secret file. The command mounts it:

docker run --detach --name joomiz-dashboard --publish 8090:8090 --publish 8091:8091 \
  --volume "$DASHBOARD_SECRETS_DIR":/run/secrets/joomiz-dashboard:ro \
  --env JOOMIZ_DASHBOARD_PUBLICURL --env JOOMIZ_DASHBOARD_CONTROLPLANE_URL \
  --env JOOMIZ_DASHBOARD_CONTROLPLANE_MANAGEMENTURL --env JOOMIZ_DASHBOARD_OAUTH_ISSUERURI \
  --env JOOMIZ_DASHBOARD_OAUTH_CLIENTID --env JOOMIZ_DASHBOARD_OAUTH_SCOPE \
  --env JOOMIZ_DASHBOARD_OAUTH_AUDIENCE \
  <dashboard image>

The service keeps the sessions of the people in its memory. Give the process at least 512 MB of heap, and expect a restart to sign people out.

Serve the pages

The service serves the pages of the dashboard from a folder. The folder must hold index.html and 404.html. If it does not, the service does not start:

Reason: joomiz.dashboard.static-location must hold an index.html
Reason: joomiz.dashboard.static-location must hold a 404.html

Use the folder that is in your image. To serve another folder, mount it and set joomiz.dashboard.static-location to file: and the path of the folder, with a slash at the end.

An image with no pages serves one placeholder page at /, and 404 for the other addresses.

Forward the Host header

Put a reverse proxy or an ingress in front of the service, at the public address. The proxy must forward the original Host header, which is the host of public-url.

If people see this at the public address, the proxy sends another Host:

HTTP 400

Check

  1. The health path of the service answers UP. Replace $DASHBOARD_MANAGEMENT_URL with the address of port 8091:
curl -s -w '\nHTTP %{http_code}\n' "$DASHBOARD_MANAGEMENT_URL/health/readiness"

{"status":"UP"}
HTTP 200
  1. The pages answer at the public address. This check sends the Host of the public address to the service directly. At the public address itself, call it without the -H option:
for path in / /runs /audit /runs.html; do curl -s -o /dev/null -w "$path HTTP %{http_code}\n" -H 'Host: dashboard.example.com' "$DASHBOARD_URL$path"; done

/ HTTP 200
/runs HTTP 200
/audit HTTP 200
/runs.html HTTP 404

The address /runs.html is 404 on purpose. Each page has one address, with no .html.

  1. A call with no sign-in gets 401. The pages use this answer to show Sign in to continue:
curl -s -w '\nHTTP %{http_code}\n' -H 'Host: dashboard.example.com' "$DASHBOARD_URL/api/session"

{"type":"about:blank","title":"Sign in to continue.","status":401}
HTTP 401
  1. The address /login sends the browser to your identity provider. The output is cut after the scope, and the address of the issuer is an example:
curl -s -D - -o /dev/null -H 'Host: dashboard.example.com' "$DASHBOARD_URL/login"

HTTP/1.1 302 
Location: https://idp.example.com/authorize?response_type=code&client_id=joomiz-dashboard&scope=api://joomiz-docs/user_impersonation%20offline_access
  1. Open the public address in a browser, sign in as an operator, and open the page Overview. The block Control plane shows Up.

Troubleshooting

Symptom Cause Fix
The container ends and the report names a setting A required setting is missing or wrong. Set it, and start again.
The report says oauth.scope must not contain openid The scope has openid. Remove it.
The report says static-location must hold an index.html The folder is wrong, or it has no pages. Check the path, and check that the folder holds index.html and 404.html.
The container ends and the log names the issuer The service cannot read the discovery document of the issuer. Check JOOMIZ_DASHBOARD_OAUTH_ISSUERURI and the network.
Every request at the public address gets 400 The proxy does not forward the Host of public-url. Forward the original Host.
The sign-in ends on an error page of the dashboard The identity provider refused the sign-in: the redirect address is not registered for the client, or the client secret is wrong. Register the public address with /login/callback. Check the secret.
After sign-in, the pages say Operator role needed The token has no operator role. Give the user the role at the identity provider.
The page Overview shows Down The control plane is not ready. Check health and follow a run explains the check.
People are signed out after a restart The sessions are in memory. This is expected. Sign in again.

Next

List what your identity provider must offer in Connect an identity provider.