Project: Grafana (Observability and Analysis / Observability)
File: configure-docker.md

aliases: ../administration/configure-docker/ ../installation/configure-docker/ description: Guide for configuring the Grafana Docker image keywords: grafana configuration documentation docker docker compose labels: products: enterprise oss menuTitle: Configure a Docker image title: Configure a Grafana Docker image weight: 1800 This topic explains how to run Grafana on Docker in complex environments that require you to: Use different images Change logging levels Define secrets on the Cloud Configure plugins 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`. 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. 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 base image, which can be found in the . 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 instead of . 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. The Ubuntu-based Grafana Enterprise and OSS images are built using the base image, which can be found in the . 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` You can also run a specific version of Grafana or a beta version based on the main branch of the . 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 . To run a specific version of Grafana, add it in the command <version number> section: ```bash docker run -d -p 3000:3000 --name grafana grafana/grafana-enterprise:<version number> ``` Example: 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 docker run -d -p 3000:3000 --name grafana grafana/grafana-enterprise:9.4.7 ``` After every successful build of the main branch, two tags, `grafana/grafana-oss:main` and `grafana/grafana-oss:main-ubuntu`, are

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 . 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 and . 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 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 . | Setting | Default value | | | - | | GFPATHSCONFIG | /etc/grafana/grafana.ini | | GFPATHSDATA | /var/lib/grafana | | GFPATHSHOME | /usr/share/grafana | | GFPATHSLOGS | /var/log/grafana | | GFPATHSPLUGINS | /var/lib/grafana/plugins | | GFPATHSPROVISIONING | /etc/grafana/provisioning | You can install publicly available plugins and plugins that are private or used internally in an organization. For plugin installation instructions, refer to . To install plugins from other sources, you must define the custom URL and specify it immediately before the plugin name in the `GFINSTALLPLUGINS` environment variable: `GFINSTALLPLUGINS=<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 `GFINSTALLPLUGINS` environment variable. ```bash docker run -d -p 3000:3000 --name=grafana \ -e "GFINSTALLPLUGINS=http://plugin-domain.com/my-custom-plugin.zip;custom-plugin,grafana-clock-panel" \ grafana/grafana-enterprise ``` 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 `GRAFANAVERSION`, `GFINSTALLPLUGINS`, and `GFINSTALLIMAGERENDERER_PLUGIN` as build arguments. The `GRAFANAVERSION` 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 `GRAFANAVERSION` 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 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 ``` Note: This feature is experimental. Currently, the Grafana Image Renderer plugin requires dependencies that are not available in the Grafana Docker image (see for more details). However, you can create a customized Docker image using the `GFINSTALLIMAGERENDERERPLUGIN` build argument as a

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 cd packaging/docker/custom docker build \ --build-arg "GRAFANA_VERSION=latest" \ --build-arg "GFINSTALLIMAGERENDERERPLUGIN=true" \ -t grafana-custom . docker run -d -p 3000:3000 --name=grafana grafana-custom ``` 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 . 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 `GFINSTALLPLUGINS` 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 "GFINSTALLPLUGINS=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 cd packaging/docker/custom docker build \ --build-arg "GRAFANA_VERSION=latest" \ --build-arg "GFINSTALLPLUGINS=grafana-clock-panel,grafana-simple-json-datasource" \ -t grafana-custom . docker run -d -p 3000:3000 --name=grafana grafana-custom ``` 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 `GFINSTALLPLUGINS` build argument to specify the plugin's URL and installation folder name, such as `GFINSTALLPLUGINS=<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 cd packaging/docker/custom docker build \ --build-arg "GRAFANA_VERSION=latest" \ --build-arg "GFINSTALLPLUGINS=http://plugin-domain.com/my-custom-plugin.zip;my-custom-plugin,grafana-clock-panel,grafana-simple-json-datasource" \ -t grafana-custom . docker run -d -p 3000:3000 --name=grafana grafana-custom ``` By default, Docker container logs are directed to `STDOUT`, a common practice in the Docker community. You can change this by setting a different 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 `GFLOGMODE` environment variable. ```bash docker run -p 3000:3000 -e "GFLOGMODE=console file" grafana/grafana-enterprise ``` You can input confidential data like login credentials and secrets into Grafana using configuration files. This method works well with , as the secrets are automatically mapped to the `/run/secrets/` location within 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

The following example demonstrates how to set the admin password: Admin password secret: `/run/secrets/admin_password` Environment variable: `GFSECURITYADMINPASSWORDFILE=/run/secrets/adminpassword` Grafana ships with built-in support for the . 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 AWSdefaultACCESSKEYID=aws01us02 AWSdefaultSECRETACCESSKEY=topsecret9b78c6 AWSdefaultREGION=us-east-1 ``` Create a Docker secret for each of the values noted above. ```bash echo "aws01us02" | docker secret create awsaccesskey_id - ``` ```bash echo "topsecret9b78c6" | docker secret create awssecretaccess_key - ``` ```bash echo "us-east-1" | docker secret create aws_region - ``` 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 awsaccesskey_id 5 minutes ago 5 minutes ago uegit5plcwodp57fxbqbnke7h awssecretaccess_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 Add the secrets to the command line when you run Docker. ```bash docker run -d -p 3000:3000 --name grafana \ -e "GFDEFAULTINSTANCE_NAME=my-grafana" \ -e "GFAWSPROFILES=default" \ -e "GFAWSdefaultACCESSKEYIDFILE=/run/secrets/awsaccesskeyid" \ -e "GFAWSdefaultSECRETACCESSKEYFILE=/run/secrets/awssecretaccesskey" \ -e "GFAWSdefaultREGIONFILE=/run/secrets/awsregion" \ -v grafana-data:/var/lib/grafana \ grafana/grafana-enterprise ``` You can also specify multiple profiles to `GFAWSPROFILES` (for example, `GFAWSPROFILES=default another`). The following list includes the supported environment variables: `GFAWS${profile}ACCESSKEY_ID`: AWS access key ID (required). `GFAWS${profile}SECRETACCESS_KEY`: AWS secret access key (required). `GFAWS${profile}_REGION`: AWS region (optional). 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 . To increase the log level to `DEBUG` mode, add the environment variable `GFLOGLEVEL` to the command line. ```bash docker run -d -p 3000:3000 --name=grafana \ -e "GFLOGLEVEL=debug" \ grafana/grafana-enterprise ``` To increase the log level to `DEBUG` mode, add the environment variable `GFLOGLEVEL` to the `docker-compose.yaml` file. ```yaml version: '3.8' services: grafana: image: grafana/grafana-enterprise container_name: grafana restart: unless-stopped environment: GFLOGLEVEL=debug ports: '3000:3000' volumes: 'grafana_storage:/var/lib/grafana' volumes: grafana_storage: {} ``` 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 cd /path-to/docker-compose/file 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.