Deployment & Docker
Relevant source files
The following files were used as context for generating this wiki page:
Grafana utilizes Docker and containerization as central pillars for both production deployment and local development. The project provides standardized Dockerfiles, build scripts, and Docker Compose configurations to ensure consistency across different environments, from a developer's local machine to large-scale production clusters.
The deployment ecosystem is divided into production-grade artifacts (fully static binaries in containers) and development environments (devenv) that utilize Docker to orchestrate backing services like databases and observability tools.
Docker Build Process
The project maintains a rigorous process for building Docker images. In production, Grafana is built with CGO_ENABLED=0 to produce fully static, pure Go binaries, ensuring compatibility across different container runtimes and base images such as Alpine or scratch.
Build Workflow
The following diagram illustrates the high-level flow from source code to a tagged Docker image:
Citations: contribute/developer-guide.md:126-134, contribute/developer-guide.md:237-240, AGENTS.md:31-34
Docker Dependencies
Building and maintaining the Docker image requires specific versioned dependencies which are tracked across multiple configuration files:
- Go and Node.js: Versions are synced in the
Dockerfile, Drone CI configurations, and Appveyor scripts. - Build Container: A custom
grafana/build-containerimage is used to provide pre-baked dependencies likefpm, cross-compilers, and specific versions of Node.js/Go.
Sources: contribute/UPGRADING_DEPENDENCIES.md:5-20, contribute/UPGRADING_DEPENDENCIES.md:46-55
Development Environment (devenv)
The devenv system uses Docker Compose to provide developers with a ready-to-use ecosystem of databases and proxies. This allows for testing Grafana against various data sources without manual local installation of those services.
Core Components
| Component | Description | Source File |
|---|---|---|
| Blocks | Modular Docker Compose definitions located in devenv/docker/blocks/. | devenv/README.md:30-32 |
| setup.sh | Script to provision data sources and dashboards in the local Grafana instance. | devenv/README.md:14-16 |
| make devenv | Command to generate a dynamic Docker Compose file based on requested sources. | devenv/README.md:30-34 |
Backing Service Orchestration
Developers can start specific clusters of services using the sources parameter. For example, make devenv sources=postgres,auth/openldap,grafana will orchestrate a PostgreSQL database and an OpenLDAP server alongside Grafana.
Configuration and Deployment Tuning
Grafana's behavior within Docker is heavily influenced by environment variables and configuration files (defaults.ini and custom.ini).
Key Configuration files
- defaults.ini: Located in the
confdirectory, containing default settings for the application. - custom.ini: Used to override defaults; for example, setting
app_mode = development. - .air.toml: Used for live-reloading the backend during development within the containerized environment.
Sources: contribute/developer-guide.md:204-210, AGENTS.md:104-106
Resource Constraints
When running Grafana in Docker for macOS, it is recommended to set the memory limit higher than 2 GiB to prevent build failures (specifically grunt build or complex frontend asset generation). Additionally, system limits for file watchers (fs.inotify.max_user_watches) may need to be increased on the host to support the volume of files watched during development.
Sources: contribute/developer-guide.md:242-246, contribute/developer-guide.md:275-285
Summary
The deployment and Docker strategy in Grafana provides a seamless transition from development to production. By using static Go builds (CGO_ENABLED=0) for production images and a flexible, block-based Docker Compose system (devenv) for development, the project maintains high reliability and developer velocity. Production images are typically tagged as grafana/grafana:dev during local builds, while the devenv setup automates the provisioning of complex data source landscapes.