From bc09954cbd139c29883a7d1c8261eee198ae68f8 Mon Sep 17 00:00:00 2001
From: Pasha Sviderski <me@psviderski.name>
Date: Thu, 17 Sep 2026 16:50:26 +1000
Subject: [PATCH] feat(caddy): mount uncloud API socket for storage module
 (#31)

---
 pkg/client/caddy.go                               | 15 +++++++++++++++
 .../docs/3-concepts/2-ingress/3-managing-caddy.md |  4 ++++
 2 files changed, 19 insertions(+)

diff --git a/pkg/client/caddy.go b/pkg/client/caddy.go
index 616b6dac..2acc0881 100644
--- a/pkg/client/caddy.go
+++ b/pkg/client/caddy.go
@@ -53,6 +53,11 @@ func (cli *Client) NewCaddyDeployment(image, config string, placement api.Placem
 					VolumeName:    "run",
 					ContainerPath: "/run/caddy",
 				},
+				{
+					VolumeName:    "uncloud-api",
+					ContainerPath: "/run/uncloud/api",
+					ReadOnly:      true,
+				},
 			},
 		},
 		Mode:      api.ServiceModeGlobal,
@@ -95,6 +100,16 @@ func (cli *Client) NewCaddyDeployment(image, config string, placement api.Placem
 					CreateHostPath: true,
 				},
 			},
+			// Bind the Uncloud API socket so caddy.storage.uncloud module can use it to store assets in the cluster.
+			{
+				Name: "uncloud-api",
+				Type: api.VolumeTypeBind,
+				BindOptions: &api.BindOptions{
+					// Mount the parent directory that contains the socket so it lets the container see a replacement
+					// socket after the Uncloud daemon restarts (in case it doesn't use a systemd-activated socket).
+					HostPath: "/run/uncloud/api",
+				},
+			},
 		},
 	}
 
diff --git a/website/docs/3-concepts/2-ingress/3-managing-caddy.md b/website/docs/3-concepts/2-ingress/3-managing-caddy.md
index ebfc793f..3c206c72 100644
--- a/website/docs/3-concepts/2-ingress/3-managing-caddy.md
+++ b/website/docs/3-concepts/2-ingress/3-managing-caddy.md
@@ -83,6 +83,7 @@ services:
     image: caddybuilds/caddy-cloudflare:2.10.2
     command: caddy run -c /config/Caddyfile
     environment:
+      # unix// is not a typo. Caddy uses network/address format, not a unix:// URL.
       CADDY_ADMIN: unix//run/caddy/admin.sock
     env_file:
       # Contains CLOUDFLARE_API_TOKEN=xxxxx
@@ -91,6 +92,9 @@ services:
       - /var/lib/uncloud/caddy:/data
       - /var/lib/uncloud/caddy:/config
       - /run/uncloud/caddy:/run/caddy
+      # Required by caddy.storage.uncloud module. Remove this mount if Uncloud cluster storage is not used for Caddy.
+      # Mount the directory, not the socket file, so Caddy sees a replacement socket after the daemon restarts.
+      - /run/uncloud/api:/run/uncloud/api:ro
     x-ports:
       - 80:80@host
       - 443:443@host