Docker Configuration

This guide covers Docker-specific configuration, customization, and best practices for deploying Cal.com with Docker and Docker Compose.

Overview

Cal.com provides official Docker images and Docker Compose configurations for easy deployment:

Docker Hub: calcom/cal.com
Scarf Registry: calcom.docker.scarf.sh/calcom/cal.com (default, for metrics)
GitHub: Source Dockerfiles in the main repository

Support Policy: Cal.com maintains official Docker configurations, but users are responsible for their Docker-based installations. Community support is available via GitHub Discussions.

Docker Compose Services

The default docker-compose.yml includes multiple services:

Service Architecture

services:
  database      # PostgreSQL database
  redis         # Redis cache and queues
  calcom        # Main web application
  calcom-api    # API v2 service
  studio        # Prisma Studio (optional)

Database Service

database:
  container_name: database
  image: postgres
  restart: always
  volumes:
    - database-data:/var/lib/postgresql
  environment:
    - POSTGRES_USER=unicorn_user
    - POSTGRES_PASSWORD=magical_password
    - POSTGRES_DB=calendso
  networks:
    - stack

Change default credentials in production!

environment:
  - POSTGRES_USER=${POSTGRES_USER}
  - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
  - POSTGRES_DB=calendso

Redis Service

redis:
  container_name: redis
  image: redis:latest
  restart: always
  volumes:
    - redis-data:/data
  networks:
    - stack
  ports:
    - "${REDIS_PORT:-6379}:6379"

Redis is used for:

Caching
Job queues
Session storage
Rate limiting

Cal.com Web Service

calcom:
  image: calcom.docker.scarf.sh/calcom/cal.com
  build:
    context: .
    dockerfile: Dockerfile
    args:
      NEXT_PUBLIC_WEBAPP_URL: ${NEXT_PUBLIC_WEBAPP_URL}
      NEXT_PUBLIC_LICENSE_CONSENT: ${NEXT_PUBLIC_LICENSE_CONSENT}
      NEXTAUTH_SECRET: ${NEXTAUTH_SECRET}
      CALENDSO_ENCRYPTION_KEY: ${CALENDSO_ENCRYPTION_KEY}
      DATABASE_URL: ${DATABASE_URL}
  restart: always
  networks:
    - stack
  ports:
    - 3000:3000
  env_file: .env
  environment:
    - DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${DATABASE_HOST}/${POSTGRES_DB}
  depends_on:
    - database

API v2 Service

calcom-api:
  container_name: calcom-api
  build:
    context: .
    dockerfile: apps/api/v2/Dockerfile
    args:
      DATABASE_URL: ${DATABASE_URL}
  restart: always
  networks:
    - stack
  ports:
    - "${API_PORT:-80}:${API_PORT:-80}"
  env_file: .env
  environment:
    - API_PORT=${API_PORT:-80}
    - DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${DATABASE_HOST}/${POSTGRES_DB}
    - NEXTAUTH_SECRET=${NEXTAUTH_SECRET}
    - REDIS_URL=${REDIS_URL}
  depends_on:
    - database
    - redis

Prisma Studio (Development)

studio:
  image: calcom.docker.scarf.sh/calcom/cal.com
  restart: always
  networks:
    - stack
  ports:
    - 5555:5555
  env_file: .env
  environment:
    - DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${DATABASE_HOST}/${POSTGRES_DB}
  depends_on:
    - database
  command:
    - npx
    - prisma
    - studio

Remove or comment out Prisma Studio in production to prevent unauthorized database access.

Dockerfile Deep Dive

Main Application Dockerfile

The Cal.com Dockerfile uses multi-stage builds:

Stage 1: Builder

FROM --platform=$BUILDPLATFORM node:20 AS builder

WORKDIR /calcom

# Build arguments
ARG NEXT_PUBLIC_WEBAPP_URL=http://localhost:3000
ARG NEXTAUTH_SECRET=secret
ARG CALENDSO_ENCRYPTION_KEY=secret
ARG DATABASE_URL
ARG MAX_OLD_SPACE_SIZE=6144

# Environment variables for build
ENV NEXT_PUBLIC_WEBAPP_URL=http://NEXT_PUBLIC_WEBAPP_URL_PLACEHOLDER \
    NODE_OPTIONS=--max-old-space-size=${MAX_OLD_SPACE_SIZE} \
    BUILD_STANDALONE=true

# Copy source and build
COPY package.json yarn.lock .yarnrc.yml ./
COPY .yarn ./.yarn
COPY apps/web ./apps/web
COPY packages ./packages

