Deploying Prometheus with Docker Compose: A Step-by-Step Guide

Prometheus is one of the most popular open-source monitoring and alerting tools. Setting up Prometheus with Docker Compose can make your monitoring stack easier to deploy and manage if you're running containerized applications.

This guide will walk you through everything you need to get Prometheus up and running with Docker Compose, from installation to configuration and setting up basic alerts.

Why Use Docker Compose for Prometheus?

Running Prometheus as a standalone service is fine, but Docker Compose lets you define and run multi-container applications effortlessly. With a single docker-compose.yml file, you can manage Prometheus along with related services like Grafana and Alertmanager.

Benefits:

• Simplifies setup: No need to install Prometheus manually.
• Easy scaling: Add exporters or monitoring services with minimal effort.
• Better maintainability: Configuration is stored in version-controlled YAML files.

How to Start Working with Prometheus

Once Prometheus is deployed, you can start using it to monitor your infrastructure effectively. This guide will walk you through the basics, ensuring even beginners can get started with ease.

1. Accessing the Prometheus Web UI

After starting Prometheus, open your browser and go to http://localhost:9090. This is the Prometheus interface, where you can:

• Explore available metrics
• Run queries
• Check the current status of your monitoring setup

2. Running PromQL Queries to Analyze Data

Prometheus uses PromQL (Prometheus Query Language) to filter and analyze metrics. Here’s how to get started:

• Open the “Graph” tab in the UI.
• Enter a basic query like up, which shows whether your monitored services are running.
• Click Execute to see results, and switch to the Graph tab for a visual representation.

3. Configuring New Targets for Monitoring

Prometheus gathers data from exporters and monitors services. To add more:

• Open the prometheus.yml file in your project folder.
• Locate the scrape_configs section and add new targets:

scrape_configs:
  - job_name: 'node_exporter'
    static_configs:
      - targets: ['localhost:9100']

• Restart Prometheus to apply changes.

4. Setting Up Alerts for Critical Events

Prometheus allows you to set alerts that notify you when conditions are met. To create a simple alert:

• In prometheus.yml, add:

alerting:
  alertmanagers:
    - static_configs:
        - targets: ['localhost:9093']
rule_files:
  - "alert.rules"

• Create an alert.rules file and define a rule, such as notifying when a service is down:

groups:
  - name: example_alert
    rules:
      - alert: InstanceDown
        expr: up == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "Instance {{ $labels.instance }} is down"

• Restart Prometheus to activate alerts.

5. Visualizing Metrics in Grafana

Grafana provides user-friendly dashboards for Prometheus data. To set it up:

