API Configuration on Docker Swarm (Portainer)

[otnnek]

I am currently self-hosting a cal.com instance on my VPS using Docker with the attached stack.

I require assistance in configuring the stack to properly start the API. I have reviewed the documentation but was unable to find the necessary details. Could you please advise on what might be missing from this stack?

Thank you in advance for your support.

calcom.yml

[dosubot[bot]]

Hi @otnnek! I'm Dosu and I’m helping the cal.com team.

To get Cal.com API running smoothly on Docker Swarm (Portainer), make sure your stack includes these essentials:

• Services for the API, database (Postgres), and Redis, with correct depends_on relationships and port mappings (API usually exposes port 5555 or 3001) example.
• Critical environment variables: DATABASE_URL, DATABASE_DIRECT_URL, REDIS_URL, NEXTAUTH_SECRET, CALENDSO_ENCRYPTION_KEY, CALCOM_LICENSE_KEY, ALLOWED_HOSTNAMES, and RESERVED_SUBDOMAINS (for routing/subdomain recognition). These must be set either in your stack file or via an .env mounted in the API container reference.
• The .env file must be accessible in the working directory where the API process starts, or all required variables must be set in the environment block reference.
• For API v2, REDIS_URL and CALCOM_LICENSE_KEY are mandatory—missing these will prevent the API from starting and listening on its port reference.
• If you use self-signed TLS certificates, mount the certificate and set NODE_EXTRA_CA_CERTS in the API container to avoid certificate errors reference.
• If API requests return HTML instead of JSON, check your routing—requests may be hitting the frontend instead of the API backend. Make sure your port mappings and proxy rules are correct reference.

If you’re still stuck, check the API container logs for errors and verify all required environment variables are present. If you can share your actual calcom.yml contents or error logs, I can help pinpoint what’s missing or misconfigured.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[otnnek]

Perfect @dosu I'll double check the information. This is my yml file.
calcom.yml

[dosubot[bot]]

I can't directly access the contents of your calcom.yml file, but here’s a checklist to help you audit your Docker Swarm stack for Cal.com API:

• Make sure you have services for the API, Postgres, and Redis, with correct depends_on relationships and port mappings (API usually exposes port 80 internally, mapped to something like 5555 or 3001 on the host) (example).
• Set all required environment variables: DATABASE_URL, DATABASE_DIRECT_URL, REDIS_URL, NEXTAUTH_SECRET, CALENDSO_ENCRYPTION_KEY, CALCOM_LICENSE_KEY, ALLOWED_HOSTNAMES (hostnames only, no protocol), and RESERVED_SUBDOMAINS (reference).
• For API v2, both REDIS_URL and CALCOM_LICENSE_KEY are mandatory—missing either will prevent the API from starting (reference).
• If you use self-signed TLS certificates, mount the certificate and set NODE_EXTRA_CA_CERTS in the API container (reference).
• If API requests return HTML instead of JSON, check your routing—requests may be hitting the frontend instead of the API backend. Make sure your port mappings and proxy rules are correct (reference).
• The .env file must be accessible in the working directory where the API process starts, or all required variables must be set in the environment block (reference).

If you want to share the actual contents of your calcom.yml file (as text), I can give more targeted feedback!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[otnnek]

For sure @dosu

version: "3.8"

services:
  calcom:
    image: calcom/cal.com:v5.6.13

    networks:
      - app_network
      - traefik_public

    environment:
      - NEXT_PUBLIC_LICENSE_CONSENT=agree
      - LICENSE=agree

      - CALCOM_LICENSE_KEY=MY_LICENCE_KEY

      - NEXT_PUBLIC_WEBAPP_URL=https://agenda.otnnek.com

      - NEXT_PUBLIC_API_V2_URL=https://agenda.otnnek.com/api/v2

      - BASE_URL=https://agenda.otnnek.com
      - NEXTAUTH_URL=https://agenda.otnnek.com
      - NEXT_PUBLIC_CONSOLE_URL=https://agenda.otnnek.com
      - NEXT_PUBLIC_APP_URL=https://agenda.otnnek.com
      - NEXT_PUBLIC_WEBSITE_URL=https://agenda.otnnek.com
      - WEB_APP=https://agenda.otnnek.com

      - NEXT_PUBLIC_APP_NAME="Otnnek Agenda"
      - NEXT_PUBLIC_SUPPORT_MAIL_ADDRESS="[email protected]"
      - NEXT_PUBLIC_COMPANY_NAME="Otnnek"

      - NEXTAUTH_SECRET=MY_SECRET_KEY
      - CALENDSO_ENCRYPTION_KEY=MY_SECRET_KEY

      - DATABASE_URL=postgresql://app_user:password@postgres:5432/calcom_database
      - DATABASE_DIRECT_URL=postgresql://app_user:password@postgres:5432/calcom_database

      - [email protected]
      - EMAIL_SERVER_HOST=smtp.gmail.com
      - EMAIL_SERVER_PORT=587
      - [email protected]
      - EMAIL_SERVER_PASSWORD=password

      - NODE_ENV=production

      - NEXT_PUBLIC_DISABLE_SIGNUP=true

    deploy:
      mode: replicated
      replicas: 1
      placement:
        constraints:
          - node.role == manager
      labels:
        - traefik.enable=true
        - traefik.swarm.network=traefik_public
        - traefik.http.routers.calcom.rule=Host(`agenda.otnnek.com`)
        - traefik.http.routers.calcom.entrypoints=websecure
        - traefik.http.routers.calcom.tls.certresolver=letsencrypt
        - traefik.http.services.calcom.loadbalancer.server.port=3000

networks:
  app_network:
    external: true
  traefik_public:
    external: true

[dosubot[bot]]

