# frontend-service local dev

This directory contains a docker compose + Tilt setup for running a full frontend service stack locally. It contains:

- frontend-service
- backend api
- static asset cdn.

## Getting started

On top of the main Grafana development dependencies, you will need installed:

- [Docker](https://docs.docker.com/get-started/get-docker/)
- [Tilt](https://docs.tilt.dev/install.html). At the moment we're not using Kubernetes locally, so you shouldn't need to follow the instructions to install kubectl or kind.

To start the stack, from the root of the Grafana project run `make frontend-service`. Tilt will orchestrate the webpack and docker builds, and then run the services with Docker compose. You can monitor it's progress and see logs with the URL to the Tilt console. Once done, you can access Grafana at `http://localhost:3000`.

Quitting the process will stop the service from running.

### Grafana config

The Grafana API and frontend-service containers are configured in two places:

- `GF_` environment variables in the docker-compose file. Config specific to this development stack, that should be the same for everyone, is set here.

- `configs/{frontend-service,grafana-api}.local.ini` file is where you can set your own personal config values, such as feature toggles. This file is git-ignored.

### Frontend Observability (Faro)

The frontend-service setup includes Grafana Alloy configured to receive Faro (Grafana JavaScript Agent) data directly from the frontend. Faro is **enabled by default** and configured via environment variables in `docker-compose.yaml`:

- `GF_LOG_FRONTEND_ENABLED=true` - Enables Faro data collection
- `GF_LOG_FRONTEND_CUSTOM_ENDPOINT=http://localhost:12347/collect` - Sends data to Alloy's Faro receiver

Faro data (logs, measurements, exceptions) will be sent directly to Alloy's Faro receiver on port 12347, which forwards:

- **Logs** → Loki (queryable with `{job="faro"}`)
- **Traces** → Tempo

You can query Faro logs in Grafana using LogQL:

```
{job="faro"} | json
```

**To enable Faro after configuration changes:** If you've just added or modified the Faro configuration, you need to restart the services. If Tilt is running, it should automatically detect the changes and restart the affected services (`frontend-service` and `alloy`). If not, restart Tilt by stopping (`Ctrl+C`) and running `make frontend-service` again.

To disable Faro or customize the endpoint, you can override these settings in `configs/frontend-service.local.ini`:

```ini
[log.frontend]
enabled = false  # Set to false to disable
custom_endpoint = http://your-custom-endpoint/collect  # Override endpoint
```

### Bootdata unavailable

To simulate the `/bootdata` endpoint being available, there are special control URLs you can visit that use cookies to control behaviour:

- `/-/down` - Simulates the endpoint being unavailable for 60 seconds.
- `/-/down/:seconds` - Simulates the endpoint being unavailable for a custom number of seconds.
- `/-/up` - Restores the endpoint to being available.

When unavailable, the API will return `HTTP 503 Service Unavailable` with a JSON payload.

### Leave service running

By default, Tilt services stay running after you close the CLI, but `make frontend-service` wraps Tilt and auto shuts down the services. Set the environment variable `AUTO_DOWN=false` when running `make frontend-service` to leave the services running after quitting make. This is useful if you're restarting tilt often in quick succession for developing it.
