Skip to content

N
nexpie-grafana-theme
Commit 4a25ec0d by Diana Payton Committed by GitHub
Options

Docs: Update debian-ubuntu installation instructions (#20875) 

* Update debian-ubuntu installation

Major rework of debian.md, minor updates to a configuration.md and upgrading.md.

* updated docs

Updated per Torkel's comments

* Update debian.md

Added wget to common properties install command

* Update docs/sources/installation/debian.md

Co-Authored-By: Dan Cech <dcech@grafana.com>

* Update docs/sources/installation/debian.md

Co-Authored-By: Dan Cech <dcech@grafana.com>

* Update docs/sources/installation/debian.md

Co-Authored-By: Dan Cech <dcech@grafana.com>

* Update docs/sources/installation/debian.md

Co-Authored-By: Dan Cech <dcech@grafana.com>

* Update docs/sources/installation/debian.md

Co-Authored-By: Dan Cech <dcech@grafana.com>

* Update docs/sources/installation/debian.md

Co-Authored-By: Dan Cech <dcech@grafana.com>

* Update docs/sources/installation/debian.md

Co-Authored-By: Dan Cech <dcech@grafana.com>

* Apply suggestions from code review

Co-Authored-By: Dan Cech <dcech@grafana.com>

* Update upgrading.md

* Update upgrading.md

* Update debian.md

Added ARM link
parent a9bf8f80
Showing with 118 additions and 117 deletions
docs/sources/installation/configuration.md
......@@ -29,18 +29,13 @@ A common problem is forgetting to uncomment a line in the `custom.ini` (or `graf
- Custom configuration from `$WORKING_DIR/conf/custom.ini`
- The custom configuration file path can be overridden using the `--config` parameter
> **Note.** If you have 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.
**Note:** If you have 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.
**macOS:** By default, the configuration file is located at `/usr/local/etc/grafana/grafana.ini`.
## Using 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 (listed below) can be overridden using environment variables using the syntax:
```bash
GF_<SectionName>_<KeyName>
......
docs/sources/installation/debian.md 100755 → 100644
+++
title = "Installing on Debian / Ubuntu"
description = "Install guide for Grafana"
title = "Install on Debian/Ubuntu"
description = "Install guide for Grafana on Debian or Ubuntu"
keywords = ["grafana", "installation", "documentation"]
type = "docs"
aliases = ["/installation/installation/debian"]
[menu.docs]
name = "Installing on Ubuntu / Debian"
name = "Install on Ubuntu/Debian"
identifier = "debian"
parent = "installation"
weight = 200
+++
# Installing on Debian / Ubuntu
# Install on Debian or Ubuntu
Read [Upgrading Grafana]({{< relref "upgrading.md" >}}) for tips and guidance on updating an existing
installation.
This page explains how to install Grafana dependencies, download and install Grafana, get the service up and running on your system, and the package details.
aster
## Download
**Note on upgrading:** While the process for upgrading Grafana is very similar to installing Grafana, there are some key backup steps you should perform. Read [Upgrading Grafana]({{< relref "installation/upgrading.md" >}}) for tips and guidance on updating an existing installation.
Go to the [download page](https://grafana.com/grafana/download?platform=linux) for the latest download
links.
## 1. Download and install
```bash
wget <debian package url>
sudo apt-get install -y adduser libfontconfig1
sudo dpkg -i grafana_<version>_amd64.deb
```
We recommend that you run all the listed commands before you download and install Grafana. They might not be necessary on all systems, but if you run them first then you will not be interrupted by dependency errors.
You can install Grafana using our official APT repository, by downloading a `.deb` package, or by using a binary `.tar.gz` file.
You will find package URLs on the [download page](https://grafana.com/grafana/download?platform=linux).
### Install from APT repository
On some older versions of Ubuntu and Debian you may need to install the
`apt-transport-https` package which is needed to fetch packages over
HTTPS.
## APT Repository
```bash
sudo apt-get install -y apt-transport-https
```
The command `add-apt-repository` isn't a default app on Debian 9 and requires you to run:
Install any missing dependencies:
```bash
apt-get install -y software-properties-common
sudo apt-get install -y software-properties-common wget
```
Install the repository for stable releases:
......@@ -49,120 +52,116 @@ There is a separate repository if you want beta releases:
sudo add-apt-repository "deb https://packages.grafana.com/oss/deb beta main"
```
Use the above line even if you are on Ubuntu or another Debian version. Then add our GPG key. This allows you to install signed packages.
Add our GPG key to install signed packages:
```bash
wget -q -O - https://packages.grafana.com/gpg.key | sudo apt-key add -
```
Update your Apt repositories and install Grafana:
Update your APT repositories and install Grafana:
```bash
sudo apt-get update
sudo apt-get install grafana
```
On some older versions of Ubuntu and Debian you may need to install the
`apt-transport-https` package which is needed to fetch packages over
HTTPS.
### Install .deb package
```bash
sudo apt-get install -y apt-transport-https
```
Go to the [Linux download page](https://grafana.com/grafana/download?platform=linux) for the latest download
links.
## Package details
If you use ARM, then use the [ARM download page](https://grafana.com/grafana/download?platform=arm) for the latest download
links.
- Installs binary to `/usr/sbin/grafana-server`
- Installs Init.d script to `/etc/init.d/grafana-server`
- Creates default file (environment vars) to `/etc/default/grafana-server`
- Installs configuration file to `/etc/grafana/grafana.ini`
- Installs systemd service (if systemd is available) name `grafana-server.service`
- The default configuration sets the log file at `/var/log/grafana/grafana.log`
- The default configuration specifies an sqlite3 db at `/var/lib/grafana/grafana.db`
- Installs HTML/JS/CSS and other Grafana files at `/usr/share/grafana`
```bash
sudo wget <.deb package url>
sudo apt-get install -y adduser libfontconfig1
sudo dpkg -i grafana_<version>_amd64.deb
```
## Start the server (init.d service)
## Install from binary .tar.gz file
Start Grafana by running:
Download the latest [`.tar.gz` file](https://grafana.com/grafana/download?platform=linux) and extract it. The files extract into a folder named after the Grafana version that you downloaded. This folder contains all files required to run Grafana. There are no init scripts or install scripts in this package.
```bash
sudo service grafana-server start
sudo wget <tar.gz package url>
sudo apt-get install -y adduser libfontconfig1
sudo tar -zxvf <tar.gz package>
```
This will start the `grafana-server` process as the `grafana` user,
which was created during the package installation. The default HTTP port
is `3000` and default user and group is `admin`.
## 2. Start the server
This starts the `grafana-server` process as the `grafana` user, which was created during the package installation.
Default login and password `admin`/ `admin`
If you installed with the APT repository or `.deb` package, then you can start the server using `systemd` or `init.d`. If you installed a binary `.tar.gz` file, then you need to execute the binary.
To configure the Grafana server to start at boot time:
### Start the server with systemd
To start the service using systemd:
```bash
sudo update-rc.d grafana-server defaults
sudo systemctl daemon-reload
sudo systemctl start grafana-server
sudo systemctl status grafana-server
```
## Start the server (via systemd)
To start the service using systemd:
Verify that the service has started:
```bash
systemctl daemon-reload
systemctl start grafana-server
systemctl status grafana-server
sudo systemctl status grafana-server
```
Enable the systemd service so that Grafana starts at boot.
Enable the systemd service so that Grafana starts at boot:
```bash
sudo systemctl enable grafana-server.service
```
## Environment file
### Start the server with init.d
Start Grafana by running:
The systemd service file and init.d script both use the file located at
`/etc/default/grafana-server` for environment variables used when
starting the back-end. Here you can override log directory, data
directory and other variables.
```bash
sudo service grafana-server start
```
### Logging
Verify that the service has started:
By default Grafana will log to `/var/log/grafana`
```bash
sudo service grafana-server status
```
### Database
Configure the Grafana server to start at boot:
The default configuration specifies a sqlite3 database located at
`/var/lib/grafana/grafana.db`. Please backup this database before
upgrades. You can also use MySQL or Postgres as the Grafana database, as detailed on [the configuration page]({{< relref "configuration.md#database" >}}).
```bash
sudo update-rc.d grafana-server defaults
```
## Configuration
### Execute the binary
The configuration file is located at `/etc/grafana/grafana.ini`. Go the
[Configuration]({{< relref "configuration.md" >}}) page for details on all
those options.
The `grafana-server` binary needs the working directory to be the root install directory where the binary and the `public` folder are located.
### Adding data sources
Start Grafana by running:
```bash
./bin/grafana-server web
```
- [Graphite]({{< relref "../features/datasources/graphite.md" >}})
- [InfluxDB]({{< relref "../features/datasources/influxdb.md" >}})
- [OpenTSDB]({{< relref "../features/datasources/opentsdb.md" >}})
- [Prometheus]({{< relref "../features/datasources/prometheus.md" >}})
## Package details
## Installing from binary tar file
- Installs binary to `/usr/sbin/grafana-server`
- Installs Init.d script to `/etc/init.d/grafana-server`
- Creates default file (environment vars) to `/etc/default/grafana-server`
- Installs configuration file to `/etc/grafana/grafana.ini`
- Installs systemd service (if systemd is available) name `grafana-server.service`
- The default configuration sets the log file at `/var/log/grafana/grafana.log`
- The default configuration specifies an sqlite3 db at `/var/lib/grafana/grafana.db`
- Installs HTML/JS/CSS and other Grafana files at `/usr/share/grafana`
Download [the latest `.tar.gz` file](https://grafana.com/get) and
extract it. This will extract into a folder named after the version you
downloaded. This folder contains all files required to run Grafana. There are
no init scripts or install scripts in this package.
## Next steps
To configure Grafana add a configuration file named `custom.ini` to the
`conf` folder and override any of the settings defined in
`conf/defaults.ini`.
Refer to the [Getting Started](/guides/getting_started/) guide for information about logging in, setting up data sources, and so on.
Start Grafana by executing `./bin/grafana-server web`. The `grafana-server`
binary needs the working directory to be the root install directory (where the
binary and the `public` folder is located).
## Configure Grafana
## Logging in for the first time
Refer the [Configuration]({{< relref "configuration.md" >}}) page for details on options for customizing your environment, logging, database, and so on.
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/" >}}).
docs/sources/installation/upgrading.md
+++
title = "Upgrading"
description = "Upgrading Grafana guide"
title = "Upgrade Grafana"
description = "Guide for upgrading Grafana"
keywords = ["grafana", "configuration", "documentation", "upgrade"]
type = "docs"
[menu.docs]
name = "Upgrading"
name = "Upgrade Grafana"
identifier = "upgrading"
parent = "installation"
weight = 800
+++
# Upgrading Grafana
# Upgrade Grafana
We recommend everyone to upgrade Grafana often to stay up to date with the latest fixes and enhancements.
We recommend that you upgrade Grafana often to stay up to date with the latest fixes and enhancements.
In order make this a reality, Grafana upgrades are backward compatible and the upgrade process is simple and quick.
Upgrading is generally always safe (between many minor and one major version) and dashboards and graphs will look the same. There can be minor breaking changes in some edge cases which are usually outlined in the [Release Notes](https://community.grafana.com/c/releases) and [Changelog](https://github.com/grafana/grafana/blob/master/CHANGELOG.md)
Upgrading is generally safe (between many minor and one major version) and dashboards and graphs will look the same. There may be minor breaking changes in some edge cases, which are outlined in the [Release Notes](https://community.grafana.com/c/releases) and [Changelog](https://github.com/grafana/grafana/blob/master/CHANGELOG.md)
## Update plugins
......@@ -58,29 +58,41 @@ restore:
> psql grafana < grafana_backup
```
### Ubuntu / Debian
### Ubuntu or Debian
If you installed grafana by downloading a debian package (`.deb`) you can just follow the same installation guide
and execute the same `dpkg -i` command but with the new package. It will upgrade your Grafana install.
You can upgrade Grafana by following the same procedure as when you installed it.
If you used our APT repository:
#### Upgrade Debian package
If you installed Grafana by downloading a Debian package (`.deb`), then you can execute the same `dpkg -i` command but with the new package. It will upgrade your Grafana installation.
Go to the [download page](https://grafana.com/grafana/download?platform=linux) for the latest download
links.
```bash
wget <debian package url>
sudo apt-get install -y adduser libfontconfig1
sudo dpkg -i grafana_<version>_amd64.deb
```
#### Upgrade from APT repository
If you installed Grafana from our APT repository, then Grafana will automatically update when you run apt-get upgrade to upgrade all system packages.
```bash
sudo apt-get update
sudo apt-get install grafana
```
#### Upgrading from binary tar file
#### Upgrade from binary .tar file
If you downloaded the binary `.tar.gz` package, then you can just download and extract the new package and overwrite all your existing files. However, this might overwrite your config changes.
If you downloaded the binary tar package you can just download and extract a new package
and overwrite all your existing files. But this might overwrite your config changes. We
recommend you place your config changes in a file named `<grafana_install_dir>/conf/custom.ini`
as this will make upgrades easier without risking losing your config changes.
We recommend that you save your custom config changes in a file named `<grafana_install_dir>/conf/custom.ini`.
This allows you to upgrade Grafana without risking losing your configuration changes.
### Centos / RHEL
If you installed grafana by downloading a rpm package you can just follow the same installation guide
and execute the same `yum install` or `rpm -i` command but with the new package. It will upgrade your Grafana install.
If you installed Grafana by downloading an RPM package you can just follow the same installation guide and execute the same `yum install` or `rpm -i` command but with the new package. It will upgrade your Grafana installation.
If you used our YUM repository:
......@@ -101,10 +113,7 @@ docker run --name=my-grafana-container --restart=always -v /var/lib/grafana:/var
### Windows
If you downloaded the Windows binary package you can just download a newer package and extract
to the same location (and overwrite the existing files). This might overwrite your config changes. We
recommend you place your config changes in a file named `<grafana_install_dir>/conf/custom.ini`
as this will make upgrades easier without risking losing your config changes.
If you downloaded the Windows binary package you can just download a newer package and extract to the same location (and overwrite the existing files). This might overwrite your config changes. We recommend that you save your config changes in a file named `<grafana_install_dir>/conf/custom.ini` as this will make upgrades easier without risking losing your config changes.
## Upgrading from 1.x
......@@ -116,9 +125,7 @@ We are not aware of any issues upgrading directly from 2.x to 4.x but to be on t
## Upgrading to v5.0
The dashboard grid layout engine has changed. All dashboards will be automatically upgraded to new
positioning system when you load them in v5. Dashboards saved in v5 will not work in older versions of Grafana. Some
external panel plugins might need to be updated to work properly.
The dashboard grid layout engine has changed. All dashboards will be automatically upgraded to new positioning system when you load them in v5. Dashboards saved in v5 will not work in older versions of Grafana. Some external panel plugins might need to be updated to work properly.
For more details on the new panel positioning system, [click here]({{< relref "../reference/dashboard.md#panel-size-position" >}})
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment