How to install Grafana on Debian 12

This guide walks you through installing Grafana 11.x on a fresh Debian 12 Bookworm server. You will add the official repository, install the package, configure the web server, and start the monitoring service. The steps apply to Debian 12 with Apache or Nginx installed.

Prerequisites

• Debian 12 (Bookworm) running as root or via sudo.
• SSH access to your server.
• At least 500MB of free disk space.
• Internet connection to fetch repositories and packages.
• Web server installed (Apache or Nginx).

Step 1: Add the Grafana repository

You need to add the official Grafana APT repository to your system. This ensures you get the latest stable version and security updates.

apt update
apt install -y gnupg2 wget
wget -q -O - https://apt.grafana.com/gpg.key | gpg --dearmor -o /usr/share/keyrings/grafana.gpg
echo "deb [signed-by=/usr/share/keyrings/grafana.gpg] https://apt.grafana.com stable main" | tee -a /etc/apt/sources.list.d/grafana.list

Run the following command to update your package list after adding the new source:

apt update

You will see the list of available packages updated from the new repository.

Step 2: Install Grafana

Install the Grafana package using APT. The installer will download and configure the application automatically.

apt install -y grafana

During installation, you may see a prompt to create a default admin user. Accept the default password or set a custom one if prompted.

Setting up grafana (11.3.0-1~debian12~bullseye) ...
Created symlink /etc/systemd/system/multi-user.target.wants/grafana-server.service → /lib/systemd/system/grafana-server.service.

The service is created and enabled by default. The package version will be around 11.3.0 for Debian 12.

Step 3: Configure the web server

You must configure your web server to serve the Grafana application. The official package installs a systemd service that serves the web interface, but you need to ensure the web server is set up correctly for external access.

Configure Apache (if installed)

If you are using Apache, the package installs a configuration file at /etc/apache2/sites-enabled/grafana.conf. Verify the file exists and contains the correct proxy settings.

cat /etc/apache2/sites-enabled/grafana.conf

The file should contain a VirtualHost block listening on port 80 and proxying requests to the local Grafana service.

VirtualHost *:80
    ServerName your-domain.com
    ServerAdmin webmaster@localhost
    ProxyPreserveHost On
    ProxyPass / http://localhost:3000/
    ProxyPassReverse / http://localhost:3000/

Enable the site if it is not already enabled:

a2ensite grafana.conf
systemctl restart apache2

Configure Nginx (if installed)

If you are using Nginx, the package installs a configuration file at /etc/nginx/sites-enabled/grafana. Check that the file is present and correctly configured.

cat /etc/nginx/sites-enabled/grafana

The configuration should proxy requests to port 3000 and handle SSL if configured.

server {
    listen 80;
    server_name your-domain.com;
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Reload Nginx to apply changes:

systemctl reload nginx

Step 4: Start and enable the Grafana service

Start the Grafana service and enable it to start on boot. This ensures the monitoring dashboard is always available.

systemctl start grafana-server
systemctl enable grafana-server

Check the service status to confirm it is running without errors.

systemctl status grafana-server

The output should show "active (running)" and no recent errors in the journal.

Verify the installation

Open a web browser and navigate to http://your-server-ip. You should see the Grafana login page. Enter the default admin username and password you set during installation. If you did not change the password, the default is "admin" and a randomly generated password displayed during installation.

Once logged in, you can create a dashboard, add a data source, or view the default sample dashboards. The status bar in the bottom right corner should show "Connected" to the database.

Troubleshooting

If the service fails to start, check the logs for errors. The main log file is located at /var/log/grafana/grafana.log. Review the last few lines to identify issues.

tail -n 50 /var/log/grafana/grafana.log

Common issues include missing dependencies, incorrect web server configuration, or port conflicts. If the web server is not configured to proxy to port 3000, the browser will show a connection error or a 404 page.

Ensure the Grafana service is listening on port 3000. Check with netstat or ss:

ss -tlnp | grep 3000

If the port is not listed, the service may have failed to start. Restart the service and check the logs again.

systemctl restart grafana-server
systemctl status grafana-server

If you see permission errors, ensure the grafana user has read access to the configuration directory. Check ownership of /etc/grafana with ls -la.

Verify the web server configuration is correct by testing the connection manually. Use curl to test the proxy:

curl -I http://localhost:3000/api/health

A successful response includes a 200 status code. If you get a 404 or 502, the web server configuration is incorrect. Re-check the virtual host settings and ensure the proxy_pass directive points to the correct local address and port.

If you changed the admin password, ensure you use the new credentials to log in. The default password is only used once unless explicitly changed in the configuration file.

For advanced troubleshooting, enable verbose logging in /etc/grafana/grafana.ini by setting log_level to debug. Restart the service after making changes.

systemctl restart grafana-server

Review the logs again to find the specific error message. Common errors include database connection failures, which require checking the database service status and network connectivity.