Docker Overview

Purpose and Scope

The Docker path is the shortest self-hosting workflow for Cal.diy when you want the application, its supporting services, and the first-run setup experience to come up from a compose stack rather than from a local source build. The Docker documentation presents this route as a repository-based flow: clone the Cal.diy repository, prepare an environment file, optionally pull images, and start the services with Docker Compose. It also makes clear that the published image is available from Docker Hub and that ARM users should choose image tags with the ARM suffix when pulling platform-specific builds.

Sources: apps/docs/content/docker.mdx

Docker should be treated as a self-hosting deployment workflow, not as a managed service. The docs place Docker in the main documentation spine after installation, database migrations, and upgrading, and before the apps and deployments areas. That ordering is useful for readers: understand baseline installation concepts first, use Docker for a runnable stack, then continue into app credentials or cloud deployment details as needed. In practice, the Docker page gives the core boot sequence while the neighboring docs explain migrations, upgrades, provider setup, and cloud-specific hosting choices.

Sources: apps/docs/content/_meta.ts, apps/docs/content/docker.mdx

Relevant Source Files

• apps/docs/content/docker.mdx — Primary Docker self-hosting guide, including image location, requirements, first-run commands, update flow, build-time and run-time variable categories, and troubleshooting notes.
• apps/docs/content/_meta.ts — Places Docker in the documentation navigation alongside installation, database migrations, upgrading, apps, and deployments.
• apps/docs/content/apps/_meta.ts — Lists the integration setup pages that typically become relevant after the Docker instance is running.
• apps/docs/content/apps/daily.mdx — Shows an example of a post-Docker integration that is enabled by adding provider credentials to the environment file.
• apps/docs/content/apps/google.mdx — Documents Google Calendar credentials, redirect URIs, and app-store seeding steps that depend on a reachable Cal.diy URL.
• apps/docs/content/apps/hubspot.mdx — Documents another OAuth integration whose callback URL must match the hosted Cal.diy base URL.

Requirements and Image Model

The required local tools are intentionally small: Docker and the modern Docker Compose command. The docs explicitly use the space-separated Compose invocation rather than the older hyphenated command, matching the current Docker documentation convention. The official image name is published under the Cal.com Docker Hub namespace for Cal.diy, and the page calls out an ARM-specific tag suffix for users on ARM hosts. That distinction matters on small servers, home-lab machines, and ARM cloud instances because using an incompatible image tag can fail before Cal.diy itself has a chance to start.

Sources: apps/docs/content/docker.mdx

The Docker configuration is described as officially maintained in the main Cal.diy repository, with the Dockerfile and compose file located at the repository root. For operators, that means the compose workflow is not a detached sample; it is part of the main project’s self-hosting surface. For contributors, it also gives the right feedback path: issues and pull requests should target the main repository when the Docker setup, service composition, or image behavior needs correction. The Docker docs therefore serve both end users starting an instance and maintainers improving the container workflow.

Sources: apps/docs/content/docker.mdx

Getting Started Flow

A first run begins by cloning the repository and entering the checkout. From there, the required preparation step is to copy the example environment file into the active environment file and edit it for the target host. The docs say most configurations can be left as they are for a basic run, but they still direct the reader to update appropriate values before continuing. This is important because the same compose commands support a local evaluation stack and a more realistic self-hosted deployment, and both modes depend on consistent environment configuration.

Sources: apps/docs/content/docker.mdx

git clone https://github.com/calcom/cal.diy.git
cd cal.diy
cp .env.example .env

After configuration, the optional pre-pull step downloads the images before starting services. This can make the first startup easier to reason about because image download failures happen before container startup, database initialization, or web application boot. The basic first-run command starts the complete stack, which the docs describe as including a local Postgres database, the Cal.diy web app, and Prisma Studio. Once the stack is up, the operator opens the browser at the local web address or the configured public web application URL, then completes the setup wizard and creates the first user.

Sources: apps/docs/content/docker.mdx

