# Strapi Headless CMS

> Open-source headless CMS with REST and GraphQL APIs.

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

## Overview

Strapi is an open-source headless CMS that has gained significant traction since its launch in 2015, becoming one of the most popular content management solutions for modern web applications. Unlike traditional CMSs, Strapi provides a powerful admin interface for content creators while delivering content through REST and GraphQL APIs, making it ideal for JAMstack applications, mobile apps, and multi-channel content distribution. Its JavaScript-based architecture offers extensive customization capabilities through plugins and custom code.

This stack combines Strapi with PostgreSQL to create a robust content management platform that can handle complex relational data requirements. PostgreSQL's ACID compliance and advanced querying capabilities complement Strapi's flexible content modeling system, enabling sophisticated content relationships and data integrity. The combination provides superior performance for content-heavy applications compared to simpler database solutions, while maintaining the developer-friendly experience Strapi is known for.

This configuration is particularly valuable for development teams building content-driven applications that require both editorial workflows and developer flexibility. Startups launching content platforms, agencies managing multiple client sites, and enterprises needing headless CMS capabilities will benefit from this stack's balance of ease-of-use and technical power. The PostgreSQL backend ensures the system can scale from prototype to production while supporting complex content relationships and custom business logic.

## Features

- Visual Content-Type Builder for creating custom data models without code
- Dual API support with auto-generated REST endpoints and optional GraphQL
- Role-based access control with granular permissions for team collaboration
- Internationalization (i18n) support for multi-language content management
- Media Library with drag-and-drop asset management and automatic optimization
- Plugin ecosystem including email providers, upload providers, and custom extensions
- PostgreSQL's JSONB support for flexible schema-less fields within structured content
- Advanced PostgreSQL features like full-text search and geospatial data with PostGIS compatibility

## Use cases

- JAMstack websites using Next.js, Gatsby, or Nuxt.js for content delivery
- Mobile application backends requiring structured content and user management
- Multi-brand content platforms serving different websites from a single CMS
- E-commerce product catalogs with complex relationships and inventory management
- News and publishing platforms requiring editorial workflows and content scheduling
- Corporate websites with multiple content types and approval processes
- API-first applications serving content to multiple frontend frameworks simultaneously

## Prerequisites

- Minimum 1.5GB RAM (512MB for Strapi + 256MB for PostgreSQL + overhead)
- Docker and Docker Compose installed with support for named volumes
- Available ports 1337 (Strapi admin/API) and ensure no conflicts
- Basic understanding of headless CMS concepts and API consumption
- Familiarity with environment variable configuration for database credentials
- Knowledge of content modeling principles for effective schema design

## docker-compose.yml

```yaml
services:
  strapi:
    image: strapi/strapi:latest
    container_name: strapi
    restart: unless-stopped
    environment:
      DATABASE_CLIENT: postgres
      DATABASE_HOST: postgres
      DATABASE_PORT: 5432
      DATABASE_NAME: ${DATABASE_NAME}
      DATABASE_USERNAME: ${DATABASE_USERNAME}
      DATABASE_PASSWORD: ${DATABASE_PASSWORD}
    volumes:
      - strapi_data:/srv/app
    ports:
      - "1337:1337"
    depends_on:
      - postgres
    networks:
      - strapi-network

  postgres:
    image: postgres:16-alpine
    container_name: strapi-postgres
    environment:
      POSTGRES_DB: ${DATABASE_NAME}
      POSTGRES_USER: ${DATABASE_USERNAME}
      POSTGRES_PASSWORD: ${DATABASE_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - strapi-network

volumes:
  strapi_data:
  postgres_data:

networks:
  strapi-network:
    driver: bridge
```

## .env

```bash
DATABASE_NAME=strapi
DATABASE_USERNAME=strapi
DATABASE_PASSWORD=changeme
```

## Usage notes

- Docs: https://docs.strapi.io/
- Access admin at http://localhost:1337/admin - create first admin user
- Content-type Builder: define schemas visually
- REST API at /api/[content-type], GraphQL at /graphql (install plugin)
- Media Library for asset management
- For v4: use npx create-strapi-app, not the Docker image directly

## Troubleshooting

- Strapi container exits with database connection error: Ensure PostgreSQL container is fully started before Strapi - add healthcheck or increase depends_on wait time
- Admin panel shows 'Application not found' after restart: Strapi data volume permissions issue - check that volume mount has correct ownership (1000:1000)
- API returns 404 for content endpoints: Content types need to be published in admin panel and API permissions enabled for public role
- GraphQL playground not available at /graphql: Install GraphQL plugin through Strapi admin panel marketplace
- Slow query performance with large datasets: Enable PostgreSQL query logging and add appropriate indexes through Strapi's database layer
- Media uploads failing with file size errors: Configure Strapi's file upload limits in server configuration and ensure adequate disk space

