​
Getting Started

Welcome to the CMS API! This guide will help you set up your development environment and make your first API call.

​
Prerequisites

Before you begin, ensure you have:
  • Docker Desktop (Windows/Mac) or Docker Engine (Linux)
  • Docker Compose v2.0+
  • Git for version control
  • Make (for running project commands)
  • Node.js 20+ (for frontend development)
  • Postman or similar API client (optional)

​
Quick Start

​
1. Clone the Monorepo

git clone --recurse-submodules https://github.com/Givexpert/cms.git
cd cms

​
2. Start Development Environment

The infrastructure is managed from the cms-docker and cms-lb repositories: 
# Start the load balancer first (creates the cms-public network)
cd cms-lb
docker compose up -d
cd ..

# Start all services (PostgreSQL, Redis, Elasticsearch, MinIO, API, etc.)
cd cms-docker
docker compose build --no-cache
docker compose up -d --wait

# Check service status
docker compose ps

​
3. Initialize the API Database

Services:
  • API: http://localhost:8080
  • PostgreSQL: localhost:5432 (DB: cms_master)
  • Redis: localhost:6379
  • Elasticsearch: http://localhost:9200 (Search engine)
  • MinIO: http://localhost:9000 (Console: http://localhost:9001)
  • Adminer: http://localhost:8081 (Database UI)
From the cms-api directory, run the setup command: 
cd cms-api
make setup
This runs master migrations, seeds tenants/sites/users, runs tenant migrations, and loads demo content. Services (replace local with your USER_PREFIX from cms-docker/.env):
ServiceURL
APIhttps://local.api.cms
Adminer (DB UI)https://local.adminer.cms
MinIO Dashboardhttps://local.dashboard.minio.cms
MinIO APIhttps://local.api.minio.cms

​
4. Generate Development Token

curl -X POST https://local.api.cms/dev/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "role": "cms_admin",
    "sub": "admin@demo.local"
  }'
Response: 
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}
⚠️ DEV ONLY: This endpoint is disabled in production (APP_ENV=prod)

​
5. Make Your First API Call

# List articles
curl https://local.api.cms/admin/articles \
  -H "Authorization: Bearer <token>" \
  -H "X-Tenant-Id: demo" \
  -H "X-Site-Id: <site-uuid>"
Response: 
{
  "@context": "/contexts/Article",
  "@type": "hydra:Collection",
  "hydra:totalItems": 0,
  "hydra:member": []
}

​
Project Structure

cms-api/
├── config/              # Symfony configuration
│   ├── packages/        # Service configuration
│   └── routes/          # Route definitions
├── src/
│   ├── Entity/
│   │   ├── Master/      # Master database entities (Tenant, User, Site)
│   │   └── Tenant/      # Tenant database entities (Article, Page, Media, etc.)
│   ├── Controller/      # Custom controllers
│   ├── Service/         # Business logic
│   ├── Repository/      # Database queries
│   ├── Security/        # Authentication & authorization
│   └── EventSubscriber/ # Doctrine events
├── migrations/          # Database migrations
├── Makefile             # Dev commands (run via `make <target>`)
└── .env                 # Environment variables

​
Environment Variables

Environment variables are injected by Docker via cms-docker/compose.yaml. Key variables: 
# Database
DATABASE_URL="postgresql://cms_user:cms_password@cms-db:5432/cms_db?serverVersion=16&charset=utf8"

# Redis
REDIS_URL="redis://:redis@cms-redis:6379"

# Elasticsearch
ELASTICSEARCH_URL="http://cms-elasticsearch:9200"

# Elasticsearch
ELASTICSEARCH_URL="http://cms-elasticsearch:9200"

# MinIO (S3-compatible storage)
S3_ENDPOINT="http://cms-minio:9000"
S3_PUBLIC_ENDPOINT="https://local.api.minio.cms"
S3_BUCKET="cms-storage"
S3_ACCESS_KEY="minioadmin"
S3_SECRET_KEY="minioadmin123"
S3_REGION="us-east-1"
S3_USE_PATH_STYLE="true"

# App
APP_ENV=dev

​
API Documentation

​
Swagger UI (Interactive)

Visit https://local.api.cms/docs for interactive API documentation. Features:
  • Browse all endpoints
  • Try API calls directly
  • View request/response schemas
  • See example payloads

​
OpenAPI Spec

Download: https://local.api.cms/docs.json (JSON format)

​
Common Commands

All commands are run from the cms-api directory using make: 
make setup           # First-time setup (migrations + fixtures)
make migrate         # Run all migrations (master + tenants)
make migrate-master  # Run master migrations only
make migrate-tenant  # Run tenant migrations only
make seed            # Load all fixtures
make test            # Run tests
make clear-cache     # Clear Symfony cache
make shell           # Open a shell in the API container
make db-shell        # Open PostgreSQL shell (master)
make db-shell-tenant # Open PostgreSQL shell (tenant demo)

​
Next Steps

Architecture

Understand the system architecture

Authentication

Learn about JWT authentication

API Reference

Browse complete API documentation

Multi-Tenancy

Understand tenant isolation

​
Troubleshooting

​
Services Not Starting

# View API logs
docker compose -f ../cms-docker/compose.yaml logs -f cms-api

# Restart the API service
docker compose -f ../cms-docker/compose.yaml restart cms-api

# Rebuild the API container
docker compose -f ../cms-docker/compose.yaml up -d --build cms-api

​
Database Connection Error

Check PostgreSQL is running: 
docker compose -f ../cms-docker/compose.yaml ps cms-db
Verify connection: 
make shell
php bin/console dbal:run-sql "SELECT 1"

​
Permission Errors

# Fix permissions (Linux/Mac)
sudo chown -R $USER:$USER .

​
Need Help?

Next: Architecture Overview