Local Development Setup

This guide walks you through setting up a local MDCMS development environment from scratch for contributing to MDCMS itself. By the end, you will have all services running and be ready to develop.

If you want to use MDCMS in your own project (not contribute to the MDCMS codebase), see the Quick Start instead.

Prerequisites

Before you begin, install the following tools:

Tool	Version	Purpose
Bun	1.3.11+ (pinned in `.bun-version`)	Package manager, runtime, and test runner
Docker & Docker Compose	Latest stable	Infrastructure services (PostgreSQL, Redis, MinIO)
Node.js	20+	Required for Next.js apps (studio-example)
Git	Latest stable	Source control

macOS
Linux

# Install Bun
brew install oven-sh/bun/bun

# Install Docker Desktop (includes Docker Compose)
brew install --cask docker

# Install Node.js via nvm
brew install nvm
nvm install 20

# Install Bun
curl -fsSL https://bun.sh/install | bash

# Install Docker & Docker Compose
# Follow https://docs.docker.com/engine/install/ for your distro

# Install Node.js via nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install 20

The repository includes a .bun-version file that pins Bun to 1.3.11. If you use a version manager like mise or proto, it will pick this up automatically.

Clone & Install

Clone the repository

bash git clone git@github.com:mdcms-ai/mdcms.git && cd mdcms

Install dependencies

bash bun install This also sets up the pre-push git hook that runs CI checks before every push.

Copy environment file

bash cp .env.example .env Edit .env to override any defaults for your local setup. See the environment variables section below.

Environment Variables

Required

These must be set for the server to start.

Variable	Description	Example
`DATABASE_URL`	PostgreSQL connection string	`postgresql://postgres:postgres@localhost:5432/mdcms`
`REDIS_URL`	Redis connection string	`redis://localhost:6379`
`S3_ENDPOINT`	S3-compatible storage endpoint	`http://localhost:9000`
`S3_ACCESS_KEY`	S3 access key	`minioadmin`
`S3_SECRET_KEY`	S3 secret key	`minioadmin`
`S3_BUCKET`	S3 bucket name	`mdcms`

Server

Variable	Description	Example
`PORT`	Server listen port	`4000`
`NODE_ENV`	Runtime environment	`development`
`LOG_LEVEL`	Log verbosity (`debug`, `info`, `warn`, `error`)	`debug`

Studio

Variable	Description	Example
`MDCMS_STUDIO_ALLOWED_ORIGINS`	CORS allowed origins for Studio	`http://localhost:4173`
`MDCMS_AUTH_INSECURE_COOKIES`	Allow HTTP cookies in dev (no HTTPS)	`true`

Auth Providers (optional)

Variable	Description	Example
`MDCMS_AUTH_OIDC_PROVIDERS`	OIDC provider configuration (JSON)
`MDCMS_AUTH_SAML_PROVIDERS`	SAML provider configuration (JSON)

Demo

Variable	Description	Example
`MDCMS_DEMO_API_KEY`	API key for demo seed data	`mdcms_key_demo_local_compose_seed_2026_read`
`MDCMS_DEMO_PROJECT`	Demo project slug	`marketing-site`
`MDCMS_DEMO_ENVIRONMENT`	Demo environment name	`staging`

The Docker Compose dev configuration sets all required variables automatically. You only need to configure .env manually if running services outside Docker.

Start Development

Docker Compose (recommended)
Manual

The simplest way to get everything running:

docker compose -f docker-compose.dev.yml up -d

This starts all services together:

PostgreSQL 16 — primary database
Redis 7 — sessions and caching
MinIO — S3-compatible object storage
Mailhog — email capture for development
Server — Elysia API with watch mode (auto-reloads on changes)
Studio Example — Next.js demo app

To stop everything:

docker compose -f docker-compose.dev.yml down

Start infrastructure services only, then run apps individually for more control:

# Start infrastructure
docker compose up postgres redis minio -d

In separate terminals:

# Terminal 1: Start the server
bun nx dev server

# Terminal 2: Start the Studio example app
bun nx dev studio-example

Service Endpoints

Once running, these services are available:

Service	URL
Server API	http://localhost:4000
Studio Example	http://localhost:4173
MinIO Console	http://localhost:9001
Mailhog	http://localhost:8025
PostgreSQL	`localhost:5432`
Redis	`localhost:6379`

Demo Credentials

The dev seed data creates a demo user you can use to log in to Studio:

Field	Value
Email	`demo@mdcms.local`
Password	`Demo12345!`

Available Commands

These scripts are defined in the root package.json and orchestrated by Nx:

Command	Description
`bun run dev`	Start the server in development mode
`bun run compose:dev`	Start full dev stack via Docker Compose
`bun run compose:dev:down`	Stop the dev Docker Compose stack
`bun run build`	Build all packages and apps
`bun run typecheck`	Run TypeScript type checking across all packages
`bun run quality`	Run format check + typecheck
`bun run unit`	Run unit tests
`bun run integration`	Run integration tests (requires Docker services)
`bun run ci:required`	Run the full CI gate: format + typecheck + unit + integration
`bun run format`	Format code with Prettier

​Prerequisites

​Clone & Install

​Environment Variables

​Required

​Server

​Studio

​Auth Providers (optional)

​Demo

​Start Development

​Service Endpoints

​Demo Credentials

​Available Commands

Prerequisites

Clone & Install

Environment Variables

Required

Server

Studio

Auth Providers (optional)

Demo

Start Development

Service Endpoints

Demo Credentials

Available Commands