# Directus Headless CMS Stack

> Open-source headless CMS with PostgreSQL, Redis caching, S3 storage, and full-text search.

- Category: CMS & Blogging
- Difficulty: intermediate
- Components: directus, postgresql, redis, minio, meilisearch
- Tags: directus, headless-cms, api-first, postgresql, meilisearch
- Source: https://docker.recipes/cms/directus-advanced

## Overview

Directus is an open-source headless CMS that transforms any SQL database into a powerful API and elegant admin interface. Founded in 2004 and rebuilt from the ground up in 2018, Directus follows an API-first approach that wraps your database with RESTful and GraphQL endpoints while maintaining complete data portability. Unlike traditional CMSes that lock you into proprietary formats, Directus works directly with your existing database schema. This stack combines Directus with PostgreSQL for robust relational data storage, Redis for high-performance caching and session management, MinIO for S3-compatible object storage, and Meilisearch for lightning-fast search capabilities. Together, these components create a production-ready content management platform that can handle everything from simple blogs to complex enterprise applications with media-rich content and advanced search requirements. This configuration is ideal for developers building modern web applications, mobile apps, or IoT platforms that need flexible content management without the constraints of traditional monolithic CMSes, offering the scalability of microservices with the convenience of integrated tooling.

## Features

- Dynamic API generation with RESTful and GraphQL endpoints auto-created from PostgreSQL schema
- PostgreSQL JSONB support for flexible schema evolution alongside relational data structures
- Redis-powered session management and query result caching for sub-100ms response times
- MinIO S3-compatible storage with automatic image transformations and CDN-style asset delivery
- Meilisearch integration for typo-tolerant full-text search with instant results under 50ms
- Role-based access control with granular field-level permissions and API key management
- Real-time collaboration with WebSocket connections for live content editing
- Database introspection that automatically generates admin interfaces from existing schemas

## Use cases

- E-commerce platforms requiring product catalogs with search, media management, and inventory tracking
- Multi-tenant SaaS applications needing per-client content management and API endpoints
- Mobile app backends with user-generated content, file uploads, and push notification management
- Documentation websites with search functionality and collaborative editing workflows
- Digital asset management systems for marketing teams with approval workflows and media transformations
- IoT dashboards collecting sensor data with real-time visualization and historical analysis
- Multi-language websites requiring translation management and localized content delivery

## Prerequisites

- Minimum 4GB RAM (2GB for PostgreSQL + Directus, 512MB each for Redis/MinIO/Meilisearch)
- Docker Engine 20.10+ with Docker Compose V2 for proper health check and dependency support
- Available ports 8055 (Directus), 9000-9001 (MinIO), and 7700 (Meilisearch) on your host system
- Basic understanding of PostgreSQL schema design and SQL queries for data modeling
- Familiarity with REST/GraphQL APIs and JSON data structures for frontend integration
- SSL certificate and reverse proxy knowledge for production HTTPS deployment

## docker-compose.yml

```yaml
services:
  directus:
    image: directus/directus:latest
    ports:
      - "8055:8055"
    environment:
      KEY: ${DIRECTUS_KEY}
      SECRET: ${DIRECTUS_SECRET}
      DB_CLIENT: pg
      DB_HOST: postgres
      DB_PORT: 5432
      DB_DATABASE: ${POSTGRES_DB}
      DB_USER: ${POSTGRES_USER}
      DB_PASSWORD: ${POSTGRES_PASSWORD}
      CACHE_ENABLED: "true"
      CACHE_STORE: redis
      REDIS_HOST: redis
      REDIS_PORT: 6379
      STORAGE_LOCATIONS: s3
      STORAGE_S3_DRIVER: s3
      STORAGE_S3_KEY: ${MINIO_ACCESS_KEY}
      STORAGE_S3_SECRET: ${MINIO_SECRET_KEY}
      STORAGE_S3_BUCKET: directus
      STORAGE_S3_ENDPOINT: http://minio:9000
      STORAGE_S3_FORCE_PATH_STYLE: "true"
      ADMIN_EMAIL: ${ADMIN_EMAIL}
      ADMIN_PASSWORD: ${ADMIN_PASSWORD}
    volumes:
      - directus_uploads:/directus/uploads
      - directus_extensions:/directus/extensions
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_started
      minio:
        condition: service_started
    networks:
      - directus-net
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - directus-net
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    networks:
      - directus-net
    restart: unless-stopped

  minio:
    image: minio/minio:latest
    ports:
      - "9000:9000"
      - "9001:9001"
    environment:
      MINIO_ROOT_USER: ${MINIO_ACCESS_KEY}
      MINIO_ROOT_PASSWORD: ${MINIO_SECRET_KEY}
    volumes:
      - minio_data:/data
    command: server /data --console-address ":9001"
    networks:
      - directus-net
    restart: unless-stopped

  meilisearch:
    image: getmeili/meilisearch:latest
    ports:
      - "7700:7700"
    environment:
      MEILI_MASTER_KEY: ${MEILI_MASTER_KEY}
    volumes:
      - meili_data:/meili_data
    networks:
      - directus-net
    restart: unless-stopped

volumes:
  directus_uploads:
  directus_extensions:
  postgres_data:
  redis_data:
  minio_data:
  meili_data:

networks:
  directus-net:
    driver: bridge
```

## .env

```bash
# Directus Configuration
DIRECTUS_KEY=random-key-here
DIRECTUS_SECRET=random-secret-here
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=secure_admin_password

# PostgreSQL
POSTGRES_USER=directus
POSTGRES_PASSWORD=secure_postgres_password
POSTGRES_DB=directus

# MinIO
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=secure_minio_password

# Meilisearch
MEILI_MASTER_KEY=secure_meili_master_key
```

## Usage notes

- Directus Admin at http://localhost:8055
- MinIO Console at http://localhost:9001
- Meilisearch at http://localhost:7700
- Configure Meilisearch extension in Directus for search

## Troubleshooting

- Directus fails to start with 'Database connection failed': Ensure PostgreSQL health check passes before Directus startup using depends_on conditions
- File uploads return 500 errors: Verify MinIO bucket 'directus' exists and STORAGE_S3_FORCE_PATH_STYLE is set to true for local MinIO
- Search queries return empty results: Install and configure Directus Meilisearch extension, then sync your collections to create search indexes
- Redis connection timeouts during high load: Increase Redis memory limit and enable AOF persistence to prevent data loss during restarts
- PostgreSQL crashes with 'out of memory': Tune shared_buffers and effective_cache_size in postgresql.conf based on available system RAM
- MinIO console shows 'InvalidAccessKeyId': Ensure MINIO_ROOT_USER matches STORAGE_S3_KEY and both are at least 3 characters long

