docs: new docker image in Grafana 5.1.0.

docs/sources/installation/docker.md

@@ -18,28 +18,6 @@ Grafana is very easy to install and run using the official docker container.
 $ docker run -d -p 3000:3000 grafana/grafana
 ```
 
-All Grafana configuration settings can be defined using environment
-variables, this is especially useful when using the above container.
-
-## Docker volumes & ENV config
-
-The Docker container exposes two volumes, the sqlite3 database in the
-folder `/var/lib/grafana` and configuration files is in `/etc/grafana/`
-folder. You can map these volumes to host folders when you start the
-container:
-
-```bash
-$ docker run -d -p 3000:3000 \
-    -v /var/lib/grafana:/var/lib/grafana \
-    -e "GF_SECURITY_ADMIN_PASSWORD=secret" \
-    grafana/grafana
-```
-
-In the above example I map the data folder and sets a configuration option via
-an `ENV` instruction. 
-
-See the [docker volumes documentation](https://docs.docker.com/engine/admin/volumes/volumes/) if you want to create a volume to use with the Grafana docker image instead of a bind mount (binding to a directory in the host system).
-
 ## Configuration
 
 All options defined in conf/grafana.ini can be overridden using environment
@@ -56,15 +34,24 @@ $ docker run \
   grafana/grafana
 ```
 
-You can use your own grafana.ini file by using environment variable `GF_PATHS_CONFIG`.
-
 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.
 
+## Running a Specific Version of Grafana
+
+```bash
+# specify right tag, e.g. 5.1.0 - see Docker Hub for available tags
+$ docker run \
+  -d \
+  -p 3000:3000 \
+  --name grafana \
+  grafana/grafana:5.1.0
+```
+
 ## Installing Plugins for Grafana
 
-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}`.
+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.
 
 ```bash
 docker run \
@@ -75,15 +62,22 @@ docker run \
   grafana/grafana
 ```
 
-## Running a Specific Version of Grafana
+## Building a custom Grafana image with pre-installed plugins
 
+In the [grafana-docker](https://github.com/grafana/grafana-docker/)  there is a folder called `custom/` which includes a `Dockerfile` that can be used to build a custom Grafana image.  It accepts `GRAFANA_VERSION` and `GF_INSTALL_PLUGINS` as build arguments.
+
+Example of how to build and run:
 ```bash
-# specify right tag, e.g. 4.5.2 - see Docker Hub for available tags
-$ docker run \
+cd custom
+docker build -t grafana:latest-with-plugins \
+  --build-arg "GRAFANA_VERSION=latest" \
+  --build-arg "GF_INSTALL_PLUGINS=grafana-clock-panel,grafana-simple-json-datasource" .
+
+docker run \
   -d \
   -p 3000:3000 \
-  --name grafana \
-  grafana/grafana:5.0.2
+  --name=grafana \
+  grafana:latest-with-plugins
 ```
 
 ## Configuring AWS Credentials for CloudWatch Support
@@ -108,3 +102,73 @@ 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
+```
+
+## Migration from a previous version of the docker container to 5.1 or later
+
+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 easier for you to control what user Grafana is executed as (see examples below).
+
+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`.
+
+### Running docker as a different user
+
+```bash
+docker run --user 104 --volume "<your volume mapping here>" grafana/grafana:5.1.0
+```
+
+#### docker-compose.yml with custom user
+```yaml
+version: "2"
+
+services:
+  grafana:
+    image: grafana/grafana:5.1.0
+    ports:
+      - 3000:3000
+    user: "104"
+```
+
+### Modifying 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. 
+
+```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
+```