# Directus

> Open data platform for managing SQL databases with REST/GraphQL APIs.

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

## Overview

Directus is an open-source data platform that transforms any SQL database into a collaborative workspace with auto-generated REST and GraphQL APIs. Born from the need to bridge the gap between developers and non-technical users, Directus provides a visual Data Studio interface for content management while maintaining direct database access for developers. Unlike traditional headless CMS solutions that lock you into proprietary structures, Directus works as a wrapper around your existing database schema, making it database-agnostic and migration-friendly.

This stack combines Directus with PostgreSQL to create a powerful headless CMS and API backend. PostgreSQL's advanced JSON support, ACID compliance, and extensibility complement Directus's schema introspection capabilities, enabling complex relational data models with document-style flexibility. The combination excels at handling structured content with relationships, user permissions, and real-time collaboration while maintaining data integrity through PostgreSQL's robust transaction system.

This setup targets development teams building modern web applications, mobile backends, or multi-channel content systems who need both developer-friendly APIs and content editor interfaces. Startups benefit from rapid prototyping capabilities, while enterprises appreciate the granular permissions, audit logging, and ability to integrate with existing PostgreSQL infrastructure without vendor lock-in.

## Features

- Auto-generated REST and GraphQL APIs that reflect your PostgreSQL schema changes in real-time
- Visual Data Studio with drag-and-drop interface for managing database collections, fields, and relationships
- Flows automation system with triggers, operations, and webhooks for custom business logic
- Granular role-based permissions with field-level access control and custom validation rules
- Multi-factor authentication with SSO support including LDAP, OAuth, and SAML integrations
- Real-time collaboration with WebSocket connections for live data updates across clients
- PostgreSQL JSON/JSONB field support for flexible document storage within relational structure
- Asset management with image transformations, file versioning, and CDN integration capabilities

## Use cases

- Headless CMS for React, Vue, or Next.js applications requiring structured content management
- Mobile app backend providing user authentication, data APIs, and admin dashboard in one platform
- E-commerce product catalog management with complex attributes, variants, and inventory tracking
- Multi-tenant SaaS applications needing per-client data isolation and custom field configurations
- Digital asset management for marketing teams with approval workflows and brand asset libraries
- IoT data collection platform with sensor data storage and real-time dashboard visualization
- Customer portal development with user-generated content, file uploads, and permission-based access

## Prerequisites

- Docker and Docker Compose installed with minimum 2GB available RAM for PostgreSQL operations
- Port 8055 available for Directus web interface and API endpoints
- Basic understanding of relational database concepts and SQL for schema design
- Environment variables configured including generated 32-character KEY and SECRET values
- Knowledge of REST/GraphQL APIs for frontend integration and data consumption
- Understanding of PostgreSQL connection limits and performance tuning for production deployments

## docker-compose.yml

```yaml
services:
  directus:
    image: directus/directus:latest
    container_name: directus
    restart: unless-stopped
    environment:
      KEY: ${DIRECTUS_KEY}
      SECRET: ${DIRECTUS_SECRET}
      DB_CLIENT: pg
      DB_HOST: postgres
      DB_PORT: 5432
      DB_DATABASE: ${DB_DATABASE}
      DB_USER: ${DB_USER}
      DB_PASSWORD: ${DB_PASSWORD}
      ADMIN_EMAIL: ${ADMIN_EMAIL}
      ADMIN_PASSWORD: ${ADMIN_PASSWORD}
    volumes:
      - directus_uploads:/directus/uploads
    ports:
      - "8055:8055"
    depends_on:
      - postgres
    networks:
      - directus-network

  postgres:
    image: postgres:16-alpine
    container_name: directus-postgres
    environment:
      POSTGRES_DB: ${DB_DATABASE}
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - directus-network

volumes:
  directus_uploads:
  postgres_data:

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

## .env

```bash
DIRECTUS_KEY=your-key-here
DIRECTUS_SECRET=your-secret-here
DB_DATABASE=directus
DB_USER=directus
DB_PASSWORD=changeme
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=changeme
```

## Usage notes

- Docs: https://docs.directus.io/
- Access at http://localhost:8055 - login with ADMIN_EMAIL/ADMIN_PASSWORD
- Auto-generates REST and GraphQL APIs from any SQL database schema
- Data Studio: visual interface for managing collections and fields
- Flows: built-in automation with triggers, operations, and webhooks
- Generate KEY and SECRET with: openssl rand -hex 32

## Troubleshooting

- Directus container exits with 'Invalid KEY or SECRET': Generate new 32-character hex values using openssl rand -hex 32
- Database connection refused errors: Verify postgres container is running and DB_HOST matches service name in docker-compose
- Admin login fails after setup: Check ADMIN_EMAIL format is valid and ADMIN_PASSWORD meets minimum requirements
- File uploads return 413 errors: Configure reverse proxy client_max_body_size or adjust Directus UPLOAD_MAX_SIZE environment variable
- GraphQL queries timeout on large datasets: Optimize PostgreSQL queries with indexes and consider implementing pagination limits
- Directus shows 'Database Connection Error' on startup: Ensure PostgreSQL container fully initializes before Directus starts using healthcheck dependencies

