|
1 | | -# grafana-image-renderer |
| 1 | +# Documentation |
2 | 2 |
|
3 | | -A backend service for Grafana. |
4 | | -It provides panel and dashboard rendering with a headless browser (Chromium). |
5 | | -You can get your favourite dashboards as PDFs, PNGs, or with Grafana Enterprise, CSVs and even over emails with Grafana Reports. |
| 3 | +If you're not in the docs directory, you can either `cd` in, or use `make -C |
| 4 | +docs <target...>`. |
6 | 5 |
|
7 | | -## Installation |
| 6 | +To run a dev server, run `make docs`. This will automatically rebuild and |
| 7 | +refresh on changes. |
8 | 8 |
|
9 | | -To install the service, you are recommended to use Docker or other containerisation software. |
10 | | -We [ship images][image] for `linux/amd64` and `linux/arm64`; Windows and macOS can run these with Docker Desktop as well. |
11 | | -We do not currently ship a binary you can run, nor do we ship a plugin. |
12 | | - |
13 | | -To run the service in a stable manner, you are recommended to have a minimum of 16 GiB memory allocated to this service. |
14 | | -You may also require a relatively modern CPU for decent output speeds. |
15 | | - |
16 | | -### Install with Docker |
17 | | - |
18 | | -While we ship a `latest` tag, you should generally prefer pinning a specific version in production environments. |
19 | | -We do, however, commit to keeping the `latest` tag the latest stable release. |
20 | | - |
21 | | -```shell |
22 | | -$ docker network create grafana |
23 | | -$ docker run --network grafana --name renderer --rm --detach grafana/grafana-image-renderer:latest |
24 | | -# The following is not a production-ready Grafana instance, but shows what env vars you should set: |
25 | | -$ docker run --network grafana --name grafana --rm --detach --env GF_RENDERING_SERVER_URL=http://renderer:8081/render --env http://grafana:3000/ --port 3000:3000 grafana/grafana-enterprise:latest |
26 | | -``` |
27 | | - |
28 | | -Alternatively, if you prefer `docker compose`: |
29 | | - |
30 | | -```yaml |
31 | | -services: |
32 | | - renderer: |
33 | | - image: grafana/grafana-image-renderer:latest |
34 | | - |
35 | | - grafana: |
36 | | - image: grafana/grafana-enterprise:latest |
37 | | - ports: |
38 | | - - "3000:3000" |
39 | | - environment: |
40 | | - GF_RENDERING_SERVER_URL: http://renderer:8081/render |
41 | | - GF_RENDERING_CALLBACK_URL: http://grafana:3000/ |
42 | | -``` |
43 | | -
|
44 | | -If you are running with memory limits, you may want to set `GOMEMLIMIT` to a lower value than the limit, such as `1GiB`. |
45 | | -You should not aim for the `GOMEMLIMIT` to match the container's limit: Chromium needs free memory on top. |
46 | | -We recommend 1 GiB of `GOMEMLIMIT` per 8 GiB of container memory limit. |
47 | | - |
48 | | -[image]: https://hub.docker.com/r/grafana/grafana-image-renderer |
49 | | - |
50 | | -### Configuration |
51 | | - |
52 | | -The service can be configured via several paths: |
53 | | - |
54 | | -- Set CLI flags. See `--help` for the available flag names. |
55 | | -- Use environment variables. See `--help` for the names and current values. |
56 | | - Most, but not all, variables map 1:1 to the CLI flag names. |
57 | | -- Use a JSON or YAML configuration file. This must be in the service's current working directory, |
58 | | - and must be named one of `config.json`, `config.yaml`, or `config.yml`. Dot-separated keys are |
59 | | - nested keys. E.g.: `a.b` becomes `{"a": {"b": "VALUE"}}` in the file. |
60 | | - |
61 | | -The current configuration options can all be accessed by checking `--help`. |
62 | | - |
63 | | -As an example, see: `docker run --rm grafana/grafana-image-renderer:latest server --help`. |
64 | | - |
65 | | -### Security |
66 | | - |
67 | | -The service requires a secret token to be present in all render requests. |
68 | | -This token is set by `--server.auth-token` (`AUTH_TOKEN`); you can specify multiple and have a unique key per Grafana instance. |
69 | | -By default, the token used is `-`. |
70 | | -In Grafana, you must set this to match one of the tokens with the `[rendering] renderer_token` (`GF_RENDERING_RENDERER_TOKEN`) setting. |
71 | | - |
72 | | -### Monitoring |
73 | | - |
74 | | -You can monitor the service via Prometheus/[Mimir](https://grafana.com/oss/mimir) and any OpenTelemetry-compatible Tracing backend (like [Grafana Tempo](https://grafana.com/oss/tempo)). |
75 | | -Metrics are exposed on `/metrics` and traces are sent as configured in the configuration options (see `--help`). |
76 | | - |
77 | | -## Compile |
78 | | - |
79 | | -To compile the Go service, run: |
80 | | - |
81 | | -```shell |
82 | | -$ go build -buildvcs -o grafana-image-renderer . |
83 | | -``` |
84 | | - |
85 | | -To compile the Docker image, run: |
86 | | - |
87 | | -```shell |
88 | | -$ docker build . |
89 | | -``` |
90 | | - |
91 | | -The following tools are also useful for engineers: |
92 | | - |
93 | | -```shell |
94 | | -$ go tool goimports # our code formatter of choice |
95 | | -$ golangci-lint run # our linter of choice |
96 | | -$ IMAGE=tag-here go test ./tests/acceptance/... -count=1 # run acceptance tests |
97 | | -``` |
98 | | - |
99 | | -## Release |
100 | | - |
101 | | -When you are ready to make a release, tag it in Git (`git tag vX.Y.Z`; remember the `v` prefix), then push it. |
102 | | -GitHub Actions deals with the build and deployment. |
| 9 | +To run Vale, run `make vale`. |
0 commit comments