From 721a71df086d77879b5bf7b974df218b070cc293 Mon Sep 17 00:00:00 2001
From: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Date: Tue, 31 Mar 2026 00:49:47 -0700
Subject: [PATCH] Add health check to Directus service in Docker Compose
 example

Add a healthcheck configuration to the directus service block and a
section explaining the /server/health and /server/ping endpoints. This
helps users who run other containers that need to wait for Directus.

Fixes directus/docs#331
---
 content/self-hosting/3.deploying.md | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/content/self-hosting/3.deploying.md b/content/self-hosting/3.deploying.md
index 5b6516e2..6cb37231 100644
--- a/content/self-hosting/3.deploying.md
+++ b/content/self-hosting/3.deploying.md
@@ -83,6 +83,13 @@ services:
         condition: service_healthy
       cache:
         condition: service_healthy
+    healthcheck:
+      test: ["CMD-SHELL", "wget --spider -q http://localhost:8055/server/health || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_interval: 5s
+      start_period: 30s
     environment:
       SECRET: "REPLACE_WITH_YOUR_SECRET"
 
@@ -109,3 +116,12 @@ services:
 **Request Other Examples**
 We're keeping this section light for now, but if you need examples for other database providers, let us know!
 ::
+
+## Health Checks
+
+The Docker Compose example above includes health checks for all services. If you run other containers that depend on Directus being ready, use `depends_on` with `condition: service_healthy` to wait for Directus to start accepting requests.
+
+Directus exposes two endpoints for health monitoring:
+
+- `/server/health` - returns detailed health status including database and cache connectivity. Returns a `503` if any dependency is unhealthy (for example, a missing email transport configuration).
+- `/server/ping` - returns `pong` if the HTTP server is running, regardless of dependency status. Use this if you only need to confirm the server is accepting requests.