> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trymondo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Calcom

## Overview

Cal.com is a scheduling and appointment management system integrated into the Mondo MOPS ecosystem. It provides a robust solution for managing appointments, scheduling meetings, and coordinating availability across team members. In the MOPS platform, Cal.com serves as the central scheduling infrastructure, accessible via its own subdomain.

<Note>
  Cal.com was formerly known as Calendly and provides similar functionality with
  additional features for self-hosting and customization.
</Note>

## Architecture

Cal.com in the MOPS stack consists of:

* **Cal.com Application Container**: The main application serving the web interface
* **PostgreSQL Database**: Stores all scheduling data, accounts, and configuration
* **Traefik Integration**: Handles routing and TLS termination

## Deployment Configuration

### Docker Compose Setup

```yaml theme={null}
services:
  database:
    container_name: calcom-db
    image: postgres:17.4
    restart: unless-stopped
    volumes:
      - ./db:/var/lib/postgresql/data/
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    env_file: .env
    networks:
      - calcom-net
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U ${POSTGRES_USER}']
      interval: 5s
      timeout: 5s
      retries: 5

  calcom:
    image: calcom/cal.com:v5.0.19
    container_name: calcom-app
    restart: unless-stopped
    volumes:
      - ./data:/app/data
    networks:
      - traefik-net
      - calcom-net
    ports:
      - 3000:3000
    env_file: .env
    environment:
      # Database Configuration
      - DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@calcom-db:5432/${POSTGRES_DB}?sslmode=disable
      - DATABASE_DIRECT_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@calcom-db:5432/${POSTGRES_DB}?sslmode=disable
      # Google Calendar Integration
      - GOOGLE_API_CREDENTIALS=${GOOGLE_API_CREDENTIALS}
      # SAML Configuration
      - SAML_DATABASE_URL=${SAML_DATABASE_URL}
      - SAML_ADMINS=${SAML_ADMINS}
      # Security and Auth
      - NEXTAUTH_SECRET=${NEXTAUTH_SECRET}
      - CALENDSO_ENCRYPTION_KEY=${CALENDSO_ENCRYPTION_KEY}
      - NEXTAUTH_URL=https://cal.trymondo.com
      # Application URLs
      - NEXT_PUBLIC_WEBAPP_URL=https://cal.trymondo.com
      - NEXT_PUBLIC_APP_URL=https://cal.trymondo.com
      - NEXT_PUBLIC_API_V2_URL=https://cal.trymondo.com/api/v2
      - WEBAPP_URL=https://cal.trymondo.com
      - APP_URL=https://cal.trymondo.com
      # Hostname Configuration
      - ALLOWED_HOSTNAMES="cal.trymondo.com,trymondo.com,localhost:3000"
      # Email Configuration
      - EMAIL_FROM=info@trymondo.com
      - MAIL_FROM=info@trymondo.com
      # SMTP Configuration
      - SMTP_HOST=smtp.mailersend.net
      - SMTP_PORT=587
      - SMTP_USERNAME=${SMTP_USERNAME}
      - SMTP_PASSWORD=${SMTP_PASSWORD}
      - SMTP_SECURE=false
      - SMTP_AUTH_TYPE=LOGIN
      - SMTP_IGNORE_TLS=false
      # Nodemailer Configuration
      - EMAIL_SERVER_HOST=${SMTP_HOST}
      - EMAIL_SERVER_PORT=587
      - EMAIL_SERVER_USER=${EMAIL_SERVER_USER}
      - EMAIL_SERVER_PASSWORD=${EMAIL_SERVER_PASSWORD}
      # Force SMTP over sendmail
      - EMAIL_TRANSPORT=smtp
      - SENDMAIL_DISABLED=true
      - MAILER_PROVIDER=smtp
      # Debug
      - DEBUG=email:*,nodemailer:*,prisma:*
      - EMAIL_DEBUG=true
      - NODE_TLS_REJECT_UNAUTHORIZED=0
      # Application Settings
      - NEXT_PUBLIC_LICENSE_CONSENT=true
      - CALCOM_TELEMETRY_DISABLED=1
      - NEXT_PUBLIC_IS_E2E=0
      - NEXT_PUBLIC_IS_PREMIUM=true
      - NEXT_PUBLIC_TEAM_IMPERSONATION=false
      - NEXT_DISABLE_IMPERSONATION_PAGE=true
    depends_on:
      - database
    labels:
      - 'traefik.enable=true'
      - 'traefik.http.routers.cal.rule=Host(`cal.trymondo.com`)'
      - 'traefik.http.routers.cal.entrypoints=websecure'
      - 'traefik.http.routers.cal.tls=true'
      - 'traefik.http.routers.cal.tls.certresolver=production'
      - 'traefik.http.services.cal.loadbalancer.server.scheme=http'
      - 'traefik.http.services.cal.loadbalancer.server.port=3000'
      - 'traefik.http.routers.cal.middlewares=cors@file,secureHeaders@file'

networks:
  traefik-net:
    external: true
  calcom-net:
    external: true
```

