How to Run Grafana Loki with Docker and Docker Compose (Step-by-Step)

Grafana Loki is a horizontally scalable log aggregation system inspired by Prometheus: it indexes only labels per log stream instead of full text, so it uses less storage and is easier to run—especially if you already use Prometheus or Kubernetes. Promtail ships log files to Loki; Grafana is the UI where you add Loki as a data source and query logs with LogQL. This guide walks you through running Grafana Loki, Promtail, and Grafana with Docker and Docker Compose for local or dev use, then querying logs in Grafana Explore.

In this guide you’ll:

Verify Docker and Docker Compose, then run Grafana in a container
Run Loki and Promtail with Docker using loki-config.yaml and promtail-config.yaml
Run the full stack with a single docker compose up -d
Add Loki as a Grafana data source and query system logs with LogQL in Explore

For production, use Loki in distributed mode with Helm or Tanka and persistent storage (e.g. S3, GCS).

Related guides:

Prerequisites: Docker and Docker Compose

You need Docker and Docker Compose installed. On Ubuntu, see How to install and use Docker in Ubuntu 22.04.

Confirm that Docker is working as expected:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
$ docker version

Client: Docker Engine - Community
 Version:           20.10.17
 API version:       1.41
 Go version:        go1.17.11
 Git commit:        100c701
 Built:             Mon Jun  6 23:02:46 2022
 OS/Arch:           linux/amd64
 Context:           default
 Experimental:      true

Server: Docker Engine - Community
 Engine:
  Version:          20.10.17
  API version:      1.41 (minimum version 1.12)
  Go version:       go1.17.11
  Git commit:       a89b842
  Built:            Mon Jun  6 23:00:51 2022
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          1.6.6
  GitCommit:        10c12954828e7c7c9b6e0ea9b0c02b01407d3ae1
 runc:
  Version:          1.1.2
  GitCommit:        v1.1.2-0-ga916309
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

Docker Compose is now included with Docker Desktop and is available on Linux as a Docker plugin. Confirm it’s available with:

1
docker compose version

Run Grafana in Docker

Grafana is an open source analytics and visualization platform. For this setup, Grafana is the UI for Loki: you’ll use it to add Loki as a data source, run LogQL queries in Explore, and build dashboards from your logs.

Run Grafana OSS in a container with:

1
2
3
docker run -d --name grafana \
  -p 3000:3000 \
  grafana/grafana-oss:9.0.2

The -d flag runs the container in the background. When it’s up, open Grafana at http://localhost:3000 (or http://your_server_ip:3000).

Run Loki with Docker

Loki is the log backend; Promtail is the agent that tails local log files and sends them to Loki. Together they give you log aggregation and search that fits well with Prometheus and Kubernetes.

First, create a working directory:

1
mkdir -p loki && cd loki

Next, create a configuration file required to start and run Loki. Save this as loki-config.yaml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
auth_enabled: false

server:
  http_listen_port: 3100
  grpc_listen_port: 9096

common:
  path_prefix: /loki
  storage:
    filesystem:
      chunks_directory: /loki/chunks
      rules_directory: /loki/rules
  replication_factor: 1
  ring:
    instance_addr: 127.0.0.1
    kvstore:
      store: inmemory

schema_config:
  configs:
    - from: 2020-10-24
      store: boltdb-shipper
      object_store: filesystem
      schema: v11
      index:
        prefix: index_
        period: 24h

ruler:
  alertmanager_url: http://localhost:9093

# If you would like to disable reporting, uncomment the following lines:
#analytics:
#  reporting_enabled: false

Now we can run our loki instance with this command:

1
2
3
4
5
6
7
8
docker network create grafana_loki || true

docker run -d --name loki \
  --network grafana_loki \
  -v "$(pwd)/loki-config.yaml":/etc/loki/config.yaml \
  -v loki_data:/loki \
  -p 3100:3100 \
  grafana/loki:2.5.0 -config.file=/etc/loki/config.yaml

