Optical CMS Development with Docker Compose

Docker Compose for Optical CMS – Complete Guide for Local Instance Setup & Development.

Creating your local Optical instance to working with extensions, hooks, modules, and environment configurations.

1. Why Use Docker Compose for Optical CMS?

Optical CMS consists of multiple components:

• Directus App (API & Admin Panel)

• PostgreSQL Database

• Redis Cache (for performance & flow queue management)

• Optional Services: Custom endpoints, hooks, modules, file storage adapters, etc.

2. Components in a Typical Optical Local Setup

A complete Optical development stack typically includes:

2.1 Directus (Optical CMS API + Admin App)

Provides:

• Admin UI

• Collections & Field Management

• Flows

• Roles & Permissions

• Authentication

• File Management

• Extensions (Hooks, Endpoints, Modules, Interfaces, Displays)

2.2 PostgreSQL

Stores:

• All collection data

• User roles

• Permissions

• Audit logs

• Flow execution logs

2.3 Redis (Optional but recommended)

Handles:

• Flow job queues

• Notifications

• Event triggers

• Performance optimization

2.4 File Storage

By default:

• Local filesystem in /uploads
  But can be replaced via S3, GCS, Azure Blob, etc.

3. Standard Optical Docker Compose File

This is the exact structure many GovTech teams use while working with Optical/Directus.

services:

  directus:

    image: directus/directus:latest

    ports:

      - "8055:8055"

    environment:

      KEY: "123456"

      SECRET: "abcdef"

      ADMIN_EMAIL: "admin@example.com"

      ADMIN_PASSWORD: "admin123"

      DB_CLIENT: "pg"

      DB_HOST: "database"

      DB_PORT: "5432"

      DB_DATABASE: "optical"

      DB_USER: "postgres"

      DB_PASSWORD: "postgres"

      REDIS_ENABLED: "true"

      REDIS_HOST: "redis"

      STORAGE_LOCATIONS: "local"

      STORAGE_LOCAL_ROOT: "/directus/uploads"

    volumes:

      - ./uploads:/directus/uploads

      - ./extensions:/directus/extensions

    depends_on:

      - database

      - redis

  database:

    image: postgres:15

    environment:

      POSTGRES_PASSWORD: postgres

      POSTGRES_DB: optical

    volumes:

      - directus_db:/var/lib/postgresql/data

  redis:

    image: redis:7

    command: ["redis-server", "--appendonly", "yes"]

    volumes:

      - redis_data:/data

volumes:

  directus_db:

  redis_data:

4. Folder Structure for Optical Development

A good local development folder looks like:

optical-local/

│

├── docker-compose.yml

├── .env

├── extensions/

│   ├── hooks/

│   │   └── my-custom-hook/

│   ├── endpoints/

│   │   └── my-endpoint/

│   ├── modules/

│   │   └── my-dashboard/

│

├── uploads/

└── logs/

5. How to Start Your Local Optical Instance

Step 1: Clone your local setup folder

git clone <your-optical-local-repo>

Step 2: Start the environment

docker compose up -d

Step 3: Access the Admin Panel

http://localhost:8055/admin

Login with credentials from .env.

6. Working With Optical Extensions (Modules, Hooks, Endpoints)

Optical’s real power comes from custom extensions.

6.1 Hooks

Hooks listen to events like:

• Item create/update/delete

• Login

• File upload

• Before/after flows

Example structure:

extensions/hooks/prjourney-user-audit/index.js

6.2 Endpoints

Useful for custom API logic:

extensions/endpoints/passport-ocr/index.js

6.3 Modules (UI Components)

Used for dashboards, admin widgets, custom pages:

extensions/modules/prj-tools/src/index.js

6.4 Interfaces

Custom input fields in CMS forms.

6.5 Displays

Custom display logic for listing screens.

After any extension change:

docker compose restart directus

7. Database Reset & Rebuild

Reset the database completely

docker compose down -v

docker compose up -d

Seed sample data

You can automate this using:

• SQL scripts

• Postman collections

• Directus export/import

• Custom NPM scripts

8. Environment Variable Configuration

A typical .env file for Optical:

ADMIN_EMAIL=admin@example.com

ADMIN_PASSWORD=admin123

DB_CLIENT=pg

DB_HOST=database

DB_PORT=5432

DB_DATABASE=optical

DB_USER=postgres

DB_PASSWORD=postgres

KEY=somelongkey

SECRET=someverylongsecret

PORT=8055

9. Using Directus Template CLI for Schema Import/Export

Optical teams commonly store schema & flows using:

npx directus-template-cli export

npx directus-template-cli apply

Useful for:

• Syncing DEV → UAT → PROD

• Sharing schema with new developers

• Rebuilding instances quickly

10. Local Development Best Practices

10.1 Always bind extensions as a volume

So changes reflect instantly without rebuilding image.

10.2 Avoid editing inside the container

Always edit on your host folder.

10.3 Rebuild only when necessary

Use:

docker compose restart directus

instead of destroying everything.

10.4 Maintain environment-specific docker-compose.override.yml

Example:

• compose.dev.yml

• compose.uat.yml

11. Multi-Instance Support (Different Ports)

You can run multiple Optical instances simultaneously:

• 8055 → Worker Profile POC

• 8056 → BCA POC

• 8057 → Singpass Demo

Just duplicate the folder and change

ports:

  - "8056:8055"

12. Debugging Optical on Docker

See live logs

docker compose logs -f directus

Jump inside container

docker compose exec directus sh

Check DB

docker compose exec database psql -U postgres

Check Redis

docker compose exec redis redis-cli

13. When to Rebuild Everything

Rebuild required when:

• You upgrade Directus version

• Install/remove NPM packages inside /extensions

• DB corruption

• Switching between templates

Command:

docker compose down -v

docker compose up --build -d

14. Fully Automatic Optical Starter Kit (Ready for Beginners)

Complete downloadable starter kit containing:

• docker-compose.yml

• sample .env

• default extensions folder

• sample collections

• sample flows

• reset scripts

• seed data

Conclusion

Docker Compose is the backbone of Optical CMS development.
It ensures:

• Consistent environment

• Faster onboarding

• Easier debugging

• Clean separation between Directus, DB, and Redis

• Instant extension development workflow

A proper Docker-based Optical stack gives you complete confidence while building, testing, and demonstrating CMS features for agencies like MCCY, BCA, MOM, or GovTech.