mirror of
https://github.com/grafana/grafana.git
synced 2025-08-03 05:08:36 +08:00
Docs/docker compose update (#64565)
* added CLI in heading for clearity * added new heading * new change * updated final version for review * fix small line breaks * copy edit, restructuring * Apply suggestions from code review * Apply suggestions from code review * removed internal notes * updateding the docker configuraiton file which have advanced instructions * Update docs/sources/setup-grafana/installation/docker/index.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/installation/docker/index.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/installation/docker/index.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/installation/docker/index.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/installation/docker/index.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/installation/docker/index.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/installation/docker/index.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/installation/docker/index.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * updated persistent stroage section * updated heading typo * Update docs/sources/setup-grafana/installation/docker/index.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/installation/docker/index.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/installation/docker/index.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/installation/docker/index.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/installation/docker/index.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/installation/docker/index.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/installation/docker/index.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/installation/docker/index.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/installation/docker/index.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/installation/docker/index.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * fixed code identation and minor typos * added yaml file validation check in the troubleshooting section * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-docker.md added "also" Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * add more details to apline, cloudwatch and default path sections * Apply suggestions from code review Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * added more detailes about docker ubuntu image, fixed headings, added more clarity to the persistent vs bind stroage * Apply suggestions from code review Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * added more improvements for the examples * Update docs/sources/setup-grafana/installation/docker/index.md * Update docs/sources/setup-grafana/installation/docker/index.md * Update docs/sources/setup-grafana/installation/docker/index.md * Update docs/sources/setup-grafana/configure-docker.md * updates links, edits Troubleshooting section * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Dan Cech <dcech@grafana.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Dan Cech <dcech@grafana.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Dan Cech <dcech@grafana.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Dan Cech <dcech@grafana.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Dan Cech <dcech@grafana.com> * fixes doc-validator issues * adds link to plugin install instructions * added improvement in the AWS cloudwatch example * Update docs/sources/setup-grafana/configure-docker.md * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Apply suggestions from code review suggestions looks good Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * added dan suggestion for the tags, but skip the longer description part as not really useful for end user * Update docs/sources/setup-grafana/installation/docker/index.md Co-authored-by: Dan Cech <dcech@grafana.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Dan Cech <dcech@grafana.com> * Update docs/sources/setup-grafana/configure-docker.md Co-authored-by: Dan Cech <dcech@grafana.com> * Apply suggestions from code review looks good Co-authored-by: Dan Cech <dcech@grafana.com> * added missing version * fixed identation and small typo * fixed the pwd data folder instruction * fixed persistent volume creating and identation * fixed identation * fixed typo to get debug logs * fixed custom plugin installation section * created docker secret command instructions * fixed missing path * fixed code in docker secret and other minor typos * incorporates feedback, copy edits secrets section * fixed small typo in docker secrets section * remove the additonal info command for secrets * combined custom docker pre-installed plugin section as one * fixed the build link typo * various updates/fixes * another fix * added more clarity to the volume creating command * fixed command for bind mounts * fixed missing comman in the plugin command * fixed small typo * improve and simplifly the steps instructions * fixed validation command * Apply suggestions from code review looks good!! Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * fixed typo in docker secret command explaination * fixed minor stuff * makes prettier --------- Co-authored-by: Chris Moyer <chris.moyer@grafana.com> Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> Co-authored-by: Dan Cech <dcech@grafana.com>
This commit is contained in:
Usman Ahmad
@ -8,48 +8,81 @@ keywords:
|
||||
- configuration
|
||||
- documentation
|
||||
- docker
|
||||
menuTitle: Configure Docker image
|
||||
- docker compose
|
||||
title: Configure a Grafana Docker image
|
||||
menuTitle: Configure a Docker image
|
||||
weight: 1800
|
||||
---
|
||||
|
||||
# Configure a Grafana Docker image
|
||||
|
||||
If you are running Grafana in a Docker image, then you configure Grafana using [environment variables]({{< relref "./configure-grafana#override-configuration-with-environment-variables" >}}) rather than directly editing the configuration file. If you want to save your data, then you also need to designate persistent storage or bind mounts for the Grafana container.
|
||||
This topic explains how to run Grafana on Docker in complex environments that require you to:
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
These examples use the Grafana Enterprise docker image. You can use the Grafana Open Source edition by changing the docker image to `grafana/grafana-oss`.
|
||||
{{% /admonition %}}
|
||||
- Use different images
|
||||
- Change logging levels
|
||||
- Define secrets on the Cloud
|
||||
- Configure plugins
|
||||
|
||||
## Save your Grafana data
|
||||
> **Note:** The examples in this topic use the Grafana Enterprise Docker image. You can use the Grafana Open Source edition by changing the Docker image to `grafana/grafana-oss`.
|
||||
|
||||
If you do not designate a location for information storage, then all your Grafana data disappears as soon as you stop your container. To save your data, you need to set up persistent storage or bind mounts for your container.
|
||||
## Supported Docker image variants
|
||||
|
||||
### Run Grafana container with persistent storage (recommended)
|
||||
You can install and run Grafana using the following official Docker images.
|
||||
|
||||
- **Grafana Enterprise**: `grafana/grafana-enterprise`
|
||||
|
||||
- **Grafana Open Source**: `grafana/grafana-oss`
|
||||
|
||||
Each edition is available in two variants: Alpine and Ubuntu.
|
||||
|
||||
## Alpine image (recommended)
|
||||
|
||||
[Alpine Linux](https://alpinelinux.org/about/) is a Linux distribution not affiliated with any commercial entity. It is a versatile operating system that caters to users who prioritize security, efficiency, and user-friendliness. Alpine Linux is much smaller than other distribution base images, allowing for slimmer and more secure images to be created.
|
||||
|
||||
By default, the images are built using the widely used [Alpine Linux project](http://alpinelinux.org/) base image, which can be found in the [Alpine docker repo](https://hub.docker.com/_/alpine).
|
||||
If you prioritize security and want to minimize the size of your image, it is recommended that you use the Alpine variant. However, it's important to note that the Alpine variant uses [musl libc](http://www.musl-libc.org/) instead of [glibc and others](http://www.etalabs.net/compare_libcs.html). As a result, some software might encounter problems depending on their libc requirements. Nonetheless, most software should not experience any issues, so the Alpine variant is generally reliable.
|
||||
|
||||
## Ubuntu image
|
||||
|
||||
The Ubuntu-based Grafana Enterprise and OSS images are built using the [Ubuntu](https://ubuntu.com/) base image, which can be found in the [Ubuntu docker repo](https://hub.docker.com/_/ubuntu). An Ubuntu-based image can be a good option for users who prefer an Ubuntu-based image or require certain tools unavailable on Alpine.
|
||||
|
||||
- **Grafana Enterprise**: `grafana/grafana-enterprise:<version>-ubuntu`
|
||||
|
||||
- **Grafana Open Source**: `grafana/grafana-oss:<version>-ubuntu`
|
||||
|
||||
## Run a specific version of Grafana
|
||||
|
||||
You can also run a specific version of Grafana or a beta version based on the main branch of the [grafana/grafana GitHub repository](https://github.com/grafana/grafana).
|
||||
|
||||
> **Note:** If you use a Linux operating system such as Debian or Ubuntu and encounter permission errors when running Docker commands, you might need to prefix the command with `sudo` or add your user to the `docker` group. The official Docker documentation provides instructions on how to [run Docker without a non-root user](https://docs.docker.com/engine/install/linux-postinstall/).
|
||||
|
||||
To run a specific version of Grafana, add it in the command <version number> section:
|
||||
|
||||
```bash
|
||||
# create a persistent volume for your data in /var/lib/grafana (database and plugins)
|
||||
docker volume create grafana-storage
|
||||
|
||||
# start grafana
|
||||
docker run -d -p 3000:3000 --name=grafana -v grafana-storage:/var/lib/grafana grafana/grafana-enterprise
|
||||
docker run -d -p 3000:3000 --name grafana grafana/grafana-enterprise:<version number>
|
||||
```
|
||||
|
||||
### Run Grafana container using bind mounts
|
||||
Example:
|
||||
|
||||
You may want to run Grafana in Docker but use folders on your host for the database or configuration. When doing so, it becomes important to start the container with a user that is able to access and write to the folder you map into the container.
|
||||
The following command runs the Grafana Enterprise container and specifies version 9.4.7. If you want to run a different version, modify the version number section.
|
||||
|
||||
```bash
|
||||
mkdir data # creates a folder for your data
|
||||
ID=$(id -u) # saves your user id in the ID variable
|
||||
|
||||
# starts grafana with your user id and using the data folder
|
||||
docker run -d --user $ID --volume "$PWD/data:/var/lib/grafana" -p 3000:3000 grafana/grafana-enterprise:8.2.1
|
||||
docker run -d -p 3000:3000 --name grafana grafana/grafana-enterprise:9.4.7
|
||||
```
|
||||
|
||||
## Run the Grafana main branch
|
||||
|
||||
After every successful build of the main branch, two tags, `grafana/grafana-oss:main` and `grafana/grafana-oss:main-ubuntu`, are updated. Additionally, two new tags are created: `grafana/grafana-oss-dev:<version><build ID>-pre` and `grafana/grafana-oss-dev:<version><build ID>-pre-ubuntu`, where `version` is the next version of Grafana and `build ID `is the ID of the corresponding CI build. These tags provide access to the most recent Grafana main builds. For more information, refer to [grafana/grafana-oss-dev](https://hub.docker.com/r/grafana/grafana-oss-dev/tags).
|
||||
|
||||
To ensure stability and consistency, we strongly recommend using the `grafana/grafana-oss-dev:<version><build ID>-pre` tag when running the Grafana main branch in a production environment. This tag ensures that you are using a specific version of Grafana instead of the most recent commit, which could potentially introduce bugs or issues. It also avoids polluting the tag namespace for the main Grafana images with thousands of pre-release tags.
|
||||
|
||||
For a list of available tags, refer to [grafana/grafana-oss](https://hub.docker.com/r/grafana/grafana-oss/tags/) and [grafana/grafana-oss-dev](https://hub.docker.com/r/grafana/grafana-oss-dev/tags/).
|
||||
|
||||
## Default paths
|
||||
|
||||
The following settings are hard-coded when launching the Grafana Docker container and can only be overridden using environment variables, not in `conf/grafana.ini`.
|
||||
Grafana comes with default configuration parameters that remain the same among versions regardless of the operating system or the environment (for example, virtual machine, Docker, Kubernetes, etc.). You can refer to the [Configure Grafana]({{< relref "./configure-grafana" >}}) documentation to view all the default configuration settings.
|
||||
|
||||
The following configurations are set by default when you start the Grafana Docker container. When running in Docker you cannot change the configurations by editing the `conf/grafana.ini` file. Instead, you can modify the configuration using [environment variables]({{< relref "./configure-grafana#override-configuration-with-environment-variables" >}}).
|
||||
|
||||
| Setting | Default value |
|
||||
| --------------------- | ------------------------- |
|
||||
@ -60,48 +93,262 @@ The following settings are hard-coded when launching the Grafana Docker containe
|
||||
| GF_PATHS_PLUGINS | /var/lib/grafana/plugins |
|
||||
| GF_PATHS_PROVISIONING | /etc/grafana/provisioning |
|
||||
|
||||
## Logging
|
||||
## Install plugins in the Docker container
|
||||
|
||||
Logs in the Docker container go to standard out by default, as is common in the Docker world. Change this by setting a different [log mode]({{< relref "./configure-grafana#mode" >}}).
|
||||
You can install publicly available plugins and plugins that are private or used internally in an organization. For plugin installation instructions, refer to [Install plugins in the Docker container]({{< relref "./installation/docker#install-plugins-in-the-docker-container" >}}).
|
||||
|
||||
### Install plugins from other sources
|
||||
|
||||
To install plugins from other sources, you must define the custom URL and specify it immediately before the plugin name in the `GF_INSTALL_PLUGINS` environment variable: `GF_INSTALL_PLUGINS=<url to plugin zip>;<plugin name>`.
|
||||
|
||||
Example:
|
||||
|
||||
The following command runs Grafana Enterprise on **port 3000** in detached mode and installs the custom plugin, which is specified as a URL parameter in the `GF_INSTALL_PLUGINS` environment variable.
|
||||
|
||||
```bash
|
||||
# Run Grafana while logging to both standard out and /var/log/grafana/grafana.log
|
||||
docker run -d -p 3000:3000 --name=grafana \
|
||||
-e "GF_INSTALL_PLUGINS=http://plugin-domain.com/my-custom-plugin.zip;custom-plugin,grafana-clock-panel" \
|
||||
grafana/grafana-enterprise
|
||||
```
|
||||
|
||||
## Build a custom Grafana Docker image
|
||||
|
||||
In the Grafana GitHub repository, the `packaging/docker/custom/` folder includes a `Dockerfile` that you can use to build a custom Grafana image. The `Dockerfile` accepts `GRAFANA_VERSION`, `GF_INSTALL_PLUGINS`, and `GF_INSTALL_IMAGE_RENDERER_PLUGIN` as build arguments.
|
||||
|
||||
The `GRAFANA_VERSION` build argument must be a valid `grafana/grafana` Docker image tag. By default, Grafana builds an Alpine-based image. To build an Ubuntu-based image, append `-ubuntu` to the `GRAFANA_VERSION` build argument.
|
||||
|
||||
Example:
|
||||
|
||||
The following example shows you how to build and run a custom Grafana Docker image based on the latest official Ubuntu-based Grafana Docker image:
|
||||
|
||||
```bash
|
||||
# go to the custom directory
|
||||
cd packaging/docker/custom
|
||||
|
||||
# run the docker build command to build the image
|
||||
docker build \
|
||||
--build-arg "GRAFANA_VERSION=latest-ubuntu" \
|
||||
-t grafana-custom .
|
||||
|
||||
# run the custom grafana container using docker run command
|
||||
docker run -d -p 3000:3000 --name=grafana grafana-custom
|
||||
```
|
||||
|
||||
### Build Grafana with the Image Renderer plugin pre-installed
|
||||
|
||||
> **Note:** This feature is experimental.
|
||||
|
||||
Currently, the Grafana Image Renderer plugin requires dependencies that are not available in the Grafana Docker image (see [GitHub Issue#301](https://github.com/grafana/grafana-image-renderer/issues/301) for more details). However, you can create a customized Docker image using the `GF_INSTALL_IMAGE_RENDERER_PLUGIN` build argument as a solution. This will install the necessary dependencies for the Grafana Image Renderer plugin to run.
|
||||
|
||||
Example:
|
||||
|
||||
The following example shows how to build a customized Grafana Docker image that includes the Image Renderer plugin.
|
||||
|
||||
```bash
|
||||
# go to the folder
|
||||
cd packaging/docker/custom
|
||||
|
||||
# running the build command
|
||||
docker build \
|
||||
--build-arg "GRAFANA_VERSION=latest" \
|
||||
--build-arg "GF_INSTALL_IMAGE_RENDERER_PLUGIN=true" \
|
||||
-t grafana-custom .
|
||||
|
||||
# running the docker run command
|
||||
docker run -d -p 3000:3000 --name=grafana grafana-custom
|
||||
```
|
||||
|
||||
### Build a Grafana Docker image with pre-installed plugins
|
||||
|
||||
If you run multiple Grafana installations with the same plugins, you can save time by building a customized image that includes plugins available on the [Grafana Plugin download page](/grafana/plugins). When you build a customized image, Grafana doesn't have to install the plugins each time it starts, making the startup process more efficient.
|
||||
|
||||
> **Note:** To specify the version of a plugin, you can use the `GF_INSTALL_PLUGINS` build argument and add the version number. The latest version is used if you don't specify a version number. For example, you can use `--build-arg "GF_INSTALL_PLUGINS=grafana-clock-panel 1.0.1,grafana-simple-json-datasource 1.3.5"` to specify the versions of two plugins.
|
||||
|
||||
Example:
|
||||
|
||||
The following example shows how to build and run a custom Grafana Docker image with pre-installed plugins.
|
||||
|
||||
```bash
|
||||
# go to the custom directory
|
||||
cd packaging/docker/custom
|
||||
|
||||
# running the build command
|
||||
# include the plugins you want e.g. clock planel etc
|
||||
docker build \
|
||||
--build-arg "GRAFANA_VERSION=latest" \
|
||||
--build-arg "GF_INSTALL_PLUGINS=grafana-clock-panel,grafana-simple-json-datasource" \
|
||||
-t grafana-custom .
|
||||
|
||||
# running the custom Grafana container using the docker run command
|
||||
docker run -d -p 3000:3000 --name=grafana grafana-custom
|
||||
```
|
||||
|
||||
### Build a Grafana Docker image with pre-installed plugins from other sources
|
||||
|
||||
You can create a Docker image containing a plugin that is exclusive to your organization, even if it is not accessible to the public. Simply use the `GF_INSTALL_PLUGINS` build argument to specify the plugin's URL and installation folder name, such as `GF_INSTALL_PLUGINS=<url to plugin zip>;<plugin install folder name>`.
|
||||
|
||||
The following example demonstrates creating a customized Grafana Docker image that includes a custom plugin from a URL link, the clock panel plugin, and the simple-json-datasource plugin. You can define these plugins in the build argument using the Grafana Plugin environment variable.
|
||||
|
||||
```bash
|
||||
# go to the folder
|
||||
cd packaging/docker/custom
|
||||
|
||||
# running the build command
|
||||
docker build \
|
||||
--build-arg "GRAFANA_VERSION=latest" \
|
||||
--build-arg "GF_INSTALL_PLUGINS=http://plugin-domain.com/my-custom-plugin.zip;my-custom-plugin,grafana-clock-panel,grafana-simple-json-datasource" \
|
||||
-t grafana-custom .
|
||||
|
||||
# running the docker run command
|
||||
docker run -d -p 3000:3000 --name=grafana grafana-custom
|
||||
```
|
||||
|
||||
## Logging
|
||||
|
||||
By default, Docker container logs are directed to `STDOUT`, a common practice in the Docker community. You can change this by setting a different [log mode]({{< relref "./configure-grafana#mode" >}}) such as `console`, `file`, or `syslog`. You can use one or more modes by separating them with spaces, for example, `console file`. By default, both `console` and `file` modes are enabled.
|
||||
|
||||
Example:
|
||||
|
||||
The following example runs Grafana using the `console file` log mode that is set in the `GF_LOG_MODE` environment variable.
|
||||
|
||||
```bash
|
||||
# Run Grafana while logging to both standard out
|
||||
# and /var/log/grafana/grafana.log
|
||||
|
||||
docker run -p 3000:3000 -e "GF_LOG_MODE=console file" grafana/grafana-enterprise
|
||||
```
|
||||
|
||||
## Configure Grafana with Docker Secrets
|
||||
|
||||
> Only available in Grafana v5.2 and later.
|
||||
You can input confidential data like login credentials and secrets into Grafana using configuration files. This method works well with [Docker Secrets](https://docs.docker.com/engine/swarm/secrets/), as the secrets are automatically mapped to the `/run/secrets/` location within the container.
|
||||
|
||||
It's possible to supply Grafana with configuration through files. This works well with [Docker Secrets](https://docs.docker.com/engine/swarm/secrets/) as the secrets by default gets mapped into `/run/secrets/<name of secret>` of the container.
|
||||
You can apply this technique to any configuration options in `conf/grafana.ini` by setting `GF_<SectionName>_<KeyName>__FILE` to the file path that contains the secret information. For more information about Docker secret command usage, refer to [docker secret](https://docs.docker.com/engine/reference/commandline/secret/).
|
||||
|
||||
You can do this with any of the configuration options in conf/grafana.ini by setting `GF_<SectionName>_<KeyName>__FILE` to the path of the file holding the secret.
|
||||
|
||||
For example, you could set the admin password this way:
|
||||
The following example demonstrates how to set the admin password:
|
||||
|
||||
- Admin password secret: `/run/secrets/admin_password`
|
||||
- Environment variable: `GF_SECURITY_ADMIN_PASSWORD__FILE=/run/secrets/admin_password`
|
||||
|
||||
## Configure AWS credentials for CloudWatch Support
|
||||
### Configure Docker secrets credentials for AWS CloudWatch
|
||||
|
||||
Grafana ships with built-in support for the [Amazon CloudWatch datasource]({{< relref "../datasources/aws-cloudwatch" >}}). To configure the data source, you must provide information such as the AWS ID-Key, secret access key, region, and so on. You can use Docker secrets as a way to provide this information.
|
||||
|
||||
Example:
|
||||
|
||||
The example below shows how to use Grafana environment variables via Docker Secrets for the AWS ID-Key, secret access key, region, and profile.
|
||||
|
||||
The example uses the following values for the AWS Cloudwatch data source:
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
-p 3000:3000 \
|
||||
--name=grafana \
|
||||
-e "GF_AWS_PROFILES=default" \
|
||||
-e "GF_AWS_default_ACCESS_KEY_ID=YOUR_ACCESS_KEY" \
|
||||
-e "GF_AWS_default_SECRET_ACCESS_KEY=YOUR_SECRET_KEY" \
|
||||
-e "GF_AWS_default_REGION=us-east-1" \
|
||||
grafana/grafana-enterprise
|
||||
AWS_default_ACCESS_KEY_ID=aws01us02
|
||||
AWS_default_SECRET_ACCESS_KEY=topsecret9b78c6
|
||||
AWS_default_REGION=us-east-1
|
||||
```
|
||||
|
||||
You may also specify multiple profiles to `GF_AWS_PROFILES` (e.g.
|
||||
`GF_AWS_PROFILES=default another`).
|
||||
1. Create a Docker secret for each of the values noted above.
|
||||
|
||||
Supported variables:
|
||||
```bash
|
||||
echo "aws01us02" | docker secret create aws_access_key_id -
|
||||
```
|
||||
|
||||
```bash
|
||||
echo "topsecret9b78c6" | docker secret create aws_secret_access_key -
|
||||
```
|
||||
|
||||
```bash
|
||||
echo "us-east-1" | docker secret create aws_region -
|
||||
```
|
||||
|
||||
1. Run the following command to determine that the secrets were created.
|
||||
|
||||
```bash
|
||||
$ docker secret ls
|
||||
```
|
||||
|
||||
The output from the command should look similar to the following:
|
||||
|
||||
```
|
||||
ID NAME DRIVER CREATED UPDATED
|
||||
i4g62kyuy80lnti5d05oqzgwh aws_access_key_id 5 minutes ago 5 minutes ago
|
||||
uegit5plcwodp57fxbqbnke7h aws_secret_access_key 3 minutes ago 3 minutes ago
|
||||
fxbqbnke7hplcwodp57fuegit aws_region About a minute ago About a minute ago
|
||||
```
|
||||
|
||||
Where:
|
||||
|
||||
ID = the secret unique ID that will be use in the docker run command
|
||||
|
||||
NAME = the logical name defined for each secret
|
||||
|
||||
1. Add the secrets to the command line when you run Docker.
|
||||
|
||||
```bash
|
||||
docker run -d -p 3000:3000 --name grafana \
|
||||
-e "GF_DEFAULT_INSTANCE_NAME=my-grafana" \
|
||||
-e "GF_AWS_PROFILES=default" \
|
||||
-e "GF_AWS_default_ACCESS_KEY_ID__FILE=/run/secrets/aws_access_key_id" \
|
||||
-e "GF_AWS_default_SECRET_ACCESS_KEY__FILE=/run/secrets/aws_secret_access_key" \
|
||||
-e "GF_AWS_default_REGION__FILE=/run/secrets/aws_region" \
|
||||
-v grafana-data:/var/lib/grafana \
|
||||
grafana/grafana-enterprise
|
||||
```
|
||||
|
||||
You can also specify multiple profiles to `GF_AWS_PROFILES` (for example, `GF_AWS_PROFILES=default another`).
|
||||
|
||||
The following list includes the supported environment variables:
|
||||
|
||||
- `GF_AWS_${profile}_ACCESS_KEY_ID`: AWS access key ID (required).
|
||||
- `GF_AWS_${profile}_SECRET_ACCESS_KEY`: AWS secret access key (required).
|
||||
- `GF_AWS_${profile}_REGION`: AWS region (optional).
|
||||
|
||||
## Troubleshoot a Docker deployment
|
||||
|
||||
By default, the Grafana log level is set to `INFO`, but you can increase the log level to `DEBUG` mode when you want to reproduce a problem.
|
||||
|
||||
For more information about logging, refer to [logs]({{< relref "./configure-grafana#log" >}}).
|
||||
|
||||
### Increase log level using the Docker run (CLI) command
|
||||
|
||||
To increase the log level to `DEBUG` mode, add the environment variable `GF_LOG_LEVEL` to the command line.
|
||||
|
||||
```bash
|
||||
docker run -d -p 3000:3000 --name=grafana \
|
||||
-e "GF_LOG_LEVEL=debug" \
|
||||
grafana/grafana-enterprise
|
||||
```
|
||||
|
||||
### Increase log level using the Docker Compose
|
||||
|
||||
To increase the log level to `DEBUG` mode, add the environment variable `GF_LOG_LEVEL` to the `docker-compose.yaml` file.
|
||||
|
||||
```yaml
|
||||
version: '3.8'
|
||||
services:
|
||||
grafana:
|
||||
image: grafana/grafana-enterprise
|
||||
container_name: grafana
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
# increases the log level from info to debug
|
||||
- GF_LOG_LEVEL=debug
|
||||
ports:
|
||||
- '3000:3000'
|
||||
volumes:
|
||||
- 'grafana_storage:/var/lib/grafana'
|
||||
volumes:
|
||||
grafana_storage: {}
|
||||
```
|
||||
|
||||
### Validate Docker Compose YAML file
|
||||
|
||||
The chance of syntax errors appearing in a YAML file increases as the file becomes more complex. You can use the following command to check for syntax errors.
|
||||
|
||||
```bash
|
||||
# go to your docker-compose.yaml directory
|
||||
cd /path-to/docker-compose/file
|
||||
|
||||
# run the validation command
|
||||
docker compose config
|
||||
```
|
||||
|
||||
If there are errors in the YAML file, the command output highlights the lines that contain errors. If there are no errors in the YAML file, the output includes the content of the `docker-compose.yaml` file in detailed YAML format.
|
||||
|
||||
@ -8,260 +8,364 @@ weight: 200
|
||||
|
||||
# Run Grafana Docker image
|
||||
|
||||
You can install and run Grafana using the official Docker images. Our docker images come in two editions:
|
||||
This topic guides you through installing Grafana via the official Docker images. Specifically, it covers running Grafana via the Docker command line interface (CLI) and docker-compose.
|
||||
|
||||
**Grafana Enterprise**: `grafana/grafana-enterprise`
|
||||
Grafana Docker images come in two editions:
|
||||
|
||||
**Grafana Open Source**: `grafana/grafana-oss`
|
||||
- **Grafana Enterprise**: `grafana/grafana-enterprise`
|
||||
- **Grafana Open Source**: `grafana/grafana-oss`
|
||||
|
||||
Each edition is available in two variants: Alpine and Ubuntu. See below.
|
||||
> **Note:** The recommended and default edition of Grafana is Grafana Enterprise. It is free and includes all the features of the OSS edition. Additionally, you have the option to upgrade to the [full Enterprise feature set](/products/enterprise/?utm_source=grafana-install-page), which includes support for [Enterprise plugins](/grafana/plugins/?enterprise=1&utcm_source=grafana-install-page).
|
||||
|
||||
For documentation regarding the configuration of a docker image, refer to [configure a Grafana Docker image](/docs/grafana/latest/administration/configure-docker/).
|
||||
The default images for Grafana are created using the Alpine Linux project and can be found in the Alpine official image. For instructions on configuring a Docker image for Grafana, refer to [Configure a Grafana Docker image]({{< relref "../../configure-docker" >}}).
|
||||
|
||||
This topic also contains important information about [migrating from earlier Docker image versions](#migrate-from-previous-docker-containers-versions).
|
||||
## Run Grafana via Docker CLI
|
||||
|
||||
## Alpine image (recommended)
|
||||
This section shows you how to run Grafana using the Docker CLI.
|
||||
|
||||
**Grafana Enterprise edition**: `grafana/grafana-enterprise:<version>`
|
||||
> **Note:** If you are on a Linux system (for example, Debian or Ubuntu), you might need to add `sudo` before the command or add your user to the `docker` group. For more information, refer to [Linux post-installation steps for Docker Engine](https://docs.docker.com/engine/install/linux-postinstall/).
|
||||
|
||||
**Grafana Open Source edition**: `grafana/grafana-oss:<version>`
|
||||
|
||||
The default images are based on the popular [Alpine Linux project](http://alpinelinux.org), available in [the Alpine official image](https://hub.docker.com/_/alpine). Alpine Linux is much smaller than most distribution base images, and thus leads to slimmer and more secure images.
|
||||
|
||||
The Alpine variant is highly recommended when security and final image size being as small as possible is desired. The main caveat to note is that it uses [musl libc](http://www.musl-libc.org) instead of [glibc and friends](http://www.etalabs.net/compare_libcs.html), so certain software might run into issues depending on the depth of their libc requirements. However, most software don't have an issue with this, so this variant is usually a very safe choice.
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
Grafana docker images were based on [Ubuntu](https://ubuntu.com/) prior to version 6.4.0.
|
||||
{{% /admonition %}}
|
||||
|
||||
## Ubuntu image
|
||||
|
||||
**Grafana Enterprise edition**: `grafana/grafana-enterprise:<version>-ubuntu`
|
||||
|
||||
**Grafana Open Source edition**: `grafana/grafana-oss:<version>-ubuntu`
|
||||
|
||||
These images are based on [Ubuntu](https://ubuntu.com/), available in [the Ubuntu official image](https://hub.docker.com/_/ubuntu). It is an alternative image for those who prefer an [Ubuntu](https://ubuntu.com/) based image and/or are dependent on certain tooling not available for Alpine.
|
||||
|
||||
## Run Grafana
|
||||
|
||||
You can run the latest Grafana version, run a specific version, or run an unstable version based on the main branch of the [grafana/grafana GitHub repository](https://github.com/grafana/grafana).
|
||||
|
||||
### Run the latest stable version of Grafana
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
If you are on a Linux system, you might need to add `sudo` before the command or add your user to the `docker` group.
|
||||
{{% /admonition %}}
|
||||
To run the latest stable version of Grafana, run the following command:
|
||||
|
||||
```bash
|
||||
docker run -d -p 3000:3000 grafana/grafana-enterprise
|
||||
docker run -d -p 3000:3000 --name=grafana grafana/grafana-enterprise
|
||||
```
|
||||
|
||||
### Run a specific version of Grafana
|
||||
Where:
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
If you are on a Linux system, you might need to add `sudo` before the command or add your user to the `docker` group.
|
||||
{{% /admonition %}}
|
||||
run = run directly from the command line
|
||||
|
||||
`d` = run in the background
|
||||
|
||||
`p` = assign the port number, which in this case is `3000`
|
||||
|
||||
`name` = assign a logical name to the container, for example, `grafana`
|
||||
|
||||
`grafana/grafana-enterprise` = the image to run in the container
|
||||
|
||||
### Stop the Grafana container
|
||||
|
||||
To stop the Grafana container, run the following command:
|
||||
|
||||
```bash
|
||||
docker run -d -p 3000:3000 --name grafana grafana/grafana-enterprise:<version number>
|
||||
# The `docker ps` command shows the processes running in Docker
|
||||
docker ps
|
||||
|
||||
# This will display a list of containers that looks like the following:
|
||||
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
|
||||
cd48d3994968 grafana/grafana-enterprise "/run.sh" 8 seconds ago Up 7 seconds 0.0.0.0:3000->3000/tcp grafana
|
||||
|
||||
# To stop the grafana container run the command
|
||||
# docker stop CONTAINER-ID or use
|
||||
# docker stop NAME, which is `grafana` as previously defined
|
||||
docker stop grafana
|
||||
```
|
||||
|
||||
**Example:**
|
||||
### Save your Grafana data
|
||||
|
||||
When you use Docker containers, their data is temporary by default. If you don't specify where to store the information, all the Grafana data will be lost when you stop the Docker container. To avoid losing your data, you can set up [persistent storage](https://docs.docker.com/storage/volumes/) or [bind mounts](https://docs.docker.com/storage/bind-mounts/) for your container.
|
||||
|
||||
> **Note:** Though both methods are similar, there is a slight difference. If you want your storage to be fully managed by Docker and accessed only through Docker containers and the Docker CLI, you should choose to use persistent storage. However, if you need full control of the storage and want to allow other processes besides Docker to access or modify the storage layer, then bind mounts is the right choice for your environment.
|
||||
|
||||
#### Use persistent storage (recommended)
|
||||
|
||||
It is recommended to have persistent storage because, without it, all data will be lost once the container is shut down. Use this method when you want the Docker service to manage the storage volume fully.
|
||||
|
||||
To use persistent storage, complete the following steps:
|
||||
|
||||
1. Create a Grafana Docker volume `grafana-storage` by running the following commands:
|
||||
|
||||
```bash
|
||||
# create a persistent volume for your data
|
||||
docker volume create grafana-storage
|
||||
|
||||
# verify that the volume was created correctly
|
||||
# you should see a json output
|
||||
docker volume inspect grafana-storage
|
||||
```
|
||||
|
||||
1. Start the Grafana container by running the following command:
|
||||
```bash
|
||||
# start grafana
|
||||
docker run -d -p 3000:3000 --name=grafana \
|
||||
--volume grafana-storage:/var/lib/grafana \
|
||||
grafana/grafana-enterprise
|
||||
```
|
||||
|
||||
#### Use bind mounts
|
||||
|
||||
If you plan to use folders on your host for the database or configuration when running Grafana in Docker, you must start the container with a user with permission to access and write to the folder you map.
|
||||
|
||||
To use bind mounts, run the following command:
|
||||
|
||||
```bash
|
||||
docker run -d -p 3000:3000 --name grafana grafana/grafana-enterprise:8.2.0
|
||||
# create a folder for your data
|
||||
mkdir data
|
||||
|
||||
# start grafana with your user id and using the data folder
|
||||
docker run -d -p 3000:3000 --name=grafana \
|
||||
--user "$(id -u)" \
|
||||
--volume "$PWD/data:/var/lib/grafana" \
|
||||
grafana/grafana-enterprise
|
||||
```
|
||||
|
||||
### Run the Grafana main branch
|
||||
### Use environment variables to configure Grafana
|
||||
|
||||
For every successful build of the main branch, we update the `grafana/grafana-oss:main` and `grafana/grafana-oss:main-ubuntu` tags. Additionally, two new tags are created, `grafana/grafana-oss-dev:<version>-<build ID>pre` and `grafana/grafana-oss-dev:<version>-<build ID>pre-ubuntu`, where _version_ is the next version of Grafana and _build ID_ is the ID of the corresponding CI build. Use these to get access to the latest main builds of Grafana.
|
||||
Grafana supports specifying custom configuration settings using [environment variables]({{< relref "../../../setup-grafana/configure-grafana#override-configuration-with-environment-variables" >}}).
|
||||
|
||||
When running Grafana main in production, we _strongly_ recommend that you use the `grafana/grafana-oss-dev:<version>-<build ID>pre` tag. This tag guarantees that you use a specific version of Grafana instead of whatever was the most recent commit at the time.
|
||||
```bash
|
||||
# enabling public dashboard feature
|
||||
|
||||
For a list of available tags, check out [grafana/grafana-oss](https://hub.docker.com/r/grafana/grafana-oss/tags/) and [grafana/grafana-oss-dev](https://hub.docker.com/r/grafana/grafana-oss-dev/tags/).
|
||||
docker run -d -p 3000:3000 --name=grafana \
|
||||
-e "GF_FEATURE_TOGGLES_ENABLE=publicDashboards" \
|
||||
grafana/grafana-enterprise
|
||||
```
|
||||
|
||||
## Install plugins in the Docker container
|
||||
|
||||
You can install official and community plugins listed on the Grafana [plugins page](/grafana/plugins) or from a custom URL.
|
||||
You can install plugins in Grafana from the official and community [plugins page](/grafana/plugins) or by using a custom URL to install a private plugin. These plugins allow you to add new visualization types, data sources, and applications to help you better visualize your data.
|
||||
|
||||
### Install official and community Grafana plugins
|
||||
Grafana currently supports three types of plugins: panel, data source, and app. For more information on managing plugins, refer to [Plugin Management]({{< relref "../../../administration/plugin-management" >}}).
|
||||
|
||||
Pass the plugins you want installed to Docker with the `GF_INSTALL_PLUGINS` environment variable as a comma-separated list. This sends each plugin name to `grafana cli plugins install ${plugin}` and installs them when Grafana starts.
|
||||
To install plugins in the Docker container, complete the following steps:
|
||||
|
||||
1. Pass the plugins you want to be installed to Docker with the `GF_INSTALL_PLUGINS` environment variable as a comma-separated list.
|
||||
|
||||
This sends each plugin name to `grafana-cli plugins install ${plugin}` and installs them when Grafana starts.
|
||||
|
||||
For example:
|
||||
|
||||
```bash
|
||||
docker run -d -p 3000:3000 --name=grafana \
|
||||
-e "GF_INSTALL_PLUGINS=grafana-clock-panel, grafana-simple-json-datasource" \
|
||||
grafana/grafana-enterprise
|
||||
```
|
||||
|
||||
1. To specify the version of a plugin, add the version number to the `GF_INSTALL_PLUGINS` environment variable.
|
||||
|
||||
For example:
|
||||
|
||||
```bash
|
||||
docker run -d -p 3000:3000 --name=grafana \
|
||||
-e "GF_INSTALL_PLUGINS=grafana-clock-panel 1.0.1" \
|
||||
grafana/grafana-enterprise
|
||||
```
|
||||
|
||||
> **Note:** If you do not specify a version number, the latest version is used.
|
||||
|
||||
1. To install a plugin from a custom URL, use the following convention to specify the URL: `<url to plugin zip>;<plugin install folder name>`.
|
||||
|
||||
For example:
|
||||
|
||||
```bash
|
||||
docker run -d -p 3000:3000 --name=grafana \
|
||||
-e "GF_INSTALL_PLUGINS=https://github.com/VolkovLabs/custom-plugin.zip;custom-plugin" \
|
||||
grafana/grafana-enterprise
|
||||
```
|
||||
|
||||
## Example
|
||||
|
||||
The following example runs the latest stable version of Grafana, listening on port 3000, with the container named `grafana`, persistent storage in the grafana-storage docker volume, the server root URL set, and the official [clock panel](/grafana/plugins/grafana-clock-panel) plugin installed.
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
-p 3000:3000 \
|
||||
--name=grafana \
|
||||
-e "GF_INSTALL_PLUGINS=grafana-clock-panel,grafana-simple-json-datasource" \
|
||||
# create a persistent volume for your data
|
||||
docker volume create grafana-storage
|
||||
|
||||
# start grafana by using the above persistent storage
|
||||
# and defining environment variables
|
||||
|
||||
docker run -d -p 3000:3000 --name=grafana \
|
||||
--volume grafana-storage:/var/lib/grafana \
|
||||
-e "GF_SERVER_ROOT_URL=http://my.grafana.server/" \
|
||||
-e "GF_INSTALL_PLUGINS=grafana-clock-panel" \
|
||||
grafana/grafana-enterprise
|
||||
```
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
If you need to specify the version of a plugin, then you can add it to the `GF_INSTALL_PLUGINS` environment variable. Otherwise, the latest is used. For example: `-e "GF_INSTALL_PLUGINS=grafana-clock-panel 1.0.1,grafana-simple-json-datasource 1.3.5"`.
|
||||
{{% /admonition %}}
|
||||
## Run Grafana via Docker Compose
|
||||
|
||||
### Install plugins from other sources
|
||||
Docker Compose is a software tool that makes it easy to define and share applications that consist of multiple containers. It works by using a YAML file, usually called `docker-compose.yaml`, which lists all the services that make up the application. You can start the containers in the correct order with a single command, and with another command, you can shut them down. For more information about the benefits of using Docker Compose and how to use it refer to [Use Docker Compose](https://docs.docker.com/get-started/08_using_compose/).
|
||||
|
||||
> Only available in Grafana v5.3.1 and later.
|
||||
### Before you begin
|
||||
|
||||
You can install a plugin from a custom URL by specifying the URL like this: `GF_INSTALL_PLUGINS=<url to plugin zip>;<plugin install folder name>`.
|
||||
To run Grafana via Docker Compose, install the compose tool on your machine. To determine if the compose tool is available, run the following command:
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
-p 3000:3000 \
|
||||
--name=grafana \
|
||||
-e "GF_INSTALL_PLUGINS=http://plugin-domain.com/my-custom-plugin.zip;custom-plugin,grafana-clock-panel" \
|
||||
grafana/grafana-enterprise
|
||||
docker compose version
|
||||
```
|
||||
|
||||
## Build and run a Docker image with pre-installed plugins
|
||||
If the compose tool is unavailable, refer to [Install Docker Compose](https://docs.docker.com/compose/install/).
|
||||
|
||||
You can build your own customized image that includes plugins. This saves time if you are creating multiple images and you want them all to have the same plugins installed on build.
|
||||
### Run the latest stable version of Grafana
|
||||
|
||||
In the [Grafana GitHub repository](https://github.com/grafana/grafana) there is a folder called `packaging/docker/custom/`, which includes a Dockerfile that can be used to build a custom Grafana image. It accepts `GRAFANA_VERSION`, `GF_INSTALL_PLUGINS`, and `GF_INSTALL_IMAGE_RENDERER_PLUGIN` as build arguments.
|
||||
This section shows you how to run Grafana using Docker Compose. The examples in this section use Compose version 3. For more information about compatibility, refer to [Compose and Docker compatibility matrix](https://docs.docker.com/compose/compose-file/compose-file-v3/).
|
||||
|
||||
The `GRAFANA_VERSION` build argument must be a valid `grafana/grafana` docker image tag. By default, this builds an Alpine-based image. To build an Ubuntu-based image, append `-ubuntu` to the `GRAFANA_VERSION` build argument (available in Grafana v6.5 and later).
|
||||
> **Note:** If you are on a Linux system (for example, Debian or Ubuntu), you might need to add `sudo` before the command or add your user to the `docker` group. For more information, refer to [Linux post-installation steps for Docker Engine](https://docs.docker.com/engine/install/linux-postinstall/).
|
||||
|
||||
The following example shows you how to build and run a custom Grafana Docker image based on the latest official Ubuntu-based Grafana Docker image:
|
||||
To run the latest stable version of Grafana using Docker Compose, complete the following steps:
|
||||
|
||||
1. Create a `docker-compose.yaml` file.
|
||||
|
||||
```bash
|
||||
# first go into the directory where you have created this docker-compose.yaml file
|
||||
cd /path/to/docker-compose-folder
|
||||
|
||||
# now create the docker-compose.yaml file
|
||||
touch docker-compose.yaml
|
||||
```
|
||||
|
||||
1. Now, add the following code into the `docker-compose.yaml` file.
|
||||
|
||||
For example:
|
||||
|
||||
```bash
|
||||
version: "3.8"
|
||||
services:
|
||||
grafana:
|
||||
image: grafana/grafana-enterprise
|
||||
container_name: grafana
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- '3000:3000'
|
||||
```
|
||||
|
||||
1. To run `docker-compose.yaml`, run the following command:
|
||||
|
||||
```bash
|
||||
# start the grafana container
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
Where:
|
||||
|
||||
d = detached mode
|
||||
|
||||
up = to bring the container up and running
|
||||
|
||||
To determine that Grafana is running, open a browser window and type `IP_ADDRESS:3000`. The sign in screen should appear.
|
||||
|
||||
### Stop the Grafana container
|
||||
|
||||
To stop the Grafana container, run the following command:
|
||||
|
||||
```bash
|
||||
cd packaging/docker/custom
|
||||
docker build \
|
||||
--build-arg "GRAFANA_VERSION=latest-ubuntu" \
|
||||
-t grafana-custom .
|
||||
|
||||
docker run -d -p 3000:3000 --name=grafana grafana-custom
|
||||
docker compose down
|
||||
```
|
||||
|
||||
### Build with pre-installed plugins
|
||||
> **Note:** For more information about using Docker Compose commands, refer to [docker compose](https://docs.docker.com/engine/reference/commandline/compose/).
|
||||
|
||||
> If you need to specify the version of a plugin, you can add it to the `GF_INSTALL_PLUGINS` build argument. Otherwise, the latest will be assumed. For example: `--build-arg "GF_INSTALL_PLUGINS=grafana-clock-panel 1.0.1,grafana-simple-json-datasource 1.3.5"`
|
||||
### Save your Grafana data
|
||||
|
||||
Example of how to build and run:
|
||||
When you use Docker containers, their data is temporary by default. If you don't specify where to store the information, all the Grafana data will be lost when you stop the Docker container. To avoid losing your data, you can set up [persistent storage](https://docs.docker.com/storage/volumes/) or [bind mounts](https://docs.docker.com/storage/bind-mounts/) for your container.
|
||||
|
||||
#### Use persistent storage (recommended)
|
||||
|
||||
It is recommended to have persistent storage because without it, all data will be lost once the container is shut down. Use this method when you want the Docker service to fully manage the storage volume.
|
||||
|
||||
Complete the following steps to use persistent storage.
|
||||
|
||||
1. Create a `docker-compose.yaml` file
|
||||
|
||||
```bash
|
||||
# first go into the directory where you have created this docker-compose.yaml file
|
||||
cd /path/to/docker-compose-folder
|
||||
|
||||
# now create the docker-compose.yaml file
|
||||
touch docker-compose.yaml
|
||||
```
|
||||
|
||||
1. Add the following code into the `docker-compose.yaml` file.
|
||||
|
||||
```yaml
|
||||
version: '3.8'
|
||||
services:
|
||||
grafana:
|
||||
image: grafana/grafana-enterprise
|
||||
container_name: grafana
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- '3000:3000'
|
||||
volumes:
|
||||
- grafana_data:/var/lib/grafana
|
||||
volumes:
|
||||
grafana_data: {}
|
||||
```
|
||||
|
||||
1. Save the file and run the following command:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
#### Use bind mounts
|
||||
|
||||
If you plan to use folders on your host for the database or configuration when running Grafana in Docker, you must start the container with a user that has the permission to access and write to the folder you map.
|
||||
|
||||
To use bind mounts, complete the following steps:
|
||||
|
||||
1. Create a `docker-compose.yaml` file
|
||||
|
||||
```bash
|
||||
# first go into the directory where you have created this docker-compose.yaml file
|
||||
cd /path/to/docker-compose-folder
|
||||
|
||||
# now create the docker-compose.yaml file
|
||||
touch docker-compose.yaml
|
||||
```
|
||||
|
||||
1. Create the folder where you will be mounting your data, in this case is `/data` e.g. in your current working directory:
|
||||
|
||||
```bash
|
||||
mkdir $PWD/data
|
||||
```
|
||||
|
||||
1. Now, add the following code into the `docker-compose.yaml` file.
|
||||
|
||||
```yaml
|
||||
version: '3.8'
|
||||
services:
|
||||
grafana:
|
||||
image: grafana/grafana-enterprise
|
||||
container_name: grafana
|
||||
restart: unless-stopped
|
||||
# if you are running as root then set it to 0
|
||||
# else find the right id with the id -u command
|
||||
user: '0'
|
||||
ports:
|
||||
- '3000:3000'
|
||||
# adding the mount volume point which we create earlier
|
||||
volumes:
|
||||
- '$PWD/data:/var/lib/grafana'
|
||||
```
|
||||
|
||||
1. Save the file and run the following command:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
The following example runs the latest stable version of Grafana, listening on port 3000, with the container named `grafana`, persistent storage in the grafana-storage docker volume, the server root URL set, and the official [clock panel](/grafana/plugins/grafana-clock-panel) plugin installed.
|
||||
|
||||
```bash
|
||||
cd packaging/docker/custom
|
||||
docker build \
|
||||
--build-arg "GRAFANA_VERSION=latest" \
|
||||
--build-arg "GF_INSTALL_PLUGINS=grafana-clock-panel,grafana-simple-json-datasource" \
|
||||
-t grafana-custom .
|
||||
|
||||
docker run -d -p 3000:3000 --name=grafana grafana-custom
|
||||
```
|
||||
|
||||
### Build with pre-installed plugins from other sources
|
||||
|
||||
You can build a Docker image with plugins from other sources by specifying the URL like this: `GF_INSTALL_PLUGINS=<url to plugin zip>;<plugin install folder name>`.
|
||||
|
||||
```bash
|
||||
cd packaging/docker/custom
|
||||
docker build \
|
||||
--build-arg "GRAFANA_VERSION=latest" \
|
||||
--build-arg "GF_INSTALL_PLUGINS=http://plugin-domain.com/my-custom-plugin.zip;custom-plugin,grafana-clock-panel" \
|
||||
-t grafana-custom .
|
||||
|
||||
docker run -d -p 3000:3000 --name=grafana grafana-custom
|
||||
```
|
||||
|
||||
### Build with Grafana Image Renderer plugin pre-installed
|
||||
|
||||
> Only available in Grafana v6.5 and later. This is experimental.
|
||||
|
||||
The [Grafana Image Renderer plugin]({{< relref "../../image-rendering" >}}) does not currently work if it is installed in a Grafana Docker image. You can build a custom Docker image by using the `GF_INSTALL_IMAGE_RENDERER_PLUGIN` build argument. This installs additional dependencies needed for the Grafana Image Renderer plugin to run.
|
||||
|
||||
Example of how to build and run:
|
||||
|
||||
```bash
|
||||
cd packaging/docker/custom
|
||||
docker build \
|
||||
--build-arg "GRAFANA_VERSION=latest" \
|
||||
--build-arg "GF_INSTALL_IMAGE_RENDERER_PLUGIN=true" \
|
||||
-t grafana-custom .
|
||||
|
||||
docker run -d -p 3000:3000 --name=grafana grafana-custom
|
||||
```
|
||||
|
||||
## Migrate from previous Docker containers versions
|
||||
|
||||
This section contains important information if you want to migrate from previous Grafana container versions to a more current one.
|
||||
|
||||
### Migrate to v7.3 or later
|
||||
|
||||
The Grafana Docker image runs with the `root` group (id 0) instead of the `grafana` group (id 472), for better compatibility with OpenShift. If you extend the official Docker image you may need to change your scripts to use the `root` group instead of `grafana`.
|
||||
|
||||
### Migrate to v6.5 or later
|
||||
|
||||
Grafana Docker image now comes in two variants, one [Alpine](http://alpinelinux.org) based and one [Ubuntu](https://ubuntu.com/) based.
|
||||
|
||||
### Migrate to v6.4 or later
|
||||
|
||||
Grafana Docker image was changed to be based on [Alpine](http://alpinelinux.org) instead of [Ubuntu](https://ubuntu.com/).
|
||||
|
||||
### Migrate to v5.1 or later
|
||||
|
||||
The Docker container for Grafana has seen a major rewrite for 5.1.
|
||||
|
||||
**Important changes**
|
||||
|
||||
- File ownership is no longer modified during startup with `chown`.
|
||||
- Default user ID is now `472` instead of `104`.
|
||||
- Removed the following implicit volumes:
|
||||
- `/var/lib/grafana`
|
||||
- `/etc/grafana`
|
||||
- `/var/log/grafana`
|
||||
|
||||
#### Removal of implicit volumes
|
||||
|
||||
Previously `/var/lib/grafana`, `/etc/grafana` and `/var/log/grafana` were defined as volumes in the `Dockerfile`. This led to the creation of three volumes each time a new instance of the Grafana container started, whether you wanted it or not.
|
||||
|
||||
You should always be careful to define your own named volume for storage, but if you depended on these volumes, then you should be aware that an upgraded container will no longer have them.
|
||||
|
||||
**Warning**: When migrating from an earlier version to 5.1 or later using Docker compose and implicit volumes, you need to use `docker inspect` to find out which volumes your container is mapped to so that you can map them to the upgraded container as well. You will also have to change file ownership (or user) as documented below.
|
||||
|
||||
#### User ID changes
|
||||
|
||||
In Grafana v5.1, we changed the ID and group of the Grafana user and in v7.3 we changed the group. Unfortunately this means that files created prior to v5.1 won't have the correct permissions for later versions. We made this change so that it would be more likely that the Grafana users ID would be unique to Grafana. For example, on Ubuntu 16.04 `104` is already in use by the syslog user.
|
||||
|
||||
| Version | User | User ID | Group | Group ID |
|
||||
| ------- | ------- | ------- | ------- | -------- |
|
||||
| < 5.1 | grafana | 104 | grafana | 107 |
|
||||
| \>= 5.1 | grafana | 472 | grafana | 472 |
|
||||
| \>= 7.3 | grafana | 472 | root | 0 |
|
||||
|
||||
There are two possible solutions to this problem. Either you start the new container as the root user and change ownership from `104` to `472`, or you start the upgraded container as user `104`.
|
||||
|
||||
##### Run Docker as a different user
|
||||
|
||||
```bash
|
||||
docker run --user 104 --volume "<your volume mapping here>" grafana/grafana-enterprise:8.2.0
|
||||
```
|
||||
|
||||
##### Specify a user in docker-compose.yml
|
||||
|
||||
```yaml
|
||||
version: '2'
|
||||
|
||||
version: "3.8"
|
||||
services:
|
||||
grafana:
|
||||
image: grafana/grafana-enterprise:8.2.0
|
||||
image: grafana/grafana-enterprise
|
||||
container_name: grafana
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
- GF_SERVER_ROOT_URL=http://my.grafana.server/
|
||||
- GF_INSTALL_PLUGINS=grafana-clock-panel
|
||||
ports:
|
||||
- 3000:3000
|
||||
user: '104'
|
||||
- '3000:3000'
|
||||
volumes:
|
||||
- 'grafana_storage:/var/lib/grafana'
|
||||
volumes:
|
||||
grafana_storage: {}
|
||||
```
|
||||
|
||||
#### Modify permissions
|
||||
|
||||
The commands below run bash inside the Grafana container with your volume mapped in. This makes it possible to modify the file ownership to match the new container. Always be careful when modifying permissions.
|
||||
|
||||
```bash
|
||||
$ docker run -ti --user root --volume "<your volume mapping here>" --entrypoint bash grafana/grafana-enterprise:8.2.0
|
||||
|
||||
# in the container you just started:
|
||||
chown -R root:root /etc/grafana && \
|
||||
chmod -R a+r /etc/grafana && \
|
||||
chown -R grafana:grafana /var/lib/grafana && \
|
||||
chown -R grafana:grafana /usr/share/grafana
|
||||
```
|
||||
> **Note:** If you want to specify the version of a plugin, add the version number to the `GF_INSTALL_PLUGINS` environment variable. For example: `-e "GF_INSTALL_PLUGINS=grafana-clock-panel 1.0.1,grafana-simple-json-datasource 1.3.5"`. If you do not specify a version number, the latest version is used.
|
||||
|
||||
## Next steps
|
||||
|
||||
|
||||
Reference in New Issue
Block a user