# Dashboard


Francis has a web dashboard for the [management API](/docs/management-api.md), built into the runtime binary and container image. You can use it in three ways:

- [Next to the management API](#next-to-the-management-api), served by a runtime on the same listener as the API.
- [Standalone](#standalone), served by the `francis dashboard` command, connecting to the endpoints you add.
- [Hosted](#hosted), at [my.gofrancis.dev](https://my.gofrancis.dev), with nothing to run, connecting to the endpoints you add.

## Next to the management API

When the runtime serves the [management API](/docs/management-api.md#enabling-the-api), it also serves the dashboard on the same listener, at the root path. Open `http://<runtime address>:7401/` in a browser (or `https://<runtime address>:7401/` if you configured TLS).

With the Helm chart, the management Service serves it. For example:

```sh
kubectl port-forward -n francis svc/<release>-francis-management 7401:7401
```

Then open `http://localhost:7401/`.

Hosts in the local (embedded) topology serve only the API: use a [standalone dashboard](#standalone) to browse them.

## Standalone

The runtime binary can also serve the dashboard on its own, without a configuration file and without connecting to any cluster:

```sh
francis dashboard
```

It listens on `127.0.0.1:7402` by default. Change it with the `-bind` and `-port` flags, for example `francis dashboard -bind 0.0.0.0 -port 8080`. The command serves plain HTTP and prints a warning when it's reachable from other machines: in that case, put it behind a TLS-terminating proxy.

In the standalone dashboard, add the endpoints to connect to, with the address and port of a runtime's or a local host's management API. Before it saves an endpoint, the dashboard checks that the endpoint answers and allows the dashboard's origin. The browser keeps the list in its local storage, and the dashboard asks for a token each time you connect to an endpoint. The sidebar shows the endpoint you're connected to under **Sign out**, which takes you back to the list.

### Allowing the dashboard's origin

The dashboard calls each endpoint from the browser across origins, so every endpoint must allow the dashboard's origin, such as `http://localhost:7402`.

In the runtime's configuration:

```yaml
management:
  allowedOrigins:
    - "http://localhost:7402"
```

With the Helm chart, set `management.allowedOrigins` the same way. In the local topology, set `AllowedOrigins` in `local.ManagementOptions`:

```go
local.WithManagementAPI(local.ManagementOptions{
	// ...
	AllowedOrigins: []string{"http://localhost:7402"},
})
```

Optionally use the wildcard `"*"` to allow any origin, although this is not recommended in production.

When an endpoint doesn't allow the origin, adding it fails with a message that names the origin to add. Signing in to a saved endpoint that no longer allows it fails the same way.

## Hosted

The hosted dashboard at [my.gofrancis.dev](https://my.gofrancis.dev) is the [standalone dashboard](#standalone), without anything to install or run: open it, add your endpoints, and sign in to them.

The hosted dashboard runs entirely in your browser and doesn't log or store any of your data. Your browser connects to the endpoints directly, and keeps the list of endpoints in its local storage. The service is free to use and offered on a best-effort basis.

Because your browser connects to the endpoints directly, each endpoint must be reachable from it, and must allow the hosted dashboard's origin, `https://my.gofrancis.dev`:

```yaml
management:
  allowedOrigins:
    - "https://my.gofrancis.dev"
```

For the Helm chart and the local topology, see [Allowing the dashboard's origin](#allowing-the-dashboards-origin).

The hosted dashboard is served over HTTPS, and browsers block an HTTPS page's requests to plain HTTP addresses, so each endpoint must serve the management API over HTTPS, with a certificate your browser trusts. Some browsers also ask for your permission before a public site connects to an address on your local network. To connect to endpoints without TLS, use the [standalone dashboard](#standalone).

