Cortex

Key Features

• Multi-tenant metrics ingestion with X-Scope-OrgID header-based tenant isolation
• Prometheus remote_write compatibility for direct integration with existing Prometheus deployments
• Consul-based service discovery enabling automatic cluster member coordination and health monitoring
• Horizontal scalability through Cortex's microservices architecture running in single-process mode
• Long-term metrics storage with configurable retention policies and downsampling
• Complete Prometheus Query API compatibility for integration with Grafana and other visualization tools
• Built-in load balancing and high availability through Consul's distributed consensus
• Configurable ingestion limits and rate limiting per tenant for resource protection

Common Use Cases

• 1Centralized metrics storage for multiple Kubernetes clusters each running Prometheus
• 2Multi-tenant SaaS platforms requiring isolated metrics collection per customer organization
• 3Enterprise monitoring consolidation where different teams need separate metric namespaces
• 4Long-term metrics retention beyond single Prometheus instance storage limitations
• 5High-availability Prometheus replacement for mission-critical monitoring infrastructure
• 6Development and staging environment metrics aggregation with production data separation
• 7Managed service providers offering Prometheus-as-a-Service to multiple clients

Prerequisites

• Minimum 1GB RAM available (512MB for Cortex + 256MB for Consul + system overhead)
• Docker host with ports 8500 and 9009 available for Consul UI and Cortex API access
• Valid cortex/config.yaml file configured with storage backend and cluster settings
• Understanding of Prometheus remote_write configuration for metric forwarding
• Familiarity with multi-tenant concepts and HTTP header-based tenant routing
• Basic knowledge of YAML configuration for Cortex microservices tuning

docker-compose.yml

1services: 
2  consul: 
3    image: consul:latest
4    container_name: consul
5    ports: 
6      - "8500:8500"
7    networks: 
8      - cortex-network
9
10  cortex: 
11    image: cortexproject/cortex:latest
12    container_name: cortex
13    command: 
14      - -config.file=/etc/cortex/config.yaml
15    volumes: 
16      - ./cortex/config.yaml:/etc/cortex/config.yaml:ro
17      - cortex_data:/data
18    ports: 
19      - "9009:9009"
20    depends_on: 
21      - consul
22    networks: 
23      - cortex-network
24
25volumes: 
26  cortex_data: 
27
28networks: 
29  cortex-network: 
30    driver: bridge

.env Template

1# Cortex configuration file required

Usage Notes

Individual Services(2 services)

Copy individual services to mix and match with your existing compose files.

consul:
  image: consul:latest
  container_name: consul
  ports:
    - "8500:8500"
  networks:
    - cortex-network

cortex:
  image: cortexproject/cortex:latest
  container_name: cortex
  command:
    - "-config.file=/etc/cortex/config.yaml"
  volumes:
    - ./cortex/config.yaml:/etc/cortex/config.yaml:ro
    - cortex_data:/data
  ports:
    - "9009:9009"
  depends_on:
    - consul
  networks:
    - cortex-network

Quick Start

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  consul:
5    image: consul:latest
6    container_name: consul
7    ports:
8      - "8500:8500"
9    networks:
10      - cortex-network
11
12  cortex:
13    image: cortexproject/cortex:latest
14    container_name: cortex
15    command:
16      - -config.file=/etc/cortex/config.yaml
17    volumes:
18      - ./cortex/config.yaml:/etc/cortex/config.yaml:ro
19      - cortex_data:/data
20    ports:
21      - "9009:9009"
22    depends_on:
23      - consul
24    networks:
25      - cortex-network
26
27volumes:
28  cortex_data:
29
30networks:
31  cortex-network:
32    driver: bridge
33EOF
34
35# 2. Create the .env file
36cat > .env << 'EOF'
37# Cortex configuration file required
38EOF
39
40# 3. Start the services
41docker compose up -d
42
43# 4. View logs
44docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

1curl -fsSL https://docker.recipes/api/recipes/cortex/run | bash

Troubleshooting