Grafana Docker Setup

Docker packages software and everything it needs into a single unit called a container. Running Grafana in a container takes one command, works the same on every computer, and leaves your system clean. Developers love this method because they can start, stop, and delete a full Grafana server in seconds.

The Shipping Container Analogy

Global shipping uses standard steel containers. Cranes, trucks, and ships handle every container the same way, no matter what sits inside. A Docker container follows the same idea. Your laptop, a test server, and a cloud machine all run the Grafana container in an identical way.

+---------------- Your Computer ----------------+
|                                               |
|   Port 3000  <---->   +-------------------+   |
|   (browser)           |  Grafana          |   |
|                       |  Container        |   |
|                       +---------+---------+   |
|                                 |             |
|                         +-------v-------+     |
|                         | Volume        |     |
|                         | (saved data)  |     |
|                         +---------------+     |
+-----------------------------------------------+

Run Grafana With One Command

Install Docker Desktop or Docker Engine, open a terminal, and run the command below.

docker run -d -p 3000:3000 --name=grafana grafana/grafana-oss

Each part of the command has a job.

• -d runs the container in the background.
• -p 3000:3000 connects port 3000 on your computer to port 3000 inside the container.
• --name=grafana gives the container a friendly name.
• grafana/grafana-oss names the official open-source image.

Open http://localhost:3000 in a browser. The default username is admin and the default password is admin. Grafana asks you to set a new password at the first login. Choose a strong one.

Keep Your Data With a Volume

A container forgets everything when you delete it. Volumes solve that problem. A volume is a storage area that lives outside the container and survives restarts and upgrades.

docker volume create grafana-storage

docker run -d -p 3000:3000 --name=grafana \
  -v grafana-storage:/var/lib/grafana \
  grafana/grafana-oss

Grafana saves dashboards, users, and settings inside /var/lib/grafana. The volume keeps that folder safe.

Set Options With Environment Variables

Any Grafana setting accepts an environment variable that starts with GF_. The pattern is GF_ followed by the section name, an underscore, and the setting name.

docker run -d -p 3000:3000 --name=grafana \
  -e "GF_SECURITY_ADMIN_PASSWORD=ChooseAStrongPassword" \
  -e "GF_USERS_ALLOW_SIGN_UP=false" \
  -v grafana-storage:/var/lib/grafana \
  grafana/grafana-oss

Run Grafana and Prometheus Together

Docker Compose describes several containers in one file. The file below starts Grafana and Prometheus side by side, so you have a data source ready to connect.

services:
  prometheus:
    image: prom/prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

  grafana:
    image: grafana/grafana-oss
    ports:
      - "3000:3000"
    volumes:
      - grafana-storage:/var/lib/grafana
    depends_on:
      - prometheus

volumes:
  grafana-storage:

Save the file as docker-compose.yml and run docker compose up -d. Both containers share a private network. Inside Grafana, add a Prometheus data source with the address http://prometheus:9090. The service name acts as the host name.

Daily Commands

Task	Command
See running containers	docker ps
Read the logs	docker logs grafana
Stop Grafana	docker stop grafana
Start Grafana	docker start grafana
Delete the container	docker rm -f grafana
Download the newest image	docker pull grafana/grafana-oss

Upgrade Safely

Pull the newest image, remove the old container, and start a new one with the same volume. Grafana reads your saved data and migrates it to the new version automatically. Back up the volume before a major version jump.

Common Problems

Port 3000 Is Busy

Another program already uses the port. Change the left number in the mapping to -p 3001:3000 and open port 3001 in the browser.

Data Source Connection Fails

Inside a container, the word localhost points to the container itself. Use the service name from your Compose file, or the host machine address, to reach other systems.

Dashboards Vanish After a Restart

The container ran without a volume. Recreate it with a volume mounted at /var/lib/grafana.