# Craft CMS

> Flexible content management with custom fields and matrix blocks.

- Category: CMS & Blogging
- Difficulty: intermediate
- Components: craft, postgres, redis
- Tags: craft, php, flexible, custom-fields
- Source: https://docker.recipes/cms/craft-cms

## Overview

Craft CMS is a flexible, developer-friendly content management system built on the Yii PHP framework, designed to give content creators and developers unprecedented control over digital experiences. Unlike rigid, template-based CMS platforms, Craft focuses on structured content with custom fields, matrix blocks for complex layouts, and element relationships that make content truly reusable across different contexts. This stack combines Craft CMS with PostgreSQL and Redis to create a robust, scalable content platform that can handle everything from simple blogs to complex multi-site enterprise deployments.

This configuration leverages PostgreSQL's advanced JSON support and ACID compliance to store Craft's flexible content structures while maintaining data integrity across complex field relationships and matrix blocks. Redis provides high-performance session storage and caching, dramatically improving response times for content queries and reducing database load during traffic spikes. The combination allows Craft to scale beyond basic MySQL setups while providing enterprise-grade reliability.

This stack is ideal for agencies managing multiple client sites, content-heavy applications requiring custom field architectures, and developers who need a CMS that adapts to their data model rather than forcing predetermined structures. The PostgreSQL foundation makes it particularly valuable for applications requiring complex content relationships, multi-language support, or integration with existing enterprise PostgreSQL infrastructure.

## Features

- Matrix fields with PostgreSQL JSON storage for complex, nested content blocks
- Element relationship queries optimized by PostgreSQL's advanced indexing
- Redis-powered session management for improved multi-user editing performance
- Custom field types stored efficiently in PostgreSQL's flexible schema system
- Content localization using PostgreSQL's full-text search capabilities
- Redis caching for template rendering and database query optimization
- Asset transformation pipeline with metadata stored in PostgreSQL
- GraphQL API powered by PostgreSQL's JSON querying capabilities

## Use cases

- Multi-site agency platforms requiring shared content libraries and templates
- Enterprise content hubs with complex approval workflows and user permissions
- E-commerce sites needing flexible product catalogs with custom attributes
- News and publishing platforms with structured article relationships
- Portfolio websites requiring custom project categorization and filtering
- Corporate intranets with document management and employee directories
- Event management platforms with recurring schedules and venue relationships

## Prerequisites

- Docker and Docker Compose installed with minimum 2GB RAM available
- Composer installed locally for initial Craft project creation
- Basic understanding of Craft CMS field types and templating with Twig
- Environment variables configured: DB_PASSWORD and SECURITY_KEY
- Port 8080 available for web access
- PostgreSQL knowledge helpful for advanced content queries and optimization

## docker-compose.yml

```yaml
services:
  craft:
    image: craftcms/cli:latest
    container_name: craft
    restart: unless-stopped
    environment:
      CRAFT_DB_DRIVER: pgsql
      CRAFT_DB_SERVER: postgres
      CRAFT_DB_DATABASE: craft
      CRAFT_DB_USER: craft
      CRAFT_DB_PASSWORD: ${DB_PASSWORD}
      CRAFT_SECURITY_KEY: ${SECURITY_KEY}
    volumes:
      - ./craft:/app
    ports:
      - "8080:8080"
    depends_on:
      - postgres
      - redis
    networks:
      - craft-network

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

  redis:
    image: redis:alpine
    container_name: craft-redis
    networks:
      - craft-network

volumes:
  postgres_data:

networks:
  craft-network:
    driver: bridge
```

## .env

```bash
DB_PASSWORD=changeme
SECURITY_KEY=your-security-key
```

## Usage notes

- Docs: https://craftcms.com/docs/
- Create project first: composer create-project craftcms/craft
- Access at http://localhost:8080, admin at /admin
- Matrix fields: nested, repeatable content blocks
- Element types: entries, categories, users, assets, globals
- Free Solo license; Pro adds GraphQL, multi-site features

## Troubleshooting

- Craft installation error 'could not connect to database': Verify DB_PASSWORD matches in both craft and postgres services
- Matrix field data not saving: Check PostgreSQL max_allowed_packet size and JSON field limits in database configuration
- Session timeout issues during content editing: Ensure Redis container is running and accessible on craft-network
- Asset uploads failing: Verify ./craft directory permissions and volume mount is writable by container user
- GraphQL queries timing out: Enable PostgreSQL query optimization and add appropriate indexes for content relationships
- Craft security key errors: Ensure SECURITY_KEY environment variable is set and consistent across container restarts

