# KeystoneJS CMS

> KeystoneJS headless CMS with PostgreSQL.

- Category: CMS & Blogging
- Difficulty: intermediate
- Components: keystone, postgresql, nginx
- Tags: keystone, cms, headless, graphql
- Source: https://docker.recipes/cms/keystone-cms-stack

## Overview

KeystoneJS is a modern headless CMS and GraphQL API framework built on Node.js that enables developers to create powerful content management systems with a type-safe development experience. Originally developed by Thinkmill, KeystoneJS provides an intuitive admin UI, automatic GraphQL API generation, and flexible schema definition capabilities, making it ideal for building everything from simple websites to complex multi-tenant applications. This deployment creates a complete KeystoneJS CMS environment with three dedicated services: a KeystoneJS application container running on Node.js 20 Alpine, a PostgreSQL 15 database for robust data storage, and an NGINX reverse proxy for production-ready web serving. The KeystoneJS container connects to the PostgreSQL database using environment variables, while NGINX handles incoming requests and can be configured for SSL termination, caching, and load balancing. This stack is perfect for development teams who need a headless CMS with strong typing, automatic API generation, and the reliability of PostgreSQL for data persistence. The combination provides excellent performance for content-heavy applications while maintaining the flexibility to serve multiple frontend applications through KeystoneJS's GraphQL endpoint at /api/graphql.

## Features

- Automatic GraphQL API generation with type-safe schema definitions
- Built-in Admin UI for content management accessible through web interface
- PostgreSQL 15 integration with ACID compliance and advanced querying capabilities
- Session-based authentication with configurable session secrets
- NGINX reverse proxy configuration for production deployment scenarios
- Hot-reload development support through volume mounting of application code
- Persistent data storage with dedicated PostgreSQL volume management
- Environment-based configuration for database connections and security settings

## Use cases

- Headless CMS for React, Vue, or Next.js frontend applications
- Multi-site content management with shared backend infrastructure
- E-commerce product catalog management with GraphQL API integration
- Blog and publishing platforms requiring structured content workflows
- Corporate websites needing non-technical content editor interfaces
- API-first applications requiring rapid content model prototyping
- Development environments for KeystoneJS application testing and staging

## Prerequisites

- Docker and Docker Compose with minimum 2GB available RAM for all services
- Node.js knowledge for KeystoneJS schema configuration and customization
- Port 3000 and 80 available on host system for KeystoneJS and NGINX
- Basic understanding of GraphQL queries and mutations for API interaction
- PostgreSQL familiarity for database maintenance and performance tuning
- Existing KeystoneJS application code in ./app directory before container startup

## docker-compose.yml

```yaml
services:
  keystone:
    image: node:20-alpine
    container_name: keystone-cms
    restart: unless-stopped
    working_dir: /app
    command: npm run start
    ports:
      - "${KEYSTONE_PORT:-3000}:3000"
    environment:
      - DATABASE_URL=postgres://${DB_USER}:${DB_PASSWORD}@keystone-db/keystone
      - SESSION_SECRET=${SESSION_SECRET}
    volumes:
      - ./app:/app
    depends_on:
      - keystone-db

  keystone-db:
    image: postgres:15-alpine
    container_name: keystone-db
    restart: unless-stopped
    environment:
      - POSTGRES_USER=${DB_USER}
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=keystone
    volumes:
      - keystone_db_data:/var/lib/postgresql/data

  nginx:
    image: nginx:alpine
    container_name: keystone-nginx
    restart: unless-stopped
    ports:
      - "${NGINX_PORT:-80}:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro

volumes:
  keystone_db_data:
```

## .env

```bash
# KeystoneJS
KEYSTONE_PORT=3000
DB_USER=keystone
DB_PASSWORD=keystone_password
SESSION_SECRET=your_session_secret
NGINX_PORT=80
```

## Usage notes

- Keystone at http://localhost:3000
- GraphQL at /api/graphql
- Create keystone project first
- Define schema in keystone.ts

## Troubleshooting

- keystone-cms container exits immediately: Ensure ./app directory contains valid package.json with start script and KeystoneJS dependencies installed
- Database connection refused errors: Verify keystone-db container is running and DATABASE_URL environment variables match PostgreSQL credentials
- NGINX 502 Bad Gateway responses: Check that keystone container is accessible on port 3000 and update nginx.conf upstream configuration
- GraphQL endpoint returns 404 errors: Confirm KeystoneJS application started successfully and schema is properly defined in keystone.ts configuration file
- Session authentication not working: Verify SESSION_SECRET environment variable is set and has sufficient entropy for security
- PostgreSQL data not persisting: Ensure keystone_db_data volume is properly mounted and PostgreSQL container has write permissions