Your stack is missing a few critical pieces for Cal.com API v2 to start and work correctly:

• You need to add a Redis service and set the REDIS_URL environment variable (e.g. REDIS_URL=redis://redis:6379). Redis is mandatory for API v2—without it, the API won't start or listen on its port [source].
• Add ALLOWED_HOSTNAMES (e.g. ALLOWED_HOSTNAMES="agenda.otnnek.com") to your environment variables. This must be a comma-separated list of hostnames (no protocol) [source].
• If you use a subdomain that matches a reserved word (like "booking" or "api"), set RESERVED_SUBDOMAINS to avoid 404s (e.g. RESERVED_SUBDOMAINS="agenda" if needed) [source].
• The CALENDSO_ENCRYPTION_KEY should be exactly 24 characters (use openssl rand -base64 24) to avoid encryption errors [source].
• The Traefik label traefik.http.services.calcom.loadbalancer.server.port is set to 3000, but API v2 listens on 5555 by default. Make sure this matches the actual port your API is exposing [source].

You should also ensure you have a Postgres service running and that DATABASE_URL points to it. If you already have external Redis and Postgres services, just set the correct URLs.

Once you add these, the API should start and be reachable. If you still have issues, check the container logs for missing environment variables or startup errors.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[otnnek]

I followed your tips @dosu , but it’s still not working. You can find my updated YAML below. The domain agenda.otnnek.com is working, but the API is not.

version: "3.8"

services:
  redis:
    image: redis:7
    networks:
      - app_network

  calcom-api:
    image: calcom/cal.com:v5.6.13
    depends_on:
      - redis
    environment:
      # Database & Redis (externo)
      DATABASE_URL: postgresql://app_user:000@postgres:5432/calcom_database
      DATABASE_DIRECT_URL: postgresql://app_user:000@postgres:5432/calcom_database
      REDIS_URL: redis://redis:6379

      # Auth & Encryption
      NEXTAUTH_SECRET: 0000
      CALENDSO_ENCRYPTION_KEY: 0000

      # URLs
      BASE_URL: https://agenda.otnnek.com
      NEXTAUTH_URL: https://agenda.otnnek.com
      NEXT_PUBLIC_API_V2_URL: https://agenda.otnnek.com/api/v2
      NEXT_PUBLIC_WEBAPP_URL: https://agenda.otnnek.com
      NEXT_PUBLIC_APP_URL: https://agenda.otnnek.com
      NEXT_PUBLIC_WEBSITE_URL: https://agenda.otnnek.com
      NEXT_PUBLIC_CONSOLE_URL: https://agenda.otnnek.com

      # Email
      EMAIL_FROM: [email protected]
      EMAIL_SERVER_HOST: smtp.gmail.com
      EMAIL_SERVER_PORT: 587
      EMAIL_SERVER_USER: [email protected]
      EMAIL_SERVER_PASSWORD: 000

      # License
      CALCOM_LICENSE_KEY: 0000
      CAL_SIGNATURE_TOKEN: 0000

      NODE_ENV: production

    networks:
      - app_network
      - traefik_public
    deploy:
      replicas: 1
      labels:
        - traefik.enable=true
        - traefik.docker.network=traefik_public
        - traefik.http.routers.calcomapi.rule=Host(`agenda.otnnek.com`) && PathPrefix(`/api/v2`)
        - traefik.http.routers.calcomapi.entrypoints=websecure
        - traefik.http.routers.calcomapi.tls.certresolver=letsencrypt
        - traefik.http.routers.calcomapi.priority=20
        - traefik.http.services.calcomapi.loadbalancer.server.port=5555

  calcom-web:
    image: calcom/cal.com:v5.6.13
    depends_on:
      - calcom-api
      - redis
    environment:
      # Database & Redis (replicado)
      DATABASE_URL: postgresql://app_user:000@postgres:5432/calcom_database
      DATABASE_DIRECT_URL: postgresql://app_user:000@postgres:5432/calcom_database
      REDIS_URL: redis://redis:6379

      # Auth & Encryption
      NEXTAUTH_SECRET: 000
      CALENDSO_ENCRYPTION_KEY: 000

      # URLs
      BASE_URL: https://agenda.otnnek.com
      NEXTAUTH_URL: https://agenda.otnnek.com
      NEXT_PUBLIC_API_V2_URL: https://agenda.otnnek.com/api/v2
      NEXT_PUBLIC_WEBAPP_URL: https://agenda.otnnek.com
      NEXT_PUBLIC_APP_URL: https://agenda.otnnek.com
      NEXT_PUBLIC_WEBSITE_URL: https://agenda.otnnek.com
      NEXT_PUBLIC_CONSOLE_URL: https://agenda.otnnek.com

      # Email
      EMAIL_FROM: [email protected]
      EMAIL_SERVER_HOST: smtp.gmail.com
      EMAIL_SERVER_PORT: 587
      EMAIL_SERVER_USER: [email protected]
      EMAIL_SERVER_PASSWORD: 000

      # License
      CALCOM_LICENSE_KEY: 000
      CAL_SIGNATURE_TOKEN: 000

      NODE_ENV: production

    networks:
      - app_network
      - traefik_public
    deploy:
      replicas: 1
      labels:
        - traefik.enable=true
        - traefik.docker.network=traefik_public
        - traefik.http.routers.calcom.rule=Host(`agenda.otnnek.com`) && PathPrefix(`/`)
        - traefik.http.routers.calcom.entrypoints=websecure
        - traefik.http.routers.calcom.tls.certresolver=letsencrypt
        - traefik.http.routers.calcom.priority=10
        - traefik.http.services.calcom.loadbalancer.server.port=3000

networks:
  app_network:
    external: true
  traefik_public:
    external: true

Can you review and give me a right yml?