# Apostrophe CMS

> Node.js CMS with in-context editing and rich media management.

- Category: CMS & Blogging
- Difficulty: intermediate
- Components: apostrophe, mongodb
- Tags: apostrophe, nodejs, in-context-editing, media
- Source: https://docker.recipes/cms/apostrophe-cms

## Overview

Apostrophe CMS is a modern Node.js content management system built with in-context editing at its core, allowing content creators to edit pages directly on the front-end without switching between admin panels and preview modes. Originally developed by P'unk Avenue and now maintained as an open-source project, Apostrophe distinguishes itself from traditional CMSes by treating content as composable widgets within flexible page areas, enabling non-technical users to build sophisticated layouts while maintaining developer control over functionality and design. This Docker stack combines Apostrophe with MongoDB 7, leveraging MongoDB's flexible document structure to store Apostrophe's widget-based content architecture, page trees, and media assets efficiently. The pairing is particularly powerful because Apostrophe's schema-driven approach to content types maps naturally to MongoDB's document collections, while MongoDB's aggregation framework supports Apostrophe's advanced querying needs for content relationships and site navigation. This configuration is ideal for agencies, marketing teams, and organizations that need a CMS where content creators can build complex pages visually while developers maintain full control over the underlying code structure, offering a middle ground between inflexible traditional CMSes and overly complex headless solutions.

## Features

- In-context editing with live preview - edit text, images, and widgets directly on the page without admin panel switching
- Widget-based content composition using areas and singletons for flexible page layouts
- Rich media management with automatic image resizing, cropping, and optimization
- Schema-driven content types with automatic admin UI generation for custom post types
- Built-in user management with role-based permissions and workflow controls
- Page tree management with drag-and-drop organization and URL routing
- MongoDB aggregation pipeline integration for complex content queries and relationships
- Express.js foundation allowing custom routes, middleware, and API endpoints

## Use cases

- Marketing websites where non-technical teams need to create landing pages with complex layouts
- Corporate websites requiring frequent content updates with approval workflows
- Event and conference sites needing dynamic speaker, session, and venue management
- Portfolio and agency websites showcasing projects with rich media galleries
- Educational institutions managing course catalogs, faculty profiles, and program information
- Non-profit organizations managing donor campaigns, event listings, and volunteer coordination
- Small to medium e-commerce sites needing custom product presentation beyond standard templates

## Prerequisites

- Docker and Docker Compose installed with at least 2GB RAM available for MongoDB operations
- Port 3000 available for Apostrophe web interface access
- Basic understanding of Node.js project structure and npm package management
- Familiarity with MongoDB concepts like collections and documents for content modeling
- Knowledge of Express.js routing and middleware for custom functionality development
- Understanding of widget-based CMS concepts and area/singleton content organization

## docker-compose.yml

```yaml
services:
  apostrophe:
    image: apostrophecms/apostrophe:latest
    container_name: apostrophe
    restart: unless-stopped
    environment:
      APOS_MONGODB_URI: mongodb://mongodb:27017/apostrophe
    volumes:
      - ./app:/app
      - uploads_data:/app/public/uploads
    ports:
      - "3000:3000"
    depends_on:
      - mongodb
    networks:
      - apostrophe-network

  mongodb:
    image: mongo:7
    container_name: apostrophe-mongodb
    volumes:
      - mongodb_data:/data/db
    networks:
      - apostrophe-network

volumes:
  uploads_data:
  mongodb_data:

networks:
  apostrophe-network:
    driver: bridge
```

## .env

```bash
# Apostrophe requires project setup
```

## Usage notes

- Docs: https://docs.apostrophecms.org/
- Access at http://localhost:3000
- In-context editing: click to edit directly on page
- Widgets and areas for page composition
- Built on Express.js and MongoDB
- Project setup: npx create-apostrophe-app

## Troubleshooting

- Error: 'Cannot connect to MongoDB': Ensure MongoDB container is fully started before Apostrophe by adding healthcheck or increasing startup delay
- Apostrophe admin interface not loading: Check that uploads_data volume has proper permissions and disk space for media storage
- Session errors or login issues: Verify APOS_MONGODB_URI environment variable matches the exact MongoDB service name and database
- Widget rendering errors: Ensure custom widget templates are properly mounted in the app volume and restart the container
- Performance issues with large media uploads: Increase MongoDB container memory allocation beyond the 512MB minimum
- Build errors when extending Apostrophe: Verify Node.js version compatibility between your custom modules and the apostrophecms/apostrophe base image

