IntenseWebs/grafana
3
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2025-02-25 18:55:37 -06:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Update docker image run and configuration instructions (#21705)

Browse Source 
* Update docker.md

* Update configuration.md

* Update configuration.md

* Update configuration, docker, and add configure-docker

* Moe Docker updates

* Update docker.md

* deleted build custom docker image file and moved content

* Update docker.md

* Minor updates

Mostly grammar fixes

* Update docs/sources/installation/docker.md

Co-Authored-By: Marcus Efraimsson <marcus.efraimsson@gmail.com>

* Updated config-docker and configuration

Moved environment variables information back to configuration.md

* Update docs/sources/installation/configuration.md

Co-Authored-By: Leonard Gram <leo@xlson.com>

* Update docs/sources/installation/configure-docker.md

Co-Authored-By: Marcus Efraimsson <marcus.efraimsson@gmail.com>

* Update docs/sources/installation/docker.md

Co-Authored-By: Leonard Gram <leo@xlson.com>

* Update docs/sources/installation/docker.md

Co-Authored-By: Leonard Gram <leo@xlson.com>

* Update docs/sources/installation/docker.md

Co-Authored-By: Leonard Gram <leo@xlson.com>

* Applied edits

* Update _index.md

Co-authored-by: Marcus Efraimsson <marcus.efraimsson@gmail.com>
Co-authored-by: Leonard Gram <leo@xlson.com>
This commit is contained in:
Diana Payton 2020-01-29 09:23:28 -08:00 committed by GitHub
parent c15ddc295c
commit c344a3a66e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 230 additions and 215 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
docs/sources/installation/_index.md
View File

@ -1,6 +1,6 @@
+++
title = "Installation"
description = "Install guide for Grafana"
description = "Installation guide for Grafana"
keywords = ["grafana", "installation", "documentation"]
type = "docs"
aliases = ["/docs/grafana/latest/installation/installation/", "/docs/grafana/v2.1/installation/install/", "/docs/grafana/latest/install"]
@ -10,15 +10,12 @@ identifier = "installation"
weight = 1
+++
## Installing Grafana
## Install Grafana
- [Requirements]({{< relref "requirements" >}})
- [Installing on Debian / Ubuntu]({{< relref "debian" >}})
- [Installing on RPM-based Linux (CentOS, Fedora, OpenSuse, RedHat)]({{< relref "rpm" >}})
- [Installing on macOS]({{< relref "mac" >}})
- [Installing on Windows]({{< relref "windows" >}})
- [Installing on Docker]({{< relref "docker" >}})
- [Installing using Provisioning (Chef, Puppet, Salt, Ansible, etc)]({{< relref "../administration/provisioning" >}})
- [Install on Debian or Ubuntu]({{< relref "debian" >}})
- [Install on RPM-based Linux (CentOS, Fedora, OpenSuse, RedHat)]({{< relref "rpm" >}})
- [Install on macOS]({{< relref "mac" >}})
- [Install on Windows]({{< relref "windows" >}})
- [Run Docker image]({{< relref "docker" >}})
- [Nightly Builds](https://grafana.com/grafana/download)

39
docs/sources/installation/configuration.md
View File

@ -1,6 +1,6 @@
+++
title = "Configuration"
description = "Configuration Docs"
description = "Configuration documentation"
keywords = ["grafana", "configuration", "documentation"]
type = "docs"
[menu.docs]
@ -18,22 +18,22 @@ Grafana has a number of configuration options that you can specify in a `.ini` c
## Config file locations
Do not change `defaults.ini`! Grafana defaults are stored in this file. Depending on your OS, make all configuration changes in either `custom.ini` or `grafana.ini`.
*Do not* change `defaults.ini`! Grafana defaults are stored in this file. Depending on your OS, make all configuration changes in either `custom.ini` or `grafana.ini`.
- Default configuration from `$WORKING_DIR/conf/defaults.ini`
- Custom configuration from `$WORKING_DIR/conf/custom.ini`
- The custom configuration file path can be overridden using the `--config` parameter
**Linux**
### Linux
If you installed Grafana using the `deb` or `rpm` packages, then your configuration file is located at `/etc/grafana/grafana.ini` and a separate `custom.ini` is not used. This path is specified in the Grafana init.d script using `--config` file parameter.
**Windows**
### Docker
Refer to [Configure a Grafana Docker image](configure-docker.md) for information about environmental variables, persistent storage, and building custom Docker images.
### Windows
`sample.ini` is in the same directory as `defaults.ini` and contains all the settings commented out. Copy `sample.ini` and name it `custom.ini`.
**macOS**
### MacOS
By default, the configuration file is located at `/usr/local/etc/grafana/grafana.ini`. To configure Grafana, add a configuration file named `custom.ini` to the `conf` folder to override any of the settings defined in `conf/defaults.ini`.
## Comments in .ini Files
@ -48,16 +48,15 @@ Semicolons (the `;` char) are the standard way to comment out lines in a `.ini`
A common problem is forgetting to uncomment a line in the `custom.ini` (or `grafana.ini`) file which causes the configuration option to be ignored.
## Using environment variables
## Configure with environment variables
All options in the configuration file (listed below) can be overridden using environment variables using the syntax:
All options in the configuration file can be overridden using environment variables using the syntax:
```bash
GF_<SectionName>_<KeyName>
```
Where the section name is the text within the brackets. Everything
should be upper case, `.` should be replaced by `_`. For example, given these configuration settings:
Where the section name is the text within the brackets. Everything should be uppercase, `.` should be replaced by `_`. For example, if you have these configuration settings:
```bash
# default section
@ -70,15 +69,15 @@ admin_user = admin
client_secret = 0ldS3cretKey
```
Then you can override them using:
You can override them on Linux machines with:
```bash
export GF_DEFAULT_INSTANCE_NAME=my-instance
export GF_SECURITY_ADMIN_USER=true
export GF_SECURITY_ADMIN_USER=owner
export GF_AUTH_GOOGLE_CLIENT_SECRET=newS3cretKey
```
<hr />
> For any changes to `conf/grafana.ini` (or corresponding environment variables) to take effect, you must restart Grafana for the changes to take effect.
## instance_name
@ -130,8 +129,7 @@ The IP address to bind to. If empty will bind to all interfaces
### http_port
The port to bind to, defaults to `3000`. To use port 80 you need to
either give the Grafana binary permission for example:
The port to bind to, defaults to `3000`. To use port 80 you need to either give the Grafana binary permission for example:
```bash
$ sudo setcap 'cap_net_bind_service=+ep' /usr/sbin/grafana-server
@ -156,13 +154,11 @@ Path where the socket should be created when `protocol=socket`. Please make sure
### domain
This setting is only used in as a part of the `root_url` setting (see below). Important if you
use GitHub or Google OAuth.
This setting is only used in as a part of the `root_url` setting (see below). Important if you use GitHub or Google OAuth.
### enforce_domain
Redirect to correct domain if host header does not match domain.
Prevents DNS rebinding attacks. Default is `false`.
Redirect to correct domain if host header does not match domain. Prevents DNS rebinding attacks. Default is `false`.
### root_url
@ -177,8 +173,7 @@ callback URL to be correct).
### serve_from_sub_path
> Available in 6.3 and above
Serve Grafana from subpath specified in `root_url` setting. By
default it is set to `false` for compatibility reasons.
Serve Grafana from subpath specified in `root_url` setting. By default it is set to `false` for compatibility reasons.
By enabling this setting and using a subpath in `root_url` above, e.g.
`root_url = http://localhost:3000/grafana`, Grafana will be accessible on

89
docs/sources/installation/configure-docker.md Normal file
View File

@ -0,0 +1,89 @@
+++
title = "Configure Grafana Docker image"
description = "Guide for configuring the Grafana Docker image"
keywords = ["grafana", "configuration", "documentation", "docker"]
type = "docs"
[menu.docs]
name = "Configure Grafana Docker image"
identifier = "docker"
parent = "administration"
weight = 650
+++
# Configure a Grafana Docker image
If you are running Grafana in a Docker image, then you configure Grafana using [environment variables]({{< relref "configuration.md#configure-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.
## Save your Grafana data
If you do not designate a location for information storage, then all your Grafana data disappears as soon as you stop your image. To save your data, you need to set up persistent storage or bind mounts for your container.
### Run Grafana container with persistent storage (recommended)
```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
```
### Run Grafana container using bind mounts
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.
```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:5.1.0
```
## 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`.
Setting | Default value
----------------------|---------------------------
GF_PATHS_CONFIG | /etc/grafana/grafana.ini
GF_PATHS_DATA | /var/lib/grafana
GF_PATHS_HOME | /usr/share/grafana
GF_PATHS_LOGS | /var/log/grafana
GF_PATHS_PLUGINS | /var/lib/grafana/plugins
GF_PATHS_PROVISIONING | /etc/grafana/provisioning
## Configure Grafana with Docker Secrets
> Only available in Grafana v5.2 and later.
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 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:
- Admin password secret: `/run/secrets/admin_password`
- Environment variable: `GF_SECURITY_ADMIN_PASSWORD__FILE=/run/secrets/admin_password`
## Configure AWS credentials for CloudWatch Support
```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
```
You may also specify multiple profiles to `GF_AWS_PROFILES` (e.g.
`GF_AWS_PROFILES=default another`).
Supported 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).

2
docs/sources/installation/debian.md
View File

@ -168,4 +168,4 @@ Refer to the [Getting Started]({{< relref "../guides/getting_started/" >}}) guid
## Configure Grafana
Refer the [Configuration]({{< relref "configuration.md" >}}) page for details on options for customizing your environment, logging, database, and so on.
Refer to the [Configuration]({{< relref "configuration.md" >}}) page for details on options for customizing your environment, logging, database, and so on.

282
docs/sources/installation/docker.md
View File

@ -1,114 +1,108 @@
+++
title = "Installing using Docker"
description = "Installing Grafana using Docker guide"
title = "Run Grafana Docker image"
description = "Guide for running Grafana using Docker"
keywords = ["grafana", "configuration", "documentation", "docker"]
type = "docs"
[menu.docs]
name = "Installing using Docker"
name = "Run Grafana Docker image"
identifier = "docker"
parent = "installation"
weight = 600
+++
# Installing using Docker
# Run Grafana Docker image
Grafana is very easy to install and run using the official Docker container.
You can install and run Grafana using the official Docker container. The official Grafana Docker image comes in two variants: Alpine and Ubuntu.
```bash
$ docker run -d -p 3000:3000 grafana/grafana
```
This page also contains important information about [migrating from earlier Docker container versions](#migrate-from-previous-docker-containers-versions).
## Configuration
All options defined in `conf/grafana.ini` can be overridden using environment
variables by using the syntax `GF_<SectionName>_<KeyName>`.
For example:
```bash
$ docker run -d \
-p 3000:3000 \
--name=grafana \
-e "GF_SERVER_ROOT_URL=http://grafana.server.name" \
-e "GF_SECURITY_ADMIN_PASSWORD=secret" \
grafana/grafana
```
The back-end web server has a number of configuration options. Go to the
[Configuration]({{< relref "configuration.md" >}}) page for details on all
those options.
> For any changes to `conf/grafana.ini` (or corresponding environment variables) to take effect you need to restart Grafana by restarting the Docker container.
### 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`.
Setting | Default value
----------------------|---------------------------
GF_PATHS_CONFIG | /etc/grafana/grafana.ini
GF_PATHS_DATA | /var/lib/grafana
GF_PATHS_HOME | /usr/share/grafana
GF_PATHS_LOGS | /var/log/grafana
GF_PATHS_PLUGINS | /var/lib/grafana/plugins
GF_PATHS_PROVISIONING | /etc/grafana/provisioning
## Image Variants
The official Grafana Docker image comes in two variants.
**`grafana/grafana:<version>`:**
> **Note:** This image was based on [Ubuntu](https://ubuntu.com/) before version 6.4.0.
## Alpine image (recommended)
`grafana/grafana:<version>`
This is the default image. This image is 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.
This 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 does use [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 doesn't have an issue with this, so this variant is usually a very safe choice.
**`grafana/grafana:<version>-ubuntu`:**
> **Note:** The `grafana/grafana:<version>` image was based on [Ubuntu](https://ubuntu.com/) before version 6.4.0.
> **Note:** This image is available since version 6.5.0.
## Ubuntu image
`grafana/grafana:<version>-ubuntu`
This image is based on [Ubuntu](https://ubuntu.com/), available in [the ubuntu official image](https://hub.docker.com/_/ubuntu).
This is an alternative image for those who prefer an [Ubuntu](https://ubuntu.com/) based image and/or who are dependent on certain
tooling not available for Alpine.
This image is based on [Ubuntu](https://ubuntu.com/), available in [the Ubuntu official image](https://hub.docker.com/_/ubuntu). This is an alternative image for those who prefer an [Ubuntu](https://ubuntu.com/) based image and/or who are dependent on certain tooling not available for Alpine.
## Running a specific version of Grafana
> **Note:** The `grafana/grafana:<version>-ubuntu` image is available for Grafana version 6.5.0 and later.
## Run Grafana
You can run the latest Grafana version, run a specific version, or run an unstable version based on the master branch of the [grafana/grafana GitHub repository](https://github.com/grafana/grafana).
### Run the latest stable version of Grafana
> **Note:** If you are on a Linux system, you might need to add `sudo` before the command.
```bash
# specify right tag, e.g. 6.5.0 - see Docker Hub for available tags
$ docker run -d -p 3000:3000 --name grafana grafana/grafana:6.5.0
# ubuntu based images available since Grafana 6.5.0
$ docker run -d -p 3000:3000 --name grafana grafana/grafana:6.5.0-ubuntu
docker run -d -p 3000:3000 grafana/grafana
```
## Running the master branch
### Run a specific version of Grafana
For every successful build of the master branch we update the `grafana/grafana:master` and `grafana/grafana:master-ubuntu`. Additionally, two new tags are created, `grafana/grafana-dev:master-<commit hash>` and `grafana/grafana-dev:master-<commit hash>-ubuntu`, which includes the hash of the git commit that was built. This means you can always get the latest version of Grafana.
> **Note:** If you are on a Linux system, you might need to add `sudo` before the command.
When running Grafana master in production we **strongly** recommend that you use the `grafana/grafana-dev:master-<commit hash>` tag as that will guarantee that you use a specific version of Grafana instead of whatever was the most recent commit at the time.
```bash
docker run -d -p 3000:3000 --name grafana grafana/grafana:<version number>
```
**Example:**
```bash
docker run -d -p 3000:3000 --name grafana grafana/grafana:6.5.0
```
### Run the Grafana master branch
For every successful build of the master branch, we update the `grafana/grafana:master` and `grafana/grafana:master-ubuntu` tags. Additionally, two new tags are created, `grafana/grafana-dev:master-<commit hash>` and `grafana/grafana-dev:master-<commit hash>-ubuntu`, which includes the hash of the Git commit that was built. Use these to get access to the latest master builds of Grafana.
When running Grafana master in production, we *strongly* recommend that you use the `grafana/grafana-dev:master-<commit hash>` tag. This tag guarantees that you use a specific version of Grafana instead of whatever was the most recent commit at the time.
For a list of available tags, check out [grafana/grafana](https://hub.docker.com/r/grafana/grafana/tags/) and [grafana/grafana-dev](https://hub.docker.com/r/grafana/grafana-dev/tags/).
## Installing Grafana plugins
## Install plugins in the Docker container
Pass the plugins you want installed to docker with the `GF_INSTALL_PLUGINS` environment variable as a comma separated list. This will pass each plugin name to `grafana-cli plugins install ${plugin}` and install them when Grafana starts.
You can install official and community plugins listed on the Grafana [plugins page](https://grafana.com/grafana/plugins) or from a custom URL.
### Install official and community Grafana plugins
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.
```bash
docker run -d \
-p 3000:3000 \
--name=grafana \
-e "GF_INSTALL_PLUGINS=grafana-clock-panel,grafana-simple-json-datasource" \
grafana/grafana
-p 3000:3000 \
--name=grafana \
-e "GF_INSTALL_PLUGINS=grafana-clock-panel,grafana-simple-json-datasource" \
grafana/grafana
```
> If you need to specify the version of a plugin, you can add it to the `GF_INSTALL_PLUGINS` environment variable. Otherwise, the latest will be assumed. For example: `-e "GF_INSTALL_PLUGINS=grafana-clock-panel 1.0.1,grafana-simple-json-datasource 1.3.5"`
> 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 will be assumed. For example: `-e "GF_INSTALL_PLUGINS=grafana-clock-panel 1.0.1,grafana-simple-json-datasource 1.3.5"`.
## Building a custom Grafana image
### Install plugins from other sources
In the [Grafana GitHub repository](https://github.com/grafana/grafana/tree/master/packaging/docker) there is a folder called `custom/` which two includes Dockerfiles, `Dockerfile` and `ubuntu.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.
> Only available in Grafana v5.3.1 and later.
### With pre-installed plugins
You can install plugins from custom URLs by specifying the URL like this: `GF_INSTALL_PLUGINS=<url to plugin zip>;<plugin name>`.
```bash
docker run -d \
-p 3000:3000 \
--name=grafana \
-e "GF_INSTALL_PLUGINS=http://plugin-domain.com/my-custom-plugin.zip;custom-plugin" \
grafana/grafana
```
## Build and run a Docker image with pre-installed plugins
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.
In the [Grafana GitHub repository](https://github.com/grafana/grafana/tree/master/packaging/docker) there is a folder called `custom/` which includes two Dockerfiles, `Dockerfile` and `ubuntu.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.
### Build with pre-installed plugins
> 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"`
@ -116,147 +110,86 @@ Example of how to build and run:
```bash
cd custom
docker build \
--build-arg "GRAFANA_VERSION=latest" \
--build-arg "GF_INSTALL_PLUGINS=grafana-clock-panel,grafana-simple-json-datasource" \
-t grafana-custom -f Dockerfile .
--build-arg "GRAFANA_VERSION=latest" \
--build-arg "GF_INSTALL_PLUGINS=grafana-clock-panel,grafana-simple-json-datasource" \
-t grafana-custom -f Dockerfile .
docker run -d -p 3000:3000 --name=grafana grafana-custom
```
Replace `Dockerfile` in above example with `ubuntu.Dockerfile` to build a custom Ubuntu based image (Grafana 6.5+).
Replace `Dockerfile` in above example with `ubuntu.Dockerfile` to build a custom Ubuntu based image (Grafana v6.5+).
### With Grafana Image Renderer plugin pre-installed
### Build with Grafana Image Renderer plugin pre-installed
> Only available in Grafana v6.5+ and experimental.
> Only available in Grafana v6.5 and later. This is experimental.
The [Grafana Image Renderer plugin]({{< relref "../administration/image_rendering/#grafana-image-renderer-plugin" >}}) does not
currently work if it is installed in Grafana docker image.
You can build a custom docker image by using the `GF_INSTALL_IMAGE_RENDERER_PLUGIN` build argument.
This will install additional dependencies needed for the Grafana Image Renderer plugin to run.
The [Grafana Image Renderer plugin]({{< relref "../administration/image_rendering/#grafana-image-renderer-plugin" >}}) does not currently work if it is installed in 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 custom
docker build \
--build-arg "GRAFANA_VERSION=latest" \
--build-arg "GF_INSTALL_IMAGE_RENDERER_PLUGIN=true" \
-t grafana-custom -f Dockerfile .
--build-arg "GRAFANA_VERSION=latest" \
--build-arg "GF_INSTALL_IMAGE_RENDERER_PLUGIN=true" \
-t grafana-custom -f Dockerfile .
docker run -d -p 3000:3000 --name=grafana grafana-custom
```
Replace `Dockerfile` in above example with `ubuntu.Dockerfile` to build a custom Ubuntu based image.
Replace `Dockerfile` in above example with `ubuntu.Dockerfile` to build a custom Ubuntu-based image (Grafana v6.5+).
## Installing plugins from other sources
## Migrate from previous Docker containers versions
> Only available in Grafana v5.3.1+
This section contains important information if you want to migrate from previous Grafana container versions to a more current one.
It's possible to install plugins from custom url:s by specifying the url like this: `GF_INSTALL_PLUGINS=<url to plugin zip>;<plugin name>`
### Migrate to v6.5 or later
```bash
docker run -d \
-p 3000:3000 \
--name=grafana \
-e "GF_INSTALL_PLUGINS=http://plugin-domain.com/my-custom-plugin.zip;custom-plugin" \
grafana/grafana
```
Grafana Docker image now comes in two variants, one [Alpine](http://alpinelinux.org) based and one [Ubuntu](https://ubuntu.com/) based, see [Image Variants](#image-variants) for details.
## Configuring AWS credentials for CloudWatch Support
```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
```
### Migrate to v6.4 or later
You may also specify multiple profiles to `GF_AWS_PROFILES` (e.g.
`GF_AWS_PROFILES=default another`).
Grafana Docker image was changed to be based on [Alpine](http://alpinelinux.org) instead of [Ubuntu](https://ubuntu.com/).
Supported 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).
## Grafana container with persistent storage (recommended)
```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
```
## Grafana container using bind mounts
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.
```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:5.1.0
```
## Reading secrets from files (support for Docker Secrets)
> Only available in Grafana v5.2+.
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 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.
Let's say you want to set the admin password this way:
- Admin password secret: `/run/secrets/admin_password`
- Environment variable: `GF_SECURITY_ADMIN_PASSWORD__FILE=/run/secrets/admin_password`
## Migration from a previous version of the docker container to 5.1 or later
### 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 `472` instead of `104`
* no more implicit volumes
* 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
#### 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 you should be aware that an upgraded container will no longer have them.
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.
**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
#### User ID changes
In 5.1 we switched the id of the grafana user. Unfortunately this means that files created prior to 5.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.
In Grafana v5.1, we changed the ID of the Grafana user. 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
--------|---------|---------
< 5.1 | grafana | 104
>= 5.1 | grafana | 472
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`.
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`.
#### Running docker as a different user
##### Run Docker as a different user
```bash
docker run --user 104 --volume "<your volume mapping here>" grafana/grafana:5.1.0
```
##### Specifying a user in docker-compose.yml
##### Specify a user in docker-compose.yml
```yaml
version: "2"
@ -268,29 +201,28 @@ services:
user: "104"
```
#### Modifying permissions
#### Modify permissions
The commands below will 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.
The commands below runs 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:5.1.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
chmod -R a+r /etc/grafana && \
chown -R grafana:grafana /var/lib/grafana && \
chown -R grafana:grafana /usr/share/grafana
```
## Migration from a previous version of the docker container to 6.4 or later
## Next steps
Grafana’s docker image was changed to be based on [Alpine](http://alpinelinux.org) instead of [Ubuntu](https://ubuntu.com/).
Refer to the [Getting Started]({{< relref "../guides/getting_started/" >}}) guide for information about logging in, setting up data sources, and so on.
## Migration from a previous version of the docker container to 6.5 or later
## Configure Docker image
Grafana Docker image now comes in two variants, one [Alpine](http://alpinelinux.org) based and one [Ubuntu](https://ubuntu.com/) based, see [Image Variants](#image-variants) for details.
Refer to [Configure a Grafana Docker image]({{< relref "configure-docker.md" >}}) page for details on options for customizing your environment, logging, database, and so on.
## Logging in for the first time
## Configure Grafana
To run Grafana open your browser and go to http://localhost:3000/. 3000 is the default HTTP port that Grafana listens to if you haven't [configured a different port]({{< relref "configuration/#http-port" >}}).
Then follow the instructions [here]({{< relref "../guides/getting_started/" >}}).
Refer to the [Configuration]({{< relref "configuration.md" >}}) page for details on options for customizing your environment, logging, database, and so on.

2
docs/sources/installation/rpm.md
View File

@ -205,4 +205,4 @@ Refer to the [Getting Started]({{< relref "../guides/getting_started/" >}}) guid
## Configure Grafana
Refer the [Configuration]({{< relref "configuration.md" >}}) page for details on options for customizing your environment, logging, database, and so on.
Refer to the [Configuration]({{< relref "configuration.md" >}}) page for details on options for customizing your environment, logging, database, and so on.

14
docs/sources/menu.yaml
View File

@ -3,25 +3,27 @@
children:
- name: Requirements
link: /installation/requirements/
- name: Installing on Ubuntu / Debian
- name: Install on Ubuntu / Debian
link: /installation/debian/
- name: Installing on Centos / Redhat
- name: Install on Centos / Redhat
link: /installation/rpm/
- name: Installing on Windows
- name: Install on Windows
link: /installation/windows/
- name: Installing on macOS
- name: Install on macOS
link: /installation/mac/
- name: Installing using Docker
- name: Install using Docker
link: /installation/docker/
- name: Building from source
link: /project/building_from_source/
- name: Upgrading
- name: Upgrade Grafana
link: /installation/upgrading/
- name: Administration
link: /administration/
children:
- name: Configuration
link: /installation/configuration/
- name: Configure Docker image
link: /installation/configure-docker/
- name: Security
link: /installation/security/
- name: Authentication