Once Loki is running, run Promtail to ship logs from /var/log/*log to Loki. Create a file named promtail-config.yaml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
server:
  http_listen_port: 9080
  grpc_listen_port: 0

positions:
  filename: /positions/positions.yaml

clients:
  - url: http://loki:3100/loki/api/v1/push

scrape_configs:
  - job_name: system
    static_configs:
      - targets:
          - localhost
        labels:
          job: varlogs
          __path__: /var/log/*log

Start promtail with this command:

1
2
3
4
5
6
docker run -d --name promtail \
  --network grafana_loki \
  -v "$(pwd)/promtail-config.yaml":/etc/promtail/config.yml \
  -v /var/log:/var/log:ro \
  -v promtail_positions:/positions \
  grafana/promtail:2.5.0 -config.file=/etc/promtail/config.yml

When Loki and Promtail are running, check Loki’s metrics at http://localhost:3100/metrics and readiness at http://localhost:3100/ready.

Tip: Some Loki and Promtail images run as a non-root user. If bind mounts cause permission errors, fix directory permissions or run the container with --user 0 (root).

Run the full stack with Docker Compose

A Docker Compose file lets you start and manage Grafana, Loki, and Promtail with one command. Put the following in docker-compose.yaml in the same directory as your config files.

Add the following to a docker-compose.yaml file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
version: "3.9"
networks:
  grafana_loki:

volumes:
  loki_data:
  promtail_positions:
  grafana_data:

services:
  grafana:
    image: grafana/grafana-oss:9.0.2
    ports:
      - "3000:3000"
    volumes:
      - grafana_data:/var/lib/grafana
    networks:
      - grafana_loki

  loki:
    image: grafana/loki:2.5.0
    ports:
      - "3100:3100"
    volumes:
      - ./loki-config.yaml:/etc/loki/config.yaml
      - loki_data:/loki
    command: -config.file=/etc/loki/config.yaml
    networks:
      - grafana_loki

  promtail:
    image: grafana/promtail:2.5.0
    volumes:
      - /var/log:/var/log:ro
      - ./promtail-config.yaml:/etc/promtail/config.yml
      - promtail_positions:/positions
    command: -config.file=/etc/promtail/config.yml
    networks:
      - grafana_loki

From the directory that contains docker-compose.yaml and the config files, start everything with:

1
docker compose up -d

Grafana stays at port 3000, Loki at 3100. Use the same URLs as in the previous sections.

Add Loki as a data source and query logs

Log in to Grafana at http://localhost:3000 with the default user admin and password admin. Change the password when prompted.
Add Loki: Open the menu (Grafana icon) → Connections → Data sources → Add data source → Loki. Set URL to http://loki:3100 and click Save & test.
Query logs: Go to Explore, select Loki, then use the label browser to pick job → varlogs (for /var/log/*log). Run a query such as:

1
{job="varlogs"} | logfmt

To hide lines that fail logfmt parsing, add:

1
{job="varlogs"} | logfmt | __error__=""

You should see logs from your system streaming in.

Frequently Asked Questions (FAQ)

What is Grafana Loki?

Grafana Loki is a log aggregation system that indexes only label metadata for log streams (similar to how Prometheus indexes metrics), not full log content. That reduces storage and operational cost. You query logs with LogQL in Grafana after adding Loki as a data source.

What is Promtail?

Promtail is the log shipper for Loki. It discovers log files (e.g. under /var/log), adds labels, and pushes log lines to Loki. It plays a similar role to Fluentd or Filebeat for the Loki stack.

How do I run Loki with Docker Compose?

Create a docker-compose.yaml with services for grafana, loki, and promtail on a shared network. Mount loki-config.yaml and promtail-config.yaml, use named volumes for Loki and Promtail data, then run docker compose up -d. Loki listens on port 3100, Grafana on 3000.

Can I use this Loki Docker setup in production?

This guide uses single-binary Loki with filesystem storage and in-memory ring, which is suitable for local or dev. For production, run Loki in distributed mode with persistent object storage (S3, GCS) and deploy via Helm or Tanka.

What is LogQL?

LogQL is Loki’s query language (inspired by PromQL). In Grafana Explore with Loki selected, you use it to filter by labels (e.g. {job="varlogs"}) and optionally parse or filter log lines (e.g. | logfmt).

Conclusion

You ran Grafana, Loki, and Promtail with Docker and Docker Compose, added Loki as a Grafana data source, and queried system logs in Grafana Explore using LogQL. For next steps, add dashboards and alerts, or pair this stack with Prometheus in Docker for metrics and logs together.