• Install Grafana and access its UI (default: http://localhost:3000).
• Add a new data source, selecting Prometheus and setting the URL to http://prometheus:9090.
• Import community dashboards or create custom ones to visualize your metrics.

With these steps, you can efficiently start working with Prometheus and expand its capabilities over time!

3 Essential Configuration Components for Prometheus Setup

To run Prometheus effectively, you need to configure three key files that define its monitoring behavior, alerting rules, and service orchestration.

These components help fine-tune your monitoring setup for reliability, scalability, and efficient alert management.

1. prometheus.yml – Core Prometheus Configuration

The prometheus.yml file is the heart of Prometheus, defining how it scrapes metrics, applies alerting rules, and sets global parameters.

Key Configurations in prometheus.yml:

• Scrape Configuration: Defines which targets (applications, exporters, or services) Prometheus should monitor.

scrape_configs:
  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']

• Global Settings: Controls how frequently Prometheus scrapes data.

global:
  scrape_interval: 15s

• Alerting Rules: Specifies when an alert should be triggered based on PromQL expressions.

This file ensures Prometheus collects the right data at the right frequency, providing a solid foundation for monitoring.

2. docker-compose.yml – Managing Services with Docker Compose

Docker Compose simplifies deployment by defining all necessary services, networking, and persistent storage in a single docker-compose.yml file.

Key Configurations in docker-compose.yml:

• Prometheus Service

services:
  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    restart: unless-stopped
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

• Additional Services: You can add Node Exporter, Grafana, and Alertmanager to the same file, making it easy to manage all components.

Using Docker Compose ensures all services run consistently and simplifies deployment, scaling, and maintenance.

3. alertmanager.yml – Alert Routing and Notification Management

Alertmanager is responsible for processing alerts generated by Prometheus and sending them to configured receivers (e.g., Slack, email, PagerDuty).

Key Configurations in alertmanager.yml:

• Route Configuration: Defines how alerts should be handled.

route:
  receiver: 'email-notifications'

• Receiver Details: Specifies where alerts should be sent.

receivers:
  - name: 'email-notifications'
    email_configs:
      - to: 'your-email@example.com'
        from: 'alertmanager@example.com'
        smarthost: 'smtp.example.com:587'
        auth_username: 'user'
        auth_password: 'password'

This configuration ensures that when a critical condition is met, notifications are delivered promptly to the right channels.

7-Step Process to Use Docker Compose with Prometheus

Step 1: Install Docker and Docker Compose

Before we begin, ensure you have Docker and Docker Compose installed on your machine. You can check this by running:

docker -v

docker-compose -v

If not installed, refer to the official Docker documentation for your OS: Docker Installation Guide

Step 2: Create a docker-compose.yml File

Start by creating a directory for Prometheus:

mkdir prometheus && cd prometheus

Then, create a docker-compose.yml file inside the directory:

version: '3.8'
services:
  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    restart: unless-stopped
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

This file pulls the latest Prometheus image and maps port 9090, which is Prometheus’ default UI and API port.

Step 3: Configure Prometheus for Monitoring

Now, create a prometheus.yml file in the same directory:

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']

This basic configuration tells Prometheus to scrape itself every 15 seconds.

Step 4: Start and Run Prometheus with Docker Compose

Run the following command inside the prometheus directory:

docker-compose up -d

This will start Prometheus in detached mode. To check if it's running:

docker ps

You should see a running Prometheus container.

Now, open http://localhost:9090 in your browser to access the Prometheus UI.

Step 5: Add Node Exporter for System Metrics

To monitor your host system, you'll need Node Exporter. Add this service to your docker-compose.yml:

node-exporter:
    image: prom/node-exporter:latest
    container_name: node-exporter
    restart: unless-stopped
    ports:
      - "9100:9100"

Then, update prometheus.yml to include Node Exporter:

- job_name: 'node_exporter'
    static_configs:
      - targets: ['node-exporter:9100']

Restart the stack:

docker-compose down && docker-compose up -d

Now, Prometheus will scrape Node Exporter metrics as well.

Step 6: Integrate Grafana for Visualization

Grafana is the go-to tool for visualizing Prometheus metrics. Add this to docker-compose.yml:

grafana:
    image: grafana/grafana:latest
    container_name: grafana
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - grafana-storage:/var/lib/grafana
volumes:
  grafana-storage:

Start the updated stack:

docker-compose up -d

Access Grafana at http://localhost:3000, default login: admin/admin.

Step 7: Set Up Alerts with Alertmanager

For alerts, add Alertmanager to docker-compose.yml:

alertmanager:
    image: prom/alertmanager:latest
    container_name: alertmanager
    restart: unless-stopped
    ports:
      - "9093:9093"
    volumes:
      - ./alertmanager.yml:/etc/alertmanager/alertmanager.yml

Create alertmanager.yml:

route:
  receiver: 'default'
receivers:
  - name: 'default'
    email_configs:
      - to: 'your-email@example.com'
        from: 'alert@example.com'
        smarthost: 'smtp.example.com:587'
        auth_username: 'your-email@example.com'
        auth_password: 'your-password'

Update prometheus.yml to use Alertmanager:

alerting:
  alertmanagers:
    - static_configs:
        - targets: ['alertmanager:9093']

Restart everything:

docker-compose down && docker-compose up -d

Wrapping Up

You now have a complete monitoring stack with Prometheus, Node Exporter, Grafana, and Alertmanager running in Docker Compose. From here, you can:

• Add more exporters (like MySQL or Redis exporters)
• Set up advanced alerting rules
• Customize Grafana dashboards

This setup gives you flexibility and scalability while keeping things manageable.