RUN yarn install
RUN yarn workspace @calcom/web run build

NEXT_PUBLIC_WEBAPP_URL is set to a placeholder during build and replaced at runtime by start.sh script.

Stage 2: Builder-Two

FROM node:20 AS builder-two

WORKDIR /calcom
ARG NEXT_PUBLIC_WEBAPP_URL=http://localhost:3000

ENV NODE_ENV=production

# Copy artifacts from builder
COPY --from=builder /calcom/yarn.lock ./yarn.lock
COPY --from=builder /calcom/node_modules ./node_modules
COPY --from=builder /calcom/packages ./packages
COPY --from=builder /calcom/apps/web ./apps/web

# Replace placeholder with actual URL
RUN scripts/replace-placeholder.sh http://NEXT_PUBLIC_WEBAPP_URL_PLACEHOLDER ${NEXT_PUBLIC_WEBAPP_URL}

Stage 3: Runner

FROM node:20 AS runner

WORKDIR /calcom

# Install utilities
RUN apt-get update && \
    apt-get install -y --no-install-recommends netcat-openbsd wget && \
    rm -rf /var/lib/apt/lists/*

COPY --from=builder-two /calcom ./

ENV NODE_ENV=production
EXPOSE 3000

# Health check
HEALTHCHECK --interval=30s --timeout=30s --retries=5 \
  CMD wget --spider http://localhost:3000 || exit 1

CMD ["/calcom/scripts/start.sh"]

API v2 Dockerfile

FROM node:20-alpine AS build

ARG DATABASE_DIRECT_URL
ARG DATABASE_URL

WORKDIR /calcom

ENV NODE_ENV="production"
ENV NODE_OPTIONS="--max-old-space-size=8192"
ENV DATABASE_URL=${DATABASE_URL}

COPY . .

RUN yarn install
RUN yarn workspace @calcom/api-v2 run generate-schemas
RUN yarn workspace @calcom/api-v2 run build:docker
RUN yarn workspace @calcom/api-v2 run build

EXPOSE 80

CMD ["yarn", "workspace", "@calcom/api-v2", "start:prod"]

Environment Variables

Runtime Variables

These must be set in your .env file:

# Database
DATABASE_URL="postgresql://unicorn_user:magical_password@database:5432/calendso"
DATABASE_HOST="database"
POSTGRES_USER="unicorn_user"
POSTGRES_PASSWORD="magical_password"
POSTGRES_DB="calendso"

# Redis
REDIS_URL="redis://redis:6379"
REDIS_PORT=6379

# Application
NEXT_PUBLIC_WEBAPP_URL="http://localhost:3000"
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="your-secret-here"
CALENDSO_ENCRYPTION_KEY="your-encryption-key"

# VAPID (Push Notifications)
NEXT_PUBLIC_VAPID_PUBLIC_KEY="your-public-key"
VAPID_PRIVATE_KEY="your-private-key"

# API v2
API_PORT=80
API_URL="http://calcom-api:80"
NEXT_PUBLIC_API_V2_URL="http://localhost:5555/api/v2"

# License (optional)
CALCOM_LICENSE_KEY="your-license-key"

Build-time Arguments

For custom builds, pass these arguments:

docker build \
  --build-arg NEXT_PUBLIC_WEBAPP_URL=https://cal.yourdomain.com \
  --build-arg NEXTAUTH_SECRET=$(openssl rand -base64 32) \
  --build-arg CALENDSO_ENCRYPTION_KEY=$(openssl rand -base64 24) \
  --build-arg DATABASE_URL=$DATABASE_URL \
  --build-arg MAX_OLD_SPACE_SIZE=8192 \
  --build-arg CALCOM_TELEMETRY_DISABLED=1 \
  -t calcom-custom:latest .

Startup Process

The scripts/start.sh handles initialization:

#!/bin/sh
set -x

# Replace build-time URL with runtime URL if different
scripts/replace-placeholder.sh "$BUILT_NEXT_PUBLIC_WEBAPP_URL" "$NEXT_PUBLIC_WEBAPP_URL"

# Wait for database
scripts/wait-for-it.sh ${DATABASE_HOST} -- echo "database is up"

# Run migrations
npx prisma migrate deploy --schema /calcom/packages/prisma/schema.prisma

# Seed app store
npx ts-node --transpile-only /calcom/scripts/seed-app-store.ts

# Start application
yarn start

Initialization Steps

URL Replacement: Updates static files if NEXT_PUBLIC_WEBAPP_URL changed
Database Wait: Ensures PostgreSQL is ready
Migrations: Applies pending database migrations
App Store Seed: Syncs app metadata
Application Start: Launches Next.js server

Migrations run automatically on every container start. This is safe and idempotent.

Docker Compose Usage

Running Services

# All services (database + redis + calcom + api + studio)
docker compose up -d

# Web application only (requires external database)
docker compose up -d calcom

# Web + API (requires external database and redis)
docker compose up -d calcom calcom-api

# With Prisma Studio
docker compose up -d calcom studio

# View logs
docker compose logs -f calcom

# Stop services
docker compose down

# Stop and remove volumes (⚠️ deletes data)
docker compose down -v

Updating Images

# Pull latest images
docker compose pull

# Rebuild custom images
docker compose build --no-cache

# Restart with new images
docker compose up -d

Scaling Services

# Run multiple Cal.com instances
docker compose up -d --scale calcom=3

# Requires load balancer configuration

Custom Docker Builds

Building from Source

# Clone repository
git clone https://github.com/calcom/cal.com.git
cd cal.com

# Start database for build
docker compose up -d database

# Build image
DOCKER_BUILDKIT=0 docker compose build calcom

# Run custom image
docker compose up -d

DOCKER_BUILDKIT=0 is required to enable network bridge during build. This limitation may be removed in future versions.

Custom Dockerfile

Create a custom Dockerfile extending the base image:

FROM calcom/cal.com:latest

# Add custom scripts
COPY ./custom-scripts /calcom/custom-scripts
RUN chmod +x /calcom/custom-scripts/*

# Add custom dependencies
RUN yarn add custom-package

# Override start command
CMD ["/calcom/custom-scripts/start.sh"]

Multi-platform Builds

# Build for multiple architectures
docker buildx create --use
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t calcom-custom:latest \
  --push .

ARM Architecture

ARM Images

For Apple Silicon, Raspberry Pi, and ARM servers:

# Pull ARM-specific image
docker pull calcom/cal.com:v5.6.19-arm

# Update docker-compose.yml
services:
  calcom:
    image: calcom/cal.com:v5.6.19-arm

Building for ARM

docker build --platform linux/arm64 -t calcom-arm:latest .

Volumes and Persistence

Default Volumes

volumes:
  database-data:    # PostgreSQL data
  redis-data:       # Redis persistence

Backup Volumes

# Backup database volume
docker run --rm \
  -v cal_database-data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/database-backup.tar.gz -C /data .

# Restore database volume
docker run --rm \
  -v cal_database-data:/data \
  -v $(pwd):/backup \
  alpine tar xzf /backup/database-backup.tar.gz -C /data

Inspect Volumes

# List volumes
docker volume ls

# Inspect volume
docker volume inspect cal_database-data

# Remove unused volumes
docker volume prune

Networks

Default Network

networks:
  stack:
    name: stack
    external: false

All services communicate on the stack network.

Custom Networks

networks:
  frontend:
    name: frontend
  backend:
    name: backend

services:
  calcom:
    networks:
      - frontend
      - backend
  
  database:
    networks:
      - backend

Health Checks

Built-in Health Check

The Dockerfile includes automatic health monitoring:

HEALTHCHECK --interval=30s --timeout=30s --retries=5 \
  CMD wget --spider http://localhost:3000 || exit 1

Custom Health Checks

services:
  calcom:
    healthcheck:
      test: ["CMD", "wget", "--spider", "http://localhost:3000/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

Check Health Status

# View health status
docker ps

# Inspect health
docker inspect --format='{{.State.Health.Status}}' calcom

# View health logs
docker inspect --format='{{json .State.Health}}' calcom | jq

Production Optimizations

Resource Limits

services:
  calcom:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G
        reservations:
          cpus: '1'
          memory: 2G

Restart Policies

services:
  calcom:
    restart: unless-stopped  # or 'always', 'on-failure'

Logging Configuration

services:
  calcom:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

Read-only Root Filesystem

services:
  calcom:
    read_only: true
    tmpfs:
      - /tmp
      - /calcom/.next/cache

Troubleshooting

View Logs

# All services
docker compose logs

# Specific service
docker compose logs calcom

# Follow logs
docker compose logs -f calcom

# Last 100 lines
docker compose logs --tail=100 calcom

Container Shell Access

# Access running container
docker exec -it calcom sh

# Run one-off command
docker compose run --rm calcom sh

Database Connection Issues

# Test database from container
docker exec calcom wget --spider database:5432 || echo "Cannot reach database"

# Check database logs
docker compose logs database

# Test connection string
docker exec calcom npx prisma db pull --schema /calcom/packages/prisma/schema.prisma

Port Conflicts

Error: Bind for 0.0.0.0:3000 failed: port is already allocated

Solution: Change port mapping:

ports:
  - "3001:3000"  # Host:Container

Out of Memory

JavaScript heap out of memory

Solution: Increase memory:

environment:
  - NODE_OPTIONS=--max-old-space-size=8192

Migration Failures

# Check migration status
docker exec calcom npx prisma migrate status \
  --schema /calcom/packages/prisma/schema.prisma

# Manual migration
docker exec calcom npx prisma migrate deploy \
  --schema /calcom/packages/prisma/schema.prisma

Security Best Practices

Secret Management

# Use Docker secrets (Swarm mode)
secrets:
  db_password:
    file: ./secrets/db_password.txt

services:
  calcom:
    secrets:
      - db_password
    environment:
      - DATABASE_URL=postgresql://user:file:///run/secrets/db_password@db:5432/calendso

Non-root User

Modify Dockerfile to run as non-root:

RUN addgroup -g 1001 calcom && \
    adduser -D -u 1001 -G calcom calcom

USER calcom

Network Isolation

networks:
  frontend:
    internal: false
  backend:
    internal: true  # No external access

Remove Development Tools

# Don't expose Prisma Studio in production
services:
  studio:
    profiles:
      - development

# Run only production profile
# docker compose --profile production up -d

Monitoring and Observability

Prometheus Metrics

Expose metrics endpoint:

services:
  calcom:
    labels:
      prometheus.scrape: "true"
      prometheus.port: "3000"
      prometheus.path: "/api/metrics"

Container Stats

# Real-time stats
docker stats calcom

# All containers
docker compose stats

Production Checklist

Next Steps

Configure Environment Variables
Set up Database with connection pooling
Review Deployment for orchestration options

​Overview

​Docker Compose Services

​Service Architecture

​Database Service

​Redis Service

​Cal.com Web Service

​API v2 Service

​Prisma Studio (Development)

​Dockerfile Deep Dive

​Main Application Dockerfile

​Stage 1: Builder

​Stage 2: Builder-Two

​Stage 3: Runner

​API v2 Dockerfile

​Environment Variables

​Runtime Variables

​Build-time Arguments

​Startup Process

​Initialization Steps

​Docker Compose Usage

​Running Services

​Updating Images

​Scaling Services

​Custom Docker Builds

​Building from Source

​Custom Dockerfile

​Multi-platform Builds

​ARM Architecture

​ARM Images

​Building for ARM

​Volumes and Persistence

​Default Volumes

​Backup Volumes

​Inspect Volumes

​Networks

​Default Network

​Custom Networks

​Health Checks

​Built-in Health Check

​Custom Health Checks

​Check Health Status

​Production Optimizations

​Resource Limits

​Restart Policies

​Logging Configuration

​Read-only Root Filesystem

​Troubleshooting

​View Logs

​Container Shell Access

​Database Connection Issues

​Port Conflicts

​Out of Memory

​Migration Failures

​Security Best Practices

​Secret Management

​Non-root User

​Network Isolation

​Remove Development Tools

​Monitoring and Observability

​Prometheus Metrics

​Container Stats

​Production Checklist

​Next Steps

Overview

Docker Compose Services

Service Architecture

Database Service

Redis Service

Cal.com Web Service

API v2 Service

Prisma Studio (Development)

Dockerfile Deep Dive

Main Application Dockerfile

Stage 1: Builder

Stage 2: Builder-Two

Stage 3: Runner

API v2 Dockerfile

Environment Variables

Runtime Variables

Build-time Arguments

Startup Process

Initialization Steps

Docker Compose Usage

Running Services

Updating Images

Scaling Services

Custom Docker Builds

Building from Source

Custom Dockerfile

Multi-platform Builds

ARM Architecture

ARM Images

Building for ARM

Volumes and Persistence

Default Volumes

Backup Volumes

Inspect Volumes

Networks

Default Network

Custom Networks

Health Checks

Built-in Health Check

Custom Health Checks

Check Health Status

Production Optimizations

Resource Limits

Restart Policies

Logging Configuration

Read-only Root Filesystem

Troubleshooting

View Logs

Container Shell Access

Database Connection Issues

Port Conflicts

Out of Memory

Migration Failures

Security Best Practices

Secret Management

Non-root User

Network Isolation

Remove Development Tools

Monitoring and Observability

Prometheus Metrics

Container Stats

Production Checklist

Next Steps