## Configuration

### Environment Variables

Create a `.env` file in the Cal.com directory with the following variables:

```
# Database Configuration
POSTGRES_USER=your_db_username
POSTGRES_PASSWORD=your_db_password
POSTGRES_DB=calcom

# Security Keys
NEXTAUTH_SECRET=your_random_secret_string
CALENDSO_ENCRYPTION_KEY=your_32_character_key

# Google Calendar (Optional)
GOOGLE_API_CREDENTIALS={"web":{"client_id":"your_client_id","project_id":"your_project_id","auth_uri":"https://accounts.google.com/o/oauth2/auth","token_uri":"https://oauth2.googleapis.com/token","auth_provider_x509_cert_url":"https://www.googleapis.com/oauth2/v1/certs","client_secret":"your_client_secret","redirect_uris":["https://cal.trymondo.com/api/auth/callback/google"],"javascript_origins":["https://cal.trymondo.com"]}}

# SAML Configuration (Optional)
SAML_DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@calcom-db:5432/${POSTGRES_DB}?sslmode=disable
SAML_ADMINS=admin@your-domain.com

# SMTP Configuration
SMTP_USERNAME=your_smtp_username
SMTP_PASSWORD=your_smtp_password
EMAIL_SERVER_USER=your_email_username
EMAIL_SERVER_PASSWORD=your_email_password
```

<Warning>
  Store these credentials securely. The `.env` file contains sensitive
  information that should not be committed to version control.
</Warning>

### Key Configuration Options

| Setting                     | Description                             | Example                         |
| --------------------------- | --------------------------------------- | ------------------------------- |
| `ALLOWED_HOSTNAMES`         | Comma-separated list of valid hostnames | `cal.trymondo.com,trymondo.com` |
| `NEXTAUTH_URL`              | URL for authentication                  | `https://cal.trymondo.com`      |
| `NEXT_PUBLIC_WEBAPP_URL`    | Public-facing URL                       | `https://cal.trymondo.com`      |
| `SMTP_*`                    | Email configuration                     | Settings for your SMTP provider |
| `CALCOM_TELEMETRY_DISABLED` | Disable usage tracking                  | `1`                             |
| `EMAIL_DEBUG`               | Enable email debugging                  | `true` for troubleshooting      |

## Installation and Setup

### Prerequisites

* Docker and Docker Compose installed
* External `traefik-net` network created
* Domain with DNS pointing to your server
* SMTP credentials for email notifications

### Deployment Steps

1. **Create Required Networks**:

   ```bash theme={null}
   docker network create calcom-net
   # Ensure traefik-net exists
   docker network ls | grep traefik-net || docker network create traefik-net
   ```

2. **Prepare Directory Structure**:

   ```bash theme={null}
   mkdir -p /opt/apps/calcom/{db,data}
   cd /opt/apps/calcom
   ```

