Docker Updates and Troubleshooting

Purpose and Scope

This page is for operators who already run Cal.diy with Docker Compose and need a safe, repeatable way to update the instance or diagnose Docker-specific failures. The common pattern is to stop the current stack, pull newer images, and start the same services again with the same environment file. The most important constraint is that some values are consumed when the web image is built, while others are passed to services at runtime. Treat environment changes as part of the update, not as an unrelated cleanup task, because stale URLs and missing service secrets can make a fresh container look broken. Sources: apps/docs/content/troubleshooting.mdx

The first-party troubleshooting page places Docker issues beside onboarding, URL, payment, API, and database problems. That organization matters for incident response: Docker is often only the delivery mechanism, while the immediate failure may be a bad public URL, missing API v2 secret, unseeded app store, or integration credential mismatch. Start with the symptom visible in logs or in the browser, then map it back to the service and configuration area. A login redirect to a local address is not fixed by restarting containers alone; an API v2 container exiting at boot needs required environment variables. Sources: apps/docs/content/troubleshooting.mdx, apps/docs/content/_meta.ts

Relevant Source Files

• apps/docs/content/troubleshooting.mdx - Main self-hosting troubleshooting guide, including URL redirect failures, Docker-specific API v2 startup errors, and service environment variables.
• apps/docs/content/_meta.ts - Shows that Docker, upgrading, installation, database migrations, apps, and deployments are first-class documentation topics in the self-hosting docs navigation.
• apps/docs/content/apps/_meta.ts - Lists app integration docs that are frequently checked after a Docker update when calendar, video, CRM, messaging, or payment features appear unavailable.
• apps/docs/content/apps/daily.mdx - Documents Daily video environment configuration, including the required API key and optional scale-plan flag.
• apps/docs/content/apps/google.mdx - Documents Google Calendar OAuth credentials, callback URLs, app-store repopulation, and the related login flag.
• apps/docs/content/apps/hubspot.mdx - Documents HubSpot OAuth client credentials, redirect URL, scopes, and expected booking-to-CRM behavior.

Update Flow

Use the Docker update as a short maintenance window. Stop the stack first so the running containers release ports and database connections cleanly, then pull the latest images, and finally bring the stack back up. If the deployment uses a remote database, keep the service selection consistent with the way the instance normally runs. A full local stack may include the web app, local Postgres database, and Prisma Studio; a remote database deployment may start only the web application and studio, or only the web application. Avoid changing the topology during an update unless you are intentionally migrating databases or services.

docker compose down
docker compose pull
docker compose up -d

Before restarting, inspect the environment file you will actually pass to Compose. The troubleshooting guide calls out that deployed instances can redirect back to localhost when the public application URL variables are not set to the production domain. It also notes a Docker-specific constraint: the public web app URL is a build-time value inlined by Next.js. If that value changes, simply recreating a container may not be enough; rebuild or repull an image built with the correct value. Do not include a trailing slash in the production URL. Sources: apps/docs/content/troubleshooting.mdx

A practical update checklist is: confirm the target image tag, confirm whether the server is using an ARM image variant, save a copy of the current environment, stop the stack, pull, start, and then check logs for each expected service. After the containers start, visit the public base URL, sign in, open a booking page, and test any integrations that matter to your instance. If the first-user setup wizard appears unexpectedly, pause before continuing and verify that the database URL still points to the intended persistent database rather than a newly created or empty one.

Diagnosing CLIENT_FETCH_ERROR and URL Problems

A common Docker-facing browser symptom is a client fetch failure after deployment. The troubleshooting page does not reduce all fetch errors to one cause, but it gives a high-value URL case: redirects and internal links can point to a local development host when the deployment is missing the correct public URL variables. In practice, the same class of misconfiguration can also make browser-side requests target the wrong origin. Verify the canonical application URL first, then restart or rebuild according to whether the changed value is runtime-only or build-time. Sources: apps/docs/content/troubleshooting.mdx

Use this minimal URL configuration as the baseline for a deployed instance:

