docker.recipes

Directus

intermediate

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

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.

Key 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

Common Use Cases

  • 1Headless CMS for React, Vue, or Next.js applications requiring structured content management
  • 2Mobile app backend providing user authentication, data APIs, and admin dashboard in one platform
  • 3E-commerce product catalog management with complex attributes, variants, and inventory tracking
  • 4Multi-tenant SaaS applications needing per-client data isolation and custom field configurations
  • 5Digital asset management for marketing teams with approval workflows and brand asset libraries
  • 6IoT data collection platform with sensor data storage and real-time dashboard visualization
  • 7Customer 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

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  directus: 
3    image: directus/directus:latest
4    container_name: directus
5    restart: unless-stopped
6    environment: 
7      KEY: ${DIRECTUS_KEY}
8      SECRET: ${DIRECTUS_SECRET}
9      DB_CLIENT: pg
10      DB_HOST: postgres
11      DB_PORT: 5432
12      DB_DATABASE: ${DB_DATABASE}
13      DB_USER: ${DB_USER}
14      DB_PASSWORD: ${DB_PASSWORD}
15      ADMIN_EMAIL: ${ADMIN_EMAIL}
16      ADMIN_PASSWORD: ${ADMIN_PASSWORD}
17    volumes: 
18      - directus_uploads:/directus/uploads
19    ports: 
20      - "8055:8055"
21    depends_on: 
22      - postgres
23    networks: 
24      - directus-network
25
26  postgres: 
27    image: postgres:16-alpine
28    container_name: directus-postgres
29    environment: 
30      POSTGRES_DB: ${DB_DATABASE}
31      POSTGRES_USER: ${DB_USER}
32      POSTGRES_PASSWORD: ${DB_PASSWORD}
33    volumes: 
34      - postgres_data:/var/lib/postgresql/data
35    networks: 
36      - directus-network
37
38volumes: 
39  directus_uploads: 
40  postgres_data: 
41
42networks: 
43  directus-network: 
44    driver: bridge

.env Template

.env
1DIRECTUS_KEY=your-key-here
2DIRECTUS_SECRET=your-secret-here
3DB_DATABASE=directus
4DB_USER=directus
5DB_PASSWORD=changeme
6ADMIN_EMAIL=admin@example.com
7ADMIN_PASSWORD=changeme

Usage Notes

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

Individual Services(2 services)

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

directus
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
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

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  directus:
5    image: directus/directus:latest
6    container_name: directus
7    restart: unless-stopped
8    environment:
9      KEY: ${DIRECTUS_KEY}
10      SECRET: ${DIRECTUS_SECRET}
11      DB_CLIENT: pg
12      DB_HOST: postgres
13      DB_PORT: 5432
14      DB_DATABASE: ${DB_DATABASE}
15      DB_USER: ${DB_USER}
16      DB_PASSWORD: ${DB_PASSWORD}
17      ADMIN_EMAIL: ${ADMIN_EMAIL}
18      ADMIN_PASSWORD: ${ADMIN_PASSWORD}
19    volumes:
20      - directus_uploads:/directus/uploads
21    ports:
22      - "8055:8055"
23    depends_on:
24      - postgres
25    networks:
26      - directus-network
27
28  postgres:
29    image: postgres:16-alpine
30    container_name: directus-postgres
31    environment:
32      POSTGRES_DB: ${DB_DATABASE}
33      POSTGRES_USER: ${DB_USER}
34      POSTGRES_PASSWORD: ${DB_PASSWORD}
35    volumes:
36      - postgres_data:/var/lib/postgresql/data
37    networks:
38      - directus-network
39
40volumes:
41  directus_uploads:
42  postgres_data:
43
44networks:
45  directus-network:
46    driver: bridge
47EOF
48
49# 2. Create the .env file
50cat > .env << 'EOF'
51DIRECTUS_KEY=your-key-here
52DIRECTUS_SECRET=your-secret-here
53DB_DATABASE=directus
54DB_USER=directus
55DB_PASSWORD=changeme
56ADMIN_EMAIL=admin@example.com
57ADMIN_PASSWORD=changeme
58EOF
59
60# 3. Start the services
61docker compose up -d
62
63# 4. View logs
64docker compose logs -f

One-Liner

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

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

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

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

directuspostgres

Tags

#directus#headless#database#api

Category

CMS & Blogging

Related Recipes

Ad Space