# Strapi + Next.js Full Stack

> Headless CMS with Strapi backend and Next.js frontend.

- Category: Full Web Stacks
- Difficulty: intermediate
- Components: strapi, nextjs, postgresql, redis, nginx
- Tags: strapi, nextjs, headless-cms, react, fullstack
- Source: https://docker.recipes/full-stacks/strapi-nextjs-stack

## Overview

Strapi is an open-source headless Content Management System (CMS) that provides a flexible, developer-first approach to content management. Built entirely in JavaScript, Strapi separates content management from presentation, offering both RESTful and GraphQL APIs out of the box. This architecture allows developers to manage content through Strapi's intuitive admin panel while delivering that content to any frontend framework or platform.

This stack combines Strapi's powerful content management capabilities with Next.js, React's production-ready framework that excels at both static site generation and server-side rendering. PostgreSQL serves as the robust relational database for Strapi's content storage, while Redis provides high-performance caching and session management. NGINX acts as the reverse proxy, handling SSL termination, load balancing, and routing between the frontend and backend services. Together, these components create a modern JAMstack architecture that can scale from startup MVPs to enterprise-grade applications.

Development teams building content-heavy applications, marketing websites, e-commerce platforms, or multi-channel digital experiences will find this stack particularly valuable. The headless approach means content creators can work independently in Strapi while developers have complete freedom to build custom frontends in Next.js. This separation enables faster development cycles, better performance through static generation, and the flexibility to deliver content to web, mobile, and IoT applications from a single source.

## Features

- Visual content-type builder in Strapi for creating custom data models without code
- Next.js static site generation (SSG) and server-side rendering (SSR) for optimal performance
- RESTful and GraphQL APIs automatically generated from Strapi content models
- Role-based access control with customizable permissions for content editors
- PostgreSQL JSONB support for flexible content structures alongside relational data
- Redis-powered session storage and API response caching
- Strapi's plugin ecosystem for extending functionality (SEO, internationalization, media)
- Next.js incremental static regeneration for updating static content without full rebuilds

## Use cases

- Marketing websites requiring frequent content updates by non-technical team members
- E-commerce platforms needing product catalogs with complex attributes and relationships
- Multi-brand companies delivering content to multiple websites from a centralized CMS
- SaaS applications requiring user-generated content management and admin dashboards
- News and publishing platforms with editorial workflows and content scheduling
- Mobile app backends providing structured content through Strapi's REST/GraphQL APIs
- International websites leveraging Strapi's i18n plugin for multi-language content management

## Prerequisites

- Docker and Docker Compose installed with at least 3GB available RAM
- Ports 80, 443, 1337, and 3000 available on the host system
- Basic understanding of React/Next.js development for frontend customization
- Familiarity with REST APIs or GraphQL for connecting frontend to Strapi backend
- Node.js development environment for building custom Strapi plugins if needed
- SSL certificates for production deployment with NGINX HTTPS configuration

## docker-compose.yml

```yaml
services:
  strapi:
    image: strapi/strapi:latest
    ports:
      - "1337:1337"
    environment:
      DATABASE_CLIENT: postgres
      DATABASE_HOST: postgres
      DATABASE_PORT: 5432
      DATABASE_NAME: ${POSTGRES_DB}
      DATABASE_USERNAME: ${POSTGRES_USER}
      DATABASE_PASSWORD: ${POSTGRES_PASSWORD}
      JWT_SECRET: ${JWT_SECRET}
      ADMIN_JWT_SECRET: ${ADMIN_JWT_SECRET}
      APP_KEYS: ${APP_KEYS}
    volumes:
      - strapi_app:/srv/app
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - strapi-net
    restart: unless-stopped

  nextjs:
    build:
      context: ./frontend
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      STRAPI_URL: http://strapi:1337
    depends_on:
      - strapi
    networks:
      - strapi-net
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - strapi-net
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    networks:
      - strapi-net
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - strapi
      - nextjs
    networks:
      - strapi-net
    restart: unless-stopped

volumes:
  strapi_app:
  postgres_data:
  redis_data:

networks:
  strapi-net:
    driver: bridge
```

## .env

```bash
# PostgreSQL
POSTGRES_USER=strapi
POSTGRES_PASSWORD=secure_postgres_password
POSTGRES_DB=strapi

# Strapi Secrets
JWT_SECRET=$(openssl rand -base64 32)
ADMIN_JWT_SECRET=$(openssl rand -base64 32)
APP_KEYS=$(openssl rand -base64 32),$(openssl rand -base64 32)
```

## Usage notes

- Strapi Admin at http://localhost:1337/admin
- Next.js frontend at http://localhost:3000
- Create Dockerfile for Next.js frontend
- Configure nginx.conf for production routing

## Troubleshooting

- Strapi 'Database connection refused': Ensure PostgreSQL health check passes before Strapi starts using depends_on condition
- Next.js build failing with 'STRAPI_URL not found': Verify environment variable points to http://strapi:1337 for container-to-container communication
- NGINX 502 Bad Gateway: Check that both Strapi (port 1337) and Next.js (port 3000) containers are running and responsive
- Strapi admin panel shows 'Application configuration error': Generate proper JWT_SECRET, ADMIN_JWT_SECRET, and APP_KEYS in environment variables
- PostgreSQL data loss after container restart: Ensure postgres_data volume is properly mounted to /var/lib/postgresql/data
- Redis connection timeout in Strapi: Configure Strapi's Redis session store to use redis:6379 as the connection string