3. **Create Configuration Files**:

   ```bash theme={null}
   # Create docker-compose.yml using the configuration above
   nano docker-compose.yml

   # Create .env file with required variables
   nano .env
   ```

4. **Deploy the Stack**:

   ```bash theme={null}
   docker compose up -d
   ```

5. **Monitor Initial Startup**:
   ```bash theme={null}
   docker compose logs -f
   ```

### First-Time Setup

Once deployed, complete the setup:

1. Visit `https://cal.trymondo.com`
2. Create the admin account
3. Configure organization settings
4. Set up event types and availability

## Integration with Other MOPS Services

### Authentication

Cal.com can be integrated with Auth0 or other authentication providers:

1. Configure the OAuth provider in your authentication service
2. Add the appropriate callback URLs
3. Update the Cal.com environment variables with the OAuth credentials

### API Integration

Cal.com exposes an API that can be used by other MOPS services:

```bash theme={null}
# Example API endpoint
https://cal.trymondo.com/api/v2/
```

## Maintenance

### Backup and Restore

Cal.com data is stored in two locations:

1. **PostgreSQL Database**: Use Backrest to back up the database volume
2. **Application Data**: The `./data` volume contains uploads and other files

Regular backups should include both components:

```bash theme={null}
# Example backup using docker commands
docker exec calcom-db pg_dump -U ${POSTGRES_USER} ${POSTGRES_DB} > calcom_backup_$(date +%Y%m%d).sql

# Example restore
cat calcom_backup_20250415.sql | docker exec -i calcom-db psql -U ${POSTGRES_USER} ${POSTGRES_DB}
```

### Updates

To update Cal.com:

1. Update the image tag in docker-compose.yml
2. Pull the new image:
   ```bash theme={null}
   docker compose pull
   ```
3. Apply the update:
   ```bash theme={null}
   docker compose up -d
   ```

<Warning>Always create a backup before updating to prevent data loss.</Warning>

## Troubleshooting

### Common Issues

| Issue                      | Solution                                                 |
| -------------------------- | -------------------------------------------------------- |
| Database connection errors | Check PostgreSQL container health and connection string  |
| Email not sending          | Verify SMTP settings and check logs with `DEBUG=email:*` |
| White screen after update  | Check application logs for JavaScript errors             |
| Authentication issues      | Verify `NEXTAUTH_URL` and `NEXTAUTH_SECRET` settings     |

### Checking Logs

```bash theme={null}
# View application logs
docker logs calcom-app

# View database logs
docker logs calcom-db

# Follow logs in real-time
docker logs -f calcom-app
```

### Health Checks

```bash theme={null}
# Check database health
docker exec calcom-db pg_isready -U ${POSTGRES_USER}

# Check application health
curl -kI https://cal.trymondo.com
```

## Performance Tuning

### Resource Allocation

Cal.com performs well with moderate resources:

* Database: 1 CPU, 1GB RAM
* Application: 1-2 CPU, 2GB RAM

For high-traffic instances, consider adding resource constraints to docker-compose.yml:

```yaml theme={null}
services:
  database:
    deploy:
      resources:
        limits:
          memory: 1G
          cpus: '1'
  calcom:
    deploy:
      resources:
        limits:
          memory: 2G
          cpus: '2'
```

## Security Considerations

1. **Database Access**: Limit access to the PostgreSQL database
2. **SMTP Credentials**: Regularly rotate email credentials
3. **API Security**: Monitor API usage and restrict access as needed
4. **Traefik Configuration**: Ensure proper security headers are applied (already configured)

## References

* [Cal.com Documentation](https://cal.com/docs)
* [Cal.com GitHub Repository](https://github.com/calcom/cal.com)
* [PostgreSQL Documentation](https://www.postgresql.org/docs/)

***

This documentation provides a comprehensive guide to deploying, configuring, and maintaining Cal.com within the Mondo MOPS ecosystem. For specific customization needs or advanced features, refer to the official Cal.com documentation.