# KeystoneJS

> Headless CMS and web application framework built on Node.js.

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

## Overview

KeystoneJS is a modern headless CMS and GraphQL-first application framework built on Node.js that bridges the gap between traditional content management and modern development practices. Originally created by Thinkmill, KeystoneJS provides a developer-friendly approach to building content-driven applications with a powerful admin interface, automatic GraphQL API generation, and TypeScript-first schema definition. Its architecture emphasizes flexibility and extensibility while maintaining the ease of use that content creators expect from traditional CMS platforms.

This Docker configuration pairs KeystoneJS with PostgreSQL to create a robust content management platform that leverages PostgreSQL's advanced relational capabilities, ACID compliance, and superior JSON support for handling KeystoneJS's flexible content schemas. PostgreSQL's mature transaction system ensures data integrity for content operations, while its excellent JSON/JSONB support complements KeystoneJS's dynamic field types and relationship structures. The combination provides both the relational reliability needed for complex content relationships and the flexibility required for modern headless CMS architectures.

This stack is ideal for development teams building content-heavy applications, marketing sites, or multi-tenant platforms where GraphQL API access, robust admin interfaces, and reliable data persistence are essential. Organizations migrating from traditional CMS platforms to headless architectures will find KeystoneJS's familiar admin UI reduces the learning curve for content creators, while developers benefit from TypeScript-driven schema definitions and PostgreSQL's proven scalability for growing content repositories.

## Features

- Auto-generated GraphQL API with real-time schema introspection based on TypeScript content models
- Built-in Admin UI with customizable field types, file uploads, and relationship management
- PostgreSQL JSONB field support for flexible content structures alongside relational data
- Advanced access control with field-level permissions and authentication hooks
- Content versioning and audit trails leveraging PostgreSQL's transaction capabilities
- Real-time subscriptions through GraphQL with PostgreSQL LISTEN/NOTIFY support
- Multi-tenancy support using PostgreSQL schemas and row-level security
- Extensible field types including rich text, images, and custom React components

## Use cases

- Marketing websites requiring frequent content updates with non-technical editor access
- E-commerce platforms needing complex product catalogs with variant relationships
- Multi-brand content management with shared asset libraries and cross-publishing
- Developer portfolios and agency sites with project showcases and blog functionality
- Enterprise knowledge bases with role-based content access and approval workflows
- SaaS application backends requiring user-generated content and file management
- News and media sites with article scheduling, categorization, and author management

## Prerequisites

- Minimum 1GB RAM (2GB recommended for PostgreSQL and KeystoneJS with admin UI)
- Docker and Docker Compose with BuildKit support for multi-stage builds
- Node.js development knowledge for KeystoneJS schema customization
- Port 3000 available for KeystoneJS admin interface and GraphQL endpoint
- Basic understanding of GraphQL for API integration and querying
- PostgreSQL knowledge for database maintenance and performance tuning

## docker-compose.yml

```yaml
services:
  keystone:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: keystone
    restart: unless-stopped
    environment:
      DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
    ports:
      - "3000:3000"
    depends_on:
      - postgres
    networks:
      - keystone-network

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

volumes:
  postgres_data:

networks:
  keystone-network:
    driver: bridge
```

## .env

```bash
DB_NAME=keystone
DB_USER=keystone
DB_PASSWORD=changeme
```

## Usage notes

- Docs: https://keystonejs.com/docs
- Requires Dockerfile: npx create-keystone-app creates project
- Access admin UI at http://localhost:3000
- GraphQL API at /api/graphql, REST possible via extensions
- Schema-driven: define content types in TypeScript
- Document and relationship fields, access control, hooks

## Troubleshooting

- Database connection refused: Ensure PostgreSQL container is fully initialized before KeystoneJS starts by adding healthcheck or longer depends_on delay
- KeystoneJS schema migration errors: Check DATABASE_URL format and PostgreSQL user permissions for CREATE/ALTER operations
- Admin UI shows 'Cannot read properties of undefined': Verify all required environment variables are set and PostgreSQL connection is stable
- GraphQL introspection disabled in production: Set NODE_ENV appropriately or enable introspection explicitly in keystone.ts config
- File upload failures: Ensure proper volume mounts for KeystoneJS uploads directory and sufficient disk space
- PostgreSQL connection pool exhausted: Tune PostgreSQL max_connections setting and KeystoneJS database pool configuration

