# Directus Headless CMS

> Directus data platform with PostgreSQL and Redis.

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

## Overview

Directus is a modern, open-source headless CMS and data platform that automatically generates REST and GraphQL APIs from your database schema. Founded in 2004 and completely rebuilt in 2019, Directus acts as a wrapper around SQL databases, providing a powerful admin interface, user management, and API layer without vendor lock-in. Unlike traditional CMSs that force content into predefined structures, Directus works with your existing database or creates new schemas dynamically, making it ideal for developers who need database flexibility with content management convenience.

This stack combines Directus with PostgreSQL as the primary database and Redis for caching and session management. PostgreSQL provides ACID compliance, complex querying capabilities, and JSON support that complements Directus's flexible content modeling, while Redis accelerates response times by caching frequently accessed data and managing user sessions. The combination delivers enterprise-grade performance with the ability to handle both structured relational data and flexible document-style content through PostgreSQL's JSONB support.

This configuration is perfect for development teams building headless applications, agencies managing multiple client projects, and organizations migrating from legacy CMSs while maintaining database control. The stack scales from prototype to production, supporting complex content relationships, multi-user collaboration, and API-first architectures that power modern web applications, mobile apps, and IoT dashboards.

## Features

- Auto-generated REST and GraphQL APIs from PostgreSQL schema changes with real-time updates
- Advanced content modeling with PostgreSQL's JSONB support for flexible field types and nested data structures
- Redis-powered caching system that dramatically improves API response times and reduces database load
- Role-based permissions with granular field-level access control tied to PostgreSQL user management
- Real-time collaboration features using Redis pub/sub for live content editing and user presence indicators
- PostgreSQL full-text search integration with ranking and highlighting for advanced content discovery
- File asset management with automatic image transformations and PostgreSQL metadata indexing
- Webhook system for triggering external integrations when content changes in PostgreSQL tables

## Use cases

- Headless e-commerce platforms requiring complex product catalogs with PostgreSQL's advanced querying for inventory management
- Multi-tenant SaaS applications where each client needs isolated content management with shared infrastructure
- News and publishing platforms leveraging PostgreSQL's full-text search and Redis caching for high-traffic article delivery
- Mobile app backends requiring real-time content updates through Directus APIs with Redis session management
- Digital asset management systems for marketing teams with PostgreSQL's robust file metadata indexing
- IoT data dashboards where Directus provides user-friendly interfaces for PostgreSQL time-series data visualization
- Agency portfolio sites managing multiple client projects with Directus's flexible content modeling and user permissions

## Prerequisites

- Docker Engine 20.10+ and Docker Compose V2 for container orchestration support
- Minimum 2GB RAM (PostgreSQL needs 1GB+, Redis 512MB+, Directus 512MB+) for stable operation
- Port 8055 available for Directus admin interface and API endpoints
- Basic understanding of PostgreSQL schema design for effective content modeling in Directus
- Generated secure random values for KEY and SECRET environment variables (minimum 32 characters each)
- Valid email configuration if using Directus email features for user invitations and password resets

## docker-compose.yml

```yaml
services:
  postgres:
    image: postgres:16-alpine
    container_name: directus-postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-directus}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-directus}
      POSTGRES_DB: ${POSTGRES_DB:-directus}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - directus-network

  redis:
    image: redis:alpine
    container_name: directus-redis
    restart: unless-stopped
    volumes:
      - redis_data:/data
    networks:
      - directus-network

  directus:
    image: directus/directus:latest
    container_name: directus
    restart: unless-stopped
    ports:
      - "${DIRECTUS_PORT:-8055}:8055"
    environment:
      KEY: ${KEY:-replace-with-random-value}
      SECRET: ${SECRET:-replace-with-random-value}
      DB_CLIENT: pg
      DB_HOST: postgres
      DB_PORT: 5432
      DB_DATABASE: ${POSTGRES_DB:-directus}
      DB_USER: ${POSTGRES_USER:-directus}
      DB_PASSWORD: ${POSTGRES_PASSWORD:-directus}
      CACHE_ENABLED: "true"
      CACHE_STORE: redis
      REDIS: redis://redis:6379
      ADMIN_EMAIL: ${ADMIN_EMAIL:-admin@example.com}
      ADMIN_PASSWORD: ${ADMIN_PASSWORD:-admin123}
    volumes:
      - directus_uploads:/directus/uploads
    depends_on:
      - postgres
      - redis
    networks:
      - directus-network

volumes:
  postgres_data:
  redis_data:
  directus_uploads:

networks:
  directus-network:
    driver: bridge
```

## .env

```bash
# Directus
DIRECTUS_PORT=8055
KEY=your-random-key-here
SECRET=your-random-secret-here
POSTGRES_USER=directus
POSTGRES_PASSWORD=directus
POSTGRES_DB=directus
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=admin123
```

## Usage notes

- Directus at http://localhost:8055
- Login with admin credentials
- Generate random KEY and SECRET
- Access API at /items/{collection}

## Troubleshooting

- Directus shows 'Database connection failed': Check PostgreSQL container logs and verify POSTGRES_PASSWORD matches DB_PASSWORD in environment variables
- API responses are slow despite Redis setup: Verify CACHE_ENABLED is 'true' and check Redis container connectivity with docker exec directus-redis redis-cli ping
- Admin login fails with 'Invalid credentials': Reset admin password by setting new ADMIN_PASSWORD and restarting Directus container to recreate admin user
- File uploads return 500 errors: Ensure directus_uploads volume has proper write permissions and check available disk space on Docker host
- PostgreSQL container fails to start with 'data directory not empty': Remove postgres_data volume or check for conflicting PostgreSQL instances on port 5432
- Directus shows 'Invalid key/secret' errors: Generate cryptographically secure random strings for KEY and SECRET environment variables using openssl rand -hex 32

