# Caisy

> High-performance headless CMS with visual editor.

- Category: CMS & Blogging
- Difficulty: beginner
- Components: caisy
- Tags: caisy, headless, visual-editor, graphql
- Source: https://docker.recipes/cms/contentful-like-caisy

## Overview

Caisy is a modern headless content management system built for performance and developer experience, featuring a visual editor that empowers content creators while delivering content through a high-performance GraphQL API. Founded as a German-based SaaS platform, Caisy distinguishes itself from traditional CMSs by combining intuitive visual content modeling with robust API-first architecture, making it particularly valuable for teams building modern web applications, mobile apps, and multi-channel digital experiences. This Docker configuration creates a local development environment by pairing Caisy with PostgreSQL 16, enabling developers to work with Caisy's content modeling and GraphQL capabilities locally before deploying to production. The stack combines Caisy's visual editor and content delivery engine with PostgreSQL's proven reliability for content storage, creating an environment where content teams can model complex content structures visually while developers consume that content through Caisy's optimized GraphQL endpoints. This setup is ideal for development teams working on headless projects who need local access to Caisy's features, agencies prototyping client projects, or organizations evaluating Caisy's capabilities before committing to the hosted service.

## Features

- Visual content modeling interface for creating custom content types without code
- High-performance GraphQL API with automatic query optimization and caching
- Built-in asset management with automatic image optimization and WebP conversion
- Multi-language content support with translation workflows
- Real-time collaborative editing with conflict resolution
- Component-based content architecture for reusable content blocks
- Advanced content relationships and reference management
- Webhook support for triggering builds and integrations on content changes

## Use cases

- Developing headless websites and web applications with complex content requirements
- Building multi-platform mobile apps that need centralized content management
- Creating marketing websites with frequent content updates from non-technical teams
- Prototyping client projects that require visual content modeling capabilities
- Developing e-commerce product catalogs with rich media and variant management
- Building documentation sites with collaborative editing workflows
- Creating multi-brand digital experiences with shared content libraries

## Prerequisites

- Docker and Docker Compose installed on your development machine
- At least 4GB RAM available for PostgreSQL and Caisy containers
- Port 3000 available for Caisy web interface access
- Basic understanding of GraphQL for content consumption
- Environment file with DB_PASSWORD variable configured
- Familiarity with headless CMS concepts and API-driven development

## docker-compose.yml

```yaml
services:
  caisy:
    image: caisy/caisy:latest
    container_name: caisy
    restart: unless-stopped
    environment:
      DATABASE_URL: postgres://caisy:${DB_PASSWORD}@postgres:5432/caisy
    ports:
      - "3000:3000"
    depends_on:
      - postgres
    networks:
      - caisy-network

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

volumes:
  postgres_data:

networks:
  caisy-network:
    driver: bridge
```

## .env

```bash
DB_PASSWORD=changeme
```

## Usage notes

- Docs: https://caisy.io/docs
- Access at http://localhost:3000
- GraphQL API for content delivery
- Visual editor for content modeling
- Global CDN for asset delivery
- Caisy is primarily a SaaS; self-hosted option limited

## Troubleshooting

- Caisy container fails to start with database connection error: Ensure PostgreSQL container is fully initialized before Caisy starts, add healthcheck or increase depends_on timing
- GraphQL queries returning empty results: Verify content has been published in Caisy admin interface, check API endpoint configuration
- Asset uploads failing or not displaying: Check volume mounts for asset storage and verify Caisy has write permissions to mounted directories
- Visual editor not loading properly: Clear browser cache and ensure all Caisy static assets are served correctly from port 3000
- PostgreSQL connection pool exhausted: Increase PostgreSQL max_connections setting or optimize Caisy connection pooling configuration
- Content changes not reflecting in API: Check if content is published and not in draft state, verify webhook triggers are configured properly

