Skip to content

Commit d6f4cde

Browse files
SlykeSlyke
authored
Merge pull request #516 from ukkopahis/doc-grafana
grafana: Fix outdated documentation
2 parents dc19742 + ed79018 commit d6f4cde

File tree

1 file changed

+70
-153
lines changed

1 file changed

+70
-153
lines changed

‎docs/Containers/Grafana.md

Lines changed: 70 additions & 153 deletions
Original file line numberDiff line numberDiff line change
@@ -5,19 +5,12 @@
55
- [Docker](https://hub.docker.com/r/grafana/grafana)
66
- [Website](https://grafana.com/)
77

8-
## Setting your time-zone
9-
10-
The default *~/IOTstack/services/grafana/grafana.env* contains this line:
11-
12-
```
13-
#TZ=Africa/Johannesburg
14-
```
15-
16-
Uncomment that line and change the right hand side to [your own timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
17-
188
## Adding InfluxDB datasource
199

20-
Select Data Sources -> Add data source -> InfluxDB.
10+
When you have logged into Grafana (default user/pass: admin/admin), you have
11+
to add a data source to be used for the graphs.
12+
13+
Select `Data Sources` -> `Add data source` -> `InfluxDB`.
2114

2215
Set options:
2316

@@ -26,188 +19,110 @@ Set options:
2619
* InfluxDB Details / User: `nodered`
2720
* InfluxDB Details / Password: `nodered`
2821

29-
## Security
30-
31-
If Grafana has just been installed but has **never** been launched then the following will be true:
32-
33-
* The folder *~/IOTstack/volumes/grafana* will not exist; and
34-
* The file *~/IOTstack/services/grafana/grafana.env* will contain these lines:
35-
36-
```
37-
#GF_SECURITY_ADMIN_USER=admin
38-
#GF_SECURITY_ADMIN_PASSWORD=admin
39-
```
40-
41-
You should see those lines as **documentation** rather than something you are being invited to edit. It is telling you that the default administative user for Grafana is "admin" and that the default password for that user is "admin".
42-
43-
If you do not change anything then, when you bring up the stack and use a browser to connect to your Raspberry Pi on port 3000, Grafana will:
44-
45-
* Expect you to login as user "admin" with password "admin"; and then
46-
* Force you to change the default password to something else.
47-
48-
Thereafter, you will login as "admin" with whatever password you chose. You can change the administrator's password as often as you like via the web UI (*profile* button, *change password* tab).
49-
50-
This method (of **not** touching these two keys in *grafana.env*) is the recommended approach. *Please* try to resist the temptation to fiddle!
22+
## Overriding configuration variables
5123

52-
### I want a different admin username (not recommended)
24+
Grafana documentation contains [a list of
25+
settings](https://grafana.com/docs/grafana/latest/administration/configuration/).
26+
Settings are described in terms of how they appear in ".ini" files.
5327

54-
If, before you bring up the stack for the first time, you do this:
28+
Grafana configuration is usually done in *grafana.ini*, but when used via
29+
docker as the IOTstack does, it should be configured using [environment
30+
variables](https://grafana.com/docs/grafana/latest/administration/configuration/#override-configuration-with-environment-variables).
5531

32+
Edit `docker-compose.yml` and find `grafana:` and under it
33+
`environment:` this is where you can place the ini-options, but formatted as:
34+
```yaml
35+
- GF_<SectionName>_<KeyName>=<value>
5636
```
57-
GF_SECURITY_ADMIN_USER=jack
58-
#GF_SECURITY_ADMIN_PASSWORD=admin
59-
```
60-
61-
then, when you bring up the stack and connect on port 3000, Grafana will:
62-
63-
* Expect you to login as user "jack" with password "admin"; and then
64-
* Force you to change the default password to something else.
65-
66-
Thereafter, "jack" will be the Grafana administrator and you will login with the password you chose, until you decide to change the password to something else via the web UI.
37+
If you are using old-menu edit `~/IOTstack/services/grafana/grafana.env`
38+
instead and add the lines directly there, but without the leading dash:
39+
`GF_<SectionName>_<KeyName>=<value>`
6740

68-
Don't think you can come back later and tweak the Grafana administrator name in the environment variables. It doesn't work that way. It's a one-shot.
41+
For any changes to take effect you need recreate the Grafana container:
6942

70-
### I want a different default admin password (not recommended)
71-
72-
Well, first off, the two methods above both make you set a different password on first login so there probably isn't much point to this.
73-
74-
But, if you *really* insist…
75-
76-
If, before you bring up the stack for the first time, you do this:
77-
78-
```
79-
#GF_SECURITY_ADMIN_USER=admin
80-
GF_SECURITY_ADMIN_PASSWORD=jack
43+
``` console
44+
$ docker-compose up -d grafana
8145
```
82-
83-
then, when you bring up the stack and use a browser to connect to your Raspberry Pi on port 3000, Grafana will expect you to login as user "admin" with password "jack".
8446

85-
Grafana will not force you to change the password on first login but you will still be able to change it via the web UI.
47+
### Setting your time-zone
8648

87-
But don't think you can come back later and change the password in the environment variables. It doesn't work that way. It's a one-shot.
49+
Change the right hand side to [your own
50+
timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones):
8851

89-
### I want to change everything (not recommended)
90-
91-
If, before you bring up the stack for the first time, you do this:
92-
93-
```
94-
GF_SECURITY_ADMIN_USER=bill
95-
GF_SECURITY_ADMIN_PASSWORD=jack
52+
```yaml
53+
- TZ=Etc/UTC
9654
```
9755

98-
then, when you bring up the stack and use a browser to connect to your Raspberry Pi on port 3000, Grafana will expect you to login as user "bill" with password "jack".
99-
100-
Grafana will not force you to change the password on first login but you will still be able to change it via the web UI.
101-
102-
But don't think you can come back later and tweak either the username or password in the environment variables. It doesn't work that way. It's a one-shot.
56+
### Anonymous login
10357

104-
### Distilling it down
105-
106-
**Before** Grafana is launched for the first time:
107-
108-
* *GF\_SECURITY\_ADMIN\_USER* has a default value of "admin". You *can* explicitly set it to "admin" or some other value. Whatever option you choose then that's the account name of Grafana's administrative user. But choosing any value other than "admin" is probably a bad idea.
109-
* *GF\_SECURITY\_ADMIN\_PASSWORD* has a default value of "admin". You can explicitly set it to "admin" or some other value. If its value is "admin" then you will be forced to change it the first time you login to Grafana. If its value is something other than "admin" then that will be the password until you change it via the web UI.
58+
To allow anonymous logins add:
11059

111-
These two environment keys **only** work for the **first** launch of Grafana. Once Grafana has been launched, you can **never** change either the username or the password by editing *grafana.env*.
112-
113-
For this reason, it is better to leave *grafana.env* in its shrink-wrapped state. Your first login is as "admin/admin" and then you set the password you actually want when Grafana prompts you to change it.
114-
115-
### HELP – I forgot my Grafana admin password!
116-
117-
Assuming your IOTstack is up, the magic incantation is:
118-
119-
```
120-
$ docker exec grafana grafana-cli --homepath "/usr/share/grafana" admin reset-admin-password "admin"
60+
```yaml
61+
- GF_AUTH_ANONYMOUS_ENABLED=true
12162
```
12263

123-
Then, use a browser to connect to your Raspberry Pi on port 3000. Grafana will:
124-
125-
* Expect you login as user "admin" with password "admin"; and then
126-
* Force you to change the default password to something else.
127-
128-
This magic incantation assumes that your administrative username is "admin". If you ignored the advice above and changed the administator username to something else then all bets are off. It might work anyway but we haven't tested it. Sorry. But that's why we said changing the username was not recommended.
64+
### Custom admin user and password (not recommended)
12965

130-
## Overriding Grafana settings
66+
If you do not change anything then, when you bring up the stack and use a browser to connect to your Raspberry Pi on port 3000, Grafana will:
13167

132-
Grafana documentation contains [a list of settings](https://grafana.com/docs/installation/configuration/). Settings are described in terms of how they appear in ".ini" files.
68+
* Expect you to login as user "admin" with password "admin"; and then
69+
* Force you to change the default password to something else.
13370

134-
An example of the sort of thing you might want to do is to enable anonymous access to your Grafana dashboards. The [Grafana documentation](https://grafana.com/docs/grafana/latest/auth/overview/#anonymous-authentication) describes this in ".ini" format as:
71+
Thereafter, you will login as "admin" with whatever password you chose. You can change the administrator's password as often as you like via the web UI (*profile* button, *change password* tab).
13572

136-
```
137-
[auth.anonymous]
138-
enabled = true
73+
This default operation can be changed by configuration options. They will have
74+
any effect only if Grafana has just been added to the stack, but has **never**
75+
been launched. Thus, if the folder *~/IOTstack/volumes/grafana* exists, Grafana
76+
has already been started, and adding and changing these options **will not**
77+
have any effect.
13978

140-
# Organization name that should be used for unauthenticated users
141-
org_name = Main Org.
79+
To customize, editing the file as describe above, add the following lines under
80+
the `environment:`-section. The default configuration is:
14281

143-
# Role for unauthenticated users, other valid values are `Editor` and `Admin`
144-
org_role = Viewer
82+
```yaml
83+
- GF_SECURITY_ADMIN_USER=admin
84+
- GF_SECURITY_ADMIN_PASSWORD=admin
14585
```
14686

147-
".ini" format is not really appropriate in a Docker context. Instead, you use environment variables to override Docker's settings. Environment variables are placed in *~/IOTstack/services/grafana/grafana.env*.
87+
If you change the default password, Grafana will not force you to change the
88+
password on first login but you will still be able to change it via the web UI.
14889

149-
You need to convert ".ini" format to environment variable syntax. The rules are:
90+
As a summary, these work only **before** Grafana is launched for the first time:
15091

151-
* Start with "GF_", then
152-
* Append the \[section name\], replacing any periods with underscores, then
153-
* Append the section key "as is", then
154-
* Append an "=", then
155-
* Append the right hand side in quotes.
156-
157-
Applying those rules gets you:
158-
159-
```
160-
GF_AUTH_ANONYMOUS_ENABLED="true"
161-
GF_AUTH_ANONYMOUS_ORG_NAME="Main Org."
162-
GF_AUTH_ANONYMOUS_ORG_ROLE="Viewer"
163-
```
92+
* *GF\_SECURITY\_ADMIN\_USER* has a default value of "admin". You *can* explicitly set it to "admin" or some other value. Whatever option you choose then that's the account name of Grafana's administrative user. But choosing any value other than "admin" is probably a bad idea.
93+
* *GF\_SECURITY\_ADMIN\_PASSWORD* has a default value of "admin". You can explicitly set it to "admin" or some other value. If its value is "admin" then you will be forced to change it the first time you login to Grafana. If its value is something other than "admin" then that will be the password until you change it via the web UI.
16494

165-
> It is not strictly necessary to encapsulate every right hand side value in quotes. In the above, both "true" and "Viewer" would work without quotes, whereas "Main Org." needs quotes because of the embedded space.
95+
### Options with spaces
16696

167-
After you have changed *~/IOTstack/services/grafana/grafana.env*, you need to propagate the changes into the Grafana container:
97+
To set an options with a space, you must enclose the whole value in quotes:
16898

99+
```yaml
100+
- "GF_AUTH_ANONYMOUS_ORG_NAME=Main Org."
169101
```
170-
$ cd ~/IOTstack
171-
$ docker-compose stop grafana
172-
$ docker-compose up -d
173-
```
174-
175-
> In theory, the second command could be omitted, or both the second and third commands could be replaced with "docker-compose restart grafana" but experience suggests stopping the container is more reliable.
176102

177-
A slightly more real-world example would involve choosing a different default organisation name for anonymous access. This example uses "ChezMoi".
103+
## HELP – I forgot my Grafana admin password!
178104

179-
First, the environment key needs to be set to that value:
105+
Assuming Grafana is started and, run:
180106

181107
```
182-
GF_AUTH_ANONYMOUS_ORG_NAME=ChezMoi
108+
$ docker-compose exec grafana grafana-cli --homepath "/usr/share/grafana" admin reset-admin-password "admin"
183109
```
184110

185-
Then that change needs to be propagated into the Grafana container as explained above.
186-
187-
Next, Grafana needs to be told that "ChezMoi" is the default organisation:
111+
Then, use a browser to connect to your Raspberry Pi on port 3000. Grafana will:
188112

189-
1. Use your browser to login to Grafana as an administrator.
190-
2. From the "Server Admin" slide-out menu on the left hand side, choose "Orgs".
191-
3. In the list that appears, click on "Main Org". This opens an editing panel.
192-
4. Change the "Name" field to "ChezMoi" and click "Update".
193-
5. Sign-out of Grafana. You will be taken back to the login screen. Your URL bar will look something like this:
113+
* Expect you login as user "admin" with password "admin"; and then
114+
* Force you to change the default password to something else.
194115

195-
```
196-
http://myhost.mydomain.com:3000/login
197-
```
198-
6. Edit the URL to remove the "login" suffix and press return. If all your changes were applied successfully, you will have anonymous access and the URL will look something like this:
199-
200-
```
201-
http://myhost.mydomain.com:3000/?orgId=1
202-
```
116+
Note: If you have customized *GF\_SECURITY\_ADMIN\_USER*, you'll need to use it
117+
as the user instead.
203118

204-
## HELP – I made a mess!
119+
## HELP - Resetting to a clean slate
205120

206121
"I made a bit of a mess with Grafana. First time user. Steep learning curve. False starts, many. Mistakes, unavoidable. Been there, done that. But now I **really** need to start from a clean slate. And, yes, I understand there is no *undo* for this."
207122

208123
Begin by stopping Grafana:
209124

210-
```
125+
``` console
211126
$ cd ~/IOTstack
212127
$ docker-compose stop grafana
213128
```
@@ -216,21 +131,23 @@ You have two options:
216131

217132
1. Destroy your settings and dashboards but retain any plugins you may have installed:
218133

219-
```
134+
``` console
220135
$ sudo rm ~/IOTstack/volumes/grafana/data/grafana.db
221136
```
222137

223138
2. Nuke everything (triple-check this command **before** you hit return):
224139

225-
```
140+
``` console
226141
$ sudo rm -rf ~/IOTstack/volumes/grafana/data
227142
```
228143

229-
This is where you should edit *~/IOTstack/services/grafana/grafana.env* to correct any problems (such as choosing an administrative username other than "admin").
144+
This is where you should edit *docker-compose.yml* or
145+
*~/IOTstack/services/grafana/grafana.env* to correct any problems (such as
146+
choosing an administrative username other than "admin").
230147

231148
When you are ready, bring Grafana back up again:
232149

233-
```
150+
``` console
234151
$ cd ~/IOTstack
235152
$ docker-compose up -d
236153
```

0 commit comments

Comments
 (0)