NEXT_PUBLIC_WEBAPP_URL=https://cal.yourdomain.com
NEXTAUTH_URL=https://cal.yourdomain.com

When investigating, compare three views of the same setting: the checked-in example you copied from, the edited environment file on the server, and the effective environment inside the running container. If the browser still reaches localhost after the file looks correct, assume the image or container was created before the change and rebuild or recreate it. Also check reverse proxy headers and public hostnames on the deployment side, but keep the Docker evidence simple: the application needs to know its externally reachable base URL before browser-visible paths and authentication redirects can be trusted.

API v2 Container Startup Failures

The troubleshooting guide has a dedicated Docker-specific entry for the API v2 service not starting. The symptom is precise: after Compose starts, the web app can still work, but the API service exits immediately or API v2 routes return connection errors. The documented cause is missing environment variables for the API v2 service. These values are passed by the Compose file to the API container, and when a required variable is absent the service throws a missing-environment-variable error during startup. Sources: apps/docs/content/troubleshooting.mdx

Use the API v2 environment block as a startup gate during Docker updates. If the update adds, renames, or tightens validation for service configuration, old environment files can stop a container that previously ran. The documented required values include Redis connectivity, signing secrets, encryption material, and Stripe-related secrets. The guide also distinguishes API and web Stripe names: the API v2 service uses a Stripe API key, while the web app uses the private key naming in the payment troubleshooting section. That distinction prevents operators from copying a web-only variable and expecting the API container to accept it. Sources: apps/docs/content/troubleshooting.mdx

REDIS_URL=redis://redis:6379
JWT_SECRET=your_random_jwt_secret_here
NEXTAUTH_SECRET=your_nextauth_secret_here
CALENDSO_ENCRYPTION_KEY=your_32_character_encryption_key
STRIPE_API_KEY=sk_test_your_stripe_key
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret
WEB_APP_URL=https://cal.yourdomain.com
REDIS_PORT=6379
LOG_LEVEL=warn

App and Integration Checks After Updating

Not every post-update problem is caused by Docker itself. The app documentation navigation groups Google, Microsoft, Zoom, Daily, HubSpot, SendGrid, Stripe, Twilio, and Zoho as integration guides, which is a useful reminder to verify feature-specific credentials after the core containers are healthy. For example, Daily video requires an API key in the environment file and has an optional scale-plan flag. Google Calendar requires OAuth credentials, two authorized redirect URIs, and app-store repopulation after adding credentials. HubSpot requires OAuth client credentials, a callback URL, and contact 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

After a Docker update, test integrations in the order users experience them. First confirm authentication and booking pages, then test calendar connection, then video conferencing, then CRM or payment flows. This sequence separates platform availability from provider-specific setup. If Google Calendar disappears from the app store after credentials are added, the Google guide explicitly points to repopulating the app store with the database seed command. If HubSpot bookings stop creating meetings, confirm the OAuth redirect URL still uses the deployed Cal.diy URL and that the selected scopes include contact read and write access. Sources: apps/docs/content/apps/google.mdx, apps/docs/content/apps/hubspot.mdx

pnpm db-seed

Recovery Checklist and Next Steps

When a Docker update fails, capture logs before repeatedly restarting containers. Identify whether the failing component is the web app, API v2 service, Redis, database, or an external integration callback. Then match the log message to configuration: wrong public URL, missing API v2 secret, absent Redis URL, missing Stripe key, or provider OAuth mismatch. Prefer small, reversible edits to the environment file, followed by a deliberate container recreate or image rebuild when the changed value is known to be build-time. This makes recovery auditable and avoids masking the original failure. Sources: apps/docs/content/troubleshooting.mdx

For next steps, read the Docker overview and Docker configuration pages before changing service topology, then use the API and database troubleshooting page if the API v2 container or migrations are involved. Use the environment and URLs page for redirect and host problems, and the apps pages for provider credentials. If the instance is important, take a database backup before updates, document the exact image tag and environment revision, and rehearse rollback using the previous image or compose configuration rather than relying on memory during an outage.