Héberger Cal.com sur votre propre VPS

Cal.com est une application Next.js adossée à PostgreSQL qui gère la planification de rendez-vous, les types d'événements, les disponibilités et la synchronisation avec les calendriers (Google, CalDAV, Office 365). L'auto-hébergement répond à un besoin précis : maîtriser les données de disponibilité et de prise de rendez-vous de vos clients, qui transitent normalement par un service tiers américain. Sur VPS, vous éliminez les limites du plan gratuit (un seul type d'événement, marque imposée), vous branchez vos propres clés d'API Google/visio et vous intégrez le widget de réservation directement dans votre site sous votre domaine. Comme Cal.com est une application Node persistante avec base de données et build de production, elle exige un VPS — un mutualisé ne peut ni faire tourner le processus ni héberger PostgreSQL.

Cal.com est plus exigeant que la moyenne du self-hosting à cause de son socle Next.js et de l'étape de build. Prévoyez 2 vCPU, 4 Go de RAM et 20 Go de disque pour une instance d'équipe confortable ; 2 Go de RAM peuvent suffire pour un usage individuel mais le build initial est plus serré. Il faut Docker et Docker Compose, une base PostgreSQL (incluse dans le compose officiel), un domaine rdv.votredomaine.com pointé vers le VPS, et plusieurs variables d'environnement obligatoires : NEXTAUTH_SECRET, CALENDSO_ENCRYPTION_KEY (clés générées aléatoirement) et NEXT_PUBLIC_WEBAPP_URL réglée sur votre URL HTTPS finale. Pour la synchro agenda et la visio, prévoyez les identifiants OAuth Google.

Trois variables d'environnement sont figées définitivement au premier démarrage de Cal.com. Les modifier après coup corrompt silencieusement toutes les intégrations stockées : l'application redémarre normalement, affiche zéro erreur, mais Google Calendar, Zoom et toutes les connexions OAuth cessent de fonctionner — leurs tokens sont chiffrés avec la clé d'origine, désormais incompatible. Ce comportement est documenté dans calcom/docker issue #333 et calcom/cal.diy issue #13290 : des utilisateurs ont perdu toutes leurs intégrations après une mise à jour qui avait régénéré le fichier .env.

CALENDSO_ENCRYPTION_KEY — chiffre les tokens OAuth stockés en base. Toute modification invalide silencieusement toutes les intégrations existantes.

NEXTAUTH_URL — ancre les cookies de session. Un changement casse l'authentification pour tous les utilisateurs actifs.

NEXT_PUBLIC_WEBAPP_URL — intégrée dans les builds Next.js lors de la compilation. Changer cette valeur exige un rebuild complet et une reconnexion de toutes les intégrations.

Bonne pratique : copiez ces trois valeurs dans un gestionnaire de secrets (Bitwarden, HashiCorp Vault, Ansible Vault) dès leur génération. Si vous gérez votre VPS en infrastructure-as-code, stockez-les dans un vault chiffré — ne laissez jamais le fichier .env être leur seul emplacement.

Intégrations perdues après une mise à jour — La cause est presque toujours une CALENDSO_ENCRYPTION_KEY différente entre deux démarrages. Vérifiez que votre .env n'a pas été écrasé par un .env.example lors du pull. Comparez la valeur actuelle avec celle dans votre gestionnaire de secrets. Si les valeurs diffèrent : restaurez la base PostgreSQL, remettez l'ancienne clé dans le .env et relancez avec docker compose up -d.

Build « JavaScript heap out of memory » — Le compilateur Next.js manque de RAM. Solution : fallocate -l 2G /swapfile && mkswap /swapfile && swapon /swapfile, puis relancez docker compose build. Sur un VPS à 2 Go, le swap est souvent indispensable pour le premier build et les mises à jour majeures. Pensez à retirer le fichier swap une fois le build terminé.

Redirect loop ou « Unable to find valid origin » — NEXT_PUBLIC_WEBAPP_URL ne correspond pas à l'URL réelle. Vérifiez que cette variable est bien https://rdv.votredomaine.com (sans barre oblique finale, avec le bon domaine et le bon protocole HTTPS), que le reverse proxy ne modifie pas l'en-tête Host, puis relancez avec docker compose up -d --build pour forcer un rebuild avec la bonne URL.