Grafana

Open-source dashboards and observability platform. Grafana connects to data sources like Prometheus, Loki, and PostgreSQL, then lets you build panels and alerts on top of them. It doesn't collect data itself -- it visualizes what other tools collect.

Quick Setup (Docker Compose)

Add Grafana to an existing docker-compose.yml:

grafana:
  image: grafana/grafana:11.5.2
  container_name: grafana
  ports:
    - "3000:3000"
  environment:
    - GF_SECURITY_ADMIN_USER=admin
    - GF_SECURITY_ADMIN_PASSWORD=changeme
  volumes:
    - grafana-data:/var/lib/grafana
  restart: unless-stopped

volumes:
  grafana-data:

docker compose up -d grafana

Open http://your-server:3000 and log in with the credentials above.

Adding a Data Source

Go to Connections > Data sources > Add data source. For Prometheus (the most common pairing):

• Type: Prometheus
• URL: http://prometheus:9090 (if both are in the same Docker network) or http://your-server:9090 if external
• Click Save & test

If the test fails, it's almost always a networking issue. Containers on the same Docker Compose network can reach each other by service name. Containers on different networks need the host IP.

Dashboard Provisioning

Manually creating dashboards through the UI is fine for experimenting, but for anything you want to survive a container rebuild, use provisioning.

Create a provisioning config:

# grafana/provisioning/datasources/datasources.yml
apiVersion: 1
datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true
    editable: false

# grafana/provisioning/dashboards/dashboards.yml
apiVersion: 1
providers:
  - name: default
    folder: ""
    type: file
    options:
      path: /var/lib/grafana/dashboards

Mount both into the container:

volumes:
  - grafana-data:/var/lib/grafana
  - ./grafana/provisioning:/etc/grafana/provisioning:ro
  - ./grafana/dashboards:/var/lib/grafana/dashboards:ro

Drop .json dashboard files into ./grafana/dashboards/ and they'll load automatically on startup. Export existing dashboards from the UI via Dashboard settings > JSON Model > Copy.

Configuration Notes

• Version pinning: Always pin to a specific tag (e.g. 11.5.2), not latest. Grafana upgrades occasionally change dashboard JSON schemas, and you don't want that happening in a docker compose pull.
• Persistent storage: The grafana-data volume holds dashboard state, user accounts, and alert history. Lose the volume, lose all of that (unless you provisioned everything from files).
• Default home dashboard: Set GF_DASHBOARDS_DEFAULT_HOME_DASHBOARD_PATH=/var/lib/grafana/dashboards/your-dashboard.json to skip the default Grafana welcome screen.
• Anonymous access: For kiosk/TV dashboard setups, enable GF_AUTH_ANONYMOUS_ENABLED=true and GF_AUTH_ANONYMOUS_ORG_ROLE=Viewer. Don't do this on anything internet-facing.
• Port 3000 conflicts with a lot of things (Next.js dev server, for one). Change it with GF_SERVER_HTTP_PORT or just remap in Compose: "3001:3000".

Troubleshooting

"Datasource is not available" after adding Prometheus -- The URL is wrong or the containers aren't on the same network. Use docker network ls and docker network inspect to verify both containers share a network. Use the service name, not localhost.

Dashboards disappear after restart -- You're editing provisioned dashboards in the UI. Provisioned dashboards are read-only by default; edits aren't saved back to the JSON file. Either edit the JSON file directly and restart, or set editable: true in the provider config (but then you need to re-export manually).

"No data" on panels -- Check the time range picker (top right). Grafana defaults to "Last 6 hours" but your data might only go back a few minutes if you just started Prometheus.