docker compose pull
docker compose up -d

Compose Service Choices

The Docker guide documents three practical startup modes. The full stack is the default for most basic users and first-run evaluation because it includes the local database alongside the application and Prisma Studio. A second mode starts only the Cal.diy web app and Prisma Studio against a remote database, provided that the database connection string points to an available database. A third mode starts only the Cal.diy web app, also against a remote database. These modes let operators gradually move from local all-in-one testing to externalized database infrastructure without changing the overall Docker entrypoint.

Sources: apps/docs/content/docker.mdx

docker compose up -d
docker compose up -d calcom studio
docker compose up -d calcom

Choose the mode based on where data should live and how much operational visibility is needed during setup. For a new evaluation, the complete stack reduces prerequisites because it includes Postgres. For a self-hosted server that already has managed database infrastructure, the remote-database variants avoid running a local database container. Prisma Studio is useful when included because it gives database inspection during setup and troubleshooting, but the web-only command is the smaller runtime footprint. In all remote-database cases, the environment must already contain a working database URL before the compose command is run.

Sources: apps/docs/content/docker.mdx

Configuration and Integrations

The Docker page separates build-time variables from important run-time variables. Build-time variables include the telemetry key, license consent setting, and public web application URL, and the docs warn that changing these for production can require building and publishing a custom image. The important run-time variable called out directly is the authentication secret. For a basic evaluation, the page says most values can remain unchanged, but production-like hosting should be planned around stable public URLs, secret management, and the difference between image build configuration and container runtime configuration.

Sources: apps/docs/content/docker.mdx

App integrations usually come after the Docker stack is reachable, because many providers require credentials, redirect URLs, or environment values that reference the hosted Cal.diy URL. The apps navigation lists providers such as Google, Daily, and HubSpot. Daily is enabled by copying an API key into the environment file, with an optional scale-plan flag for features such as recording. Google requires OAuth credentials, specific Calendar scopes, redirect URIs for calendar and authentication callbacks, and app-store repopulation after credentials are added. HubSpot similarly requires client credentials, a callback URL, and contact-related scopes.

Sources: apps/docs/content/apps/_meta.ts, apps/docs/content/apps/daily.mdx, apps/docs/content/apps/google.mdx, apps/docs/content/apps/hubspot.mdx

Updating and Troubleshooting Signals

The update flow is intentionally compact: stop the compose stack, pull newer images, and restart the stack. The docs also remind operators to update environment variables as necessary, which is a small but important detail. New images may introduce changed configuration expectations, and old environment files can become the hidden cause of startup or authentication problems. Because Docker deployments often persist data outside the web container, the safe mental model is to treat image updates, environment review, and database state as a single maintenance task rather than three unrelated chores.

Sources: apps/docs/content/docker.mdx

docker compose down
docker compose pull
docker compose up -d

The Docker troubleshooting notes identify two concrete classes of failure. User creation can fail in some versions if an empty metadata field is submitted incorrectly; the documented workaround is to use an empty JSON object for metadata or leave the auto-incrementing identifier empty. The SSL edge termination note applies when a load balancer handles certificates and backend requests are rejected, but the docs frame the related environment variable as something to use only when the operator understands and trusts the proxy path. A client fetch authentication error can also indicate that container DNS cannot resolve the same base URL seen by the browser.

Sources: apps/docs/content/docker.mdx

Next Steps

After the first Docker boot, continue according to the problem you are solving. If you are preparing a long-running instance, read the Docker configuration and update guidance next so build-time and run-time variables are not mixed together. If the instance will be placed behind a public domain, review URL, SSL, and reverse-proxy guidance before enabling OAuth providers. If the goal is calendar, video, CRM, messaging, or payment support, move into the app integration pages and add credentials deliberately, because provider callback URLs must match the address where the Docker-hosted Cal.diy application is actually reachable.

Sources: apps/docs/content/docker.mdx, apps/docs/content/apps/_meta.ts