From a9cebd578f7f5aecd86ed816dbae83ee4841dec6 Mon Sep 17 00:00:00 2001
From: 07rjain <07rjain@users.noreply.github.com>
Date: Fri, 23 Oct 2026 14:20:09 +0000
Subject: [PATCH 1/4] perf(media-server): size direct conversions from the CPUs
 and turn on the shutdown drain in compose

Direct /video/convert work defaulted to one conversion at a time on any machine. The default is now half the usable CPUs (container limit aware), between 1 and 4, and MEDIA_SERVER_MAX_CONCURRENT_DIRECT_CONVERSIONS still overrides it. The compose files set MEDIA_SERVER_SHUTDOWN_GRACE_MS to 25s under a 30s stop_grace_period so main's drain lets active work finish on docker compose stop.
---
 .../lib/audio-levels.integration.test.ts      | 13 +++++++++----
 .../src/__tests__/lib/video-capacity.test.ts  | 16 ++++++++++++++++
 apps/media-server/src/lib/video-capacity.ts   | 19 +++++++++++++++++--
 apps/web/content/docs/self-hosting.mdx        |  9 +++++++++
 docker-compose.coolify.yml                    |  3 +++
 docker-compose.template.yml                   |  3 +++
 docker-compose.yml                            |  3 +++
 7 files changed, 60 insertions(+), 6 deletions(-)
 create mode 100644 apps/media-server/src/__tests__/lib/video-capacity.test.ts

diff --git a/apps/media-server/src/__tests__/lib/audio-levels.integration.test.ts b/apps/media-server/src/__tests__/lib/audio-levels.integration.test.ts
index bd88592b2ca..aa373732385 100644
--- a/apps/media-server/src/__tests__/lib/audio-levels.integration.test.ts
+++ b/apps/media-server/src/__tests__/lib/audio-levels.integration.test.ts
@@ -20,6 +20,7 @@ import { withMediaTransfers } from "../../lib/media-transfer";
 import { processVideo } from "../../lib/media-video";
 import {
 	getActiveDirectVideoProcessCount,
+	getMaxConcurrentDirectVideoProcesses,
 	tryAcquireDirectVideoProcessSlot,
 } from "../../lib/video-capacity";
 
@@ -238,15 +239,19 @@ describe("local audio levels integration", () => {
 		expect(objects.publications()).toBe(0);
 	});
 	test("leaves an occupied conversion slot available to its current owner", async () => {
-		const slot = tryAcquireDirectVideoProcessSlot(() => true);
-		expect(slot).not.toBeNull();
+		// The default slot count follows the CPUs, so occupy every slot.
+		const max = getMaxConcurrentDirectVideoProcesses();
+		const slots = Array.from({ length: max }, () =>
+			tryAcquireDirectVideoProcessSlot(() => true),
+		);
+		expect(slots.every((slot) => slot !== null)).toBe(true);
 		try {
 			const objects = storage();
 			expect(await call()).toEqual({ status: "unchanged", reason: "capacity" });
 			expect(objects.preparations()).toBe(0);
-			expect(getActiveDirectVideoProcessCount()).toBe(1);
+			expect(getActiveDirectVideoProcessCount()).toBe(max);
 		} finally {
-			slot?.release();
+			for (const slot of slots) slot?.release();
 		}
 	});
 	test("cancels optional work on shutdown and releases its processing slot", async () => {
diff --git a/apps/media-server/src/__tests__/lib/video-capacity.test.ts b/apps/media-server/src/__tests__/lib/video-capacity.test.ts
new file mode 100644
index 00000000000..d73be931803
--- /dev/null
+++ b/apps/media-server/src/__tests__/lib/video-capacity.test.ts
@@ -0,0 +1,16 @@
+import { describe, expect, test } from "bun:test";
+import { getDefaultMaxConcurrentDirectVideoProcesses } from "../../lib/video-capacity";
+
+describe("getDefaultMaxConcurrentDirectVideoProcesses", () => {
+	test("keeps one conversion on small machines", () => {
+		expect(getDefaultMaxConcurrentDirectVideoProcesses(1)).toBe(1);
+		expect(getDefaultMaxConcurrentDirectVideoProcesses(2)).toBe(1);
+		expect(getDefaultMaxConcurrentDirectVideoProcesses(0.5)).toBe(1);
+	});
+
+	test("uses half the CPUs, capped at four", () => {
+		expect(getDefaultMaxConcurrentDirectVideoProcesses(4)).toBe(2);
+		expect(getDefaultMaxConcurrentDirectVideoProcesses(8)).toBe(4);
+		expect(getDefaultMaxConcurrentDirectVideoProcesses(32)).toBe(4);
+	});
+});
diff --git a/apps/media-server/src/lib/video-capacity.ts b/apps/media-server/src/lib/video-capacity.ts
index da08f193524..97fbebeb365 100644
--- a/apps/media-server/src/lib/video-capacity.ts
+++ b/apps/media-server/src/lib/video-capacity.ts
@@ -1,3 +1,6 @@
+import os from "node:os";
+import { getContainerCpuLimit } from "./container-cpu";
+
 export interface VideoProcessSlot {
 	release: () => void;
 }
@@ -7,7 +10,19 @@ const configuredMaxDirectVideoProcesses =
 		process.env.MEDIA_SERVER_MAX_CONCURRENT_DIRECT_CONVERSIONS ?? "0",
 		10,
 	) || 0;
-const DEFAULT_MAX_CONCURRENT_DIRECT_VIDEO_PROCESSES = 1;
+const MAX_DEFAULT_DIRECT_VIDEO_PROCESSES = 4;
+
+export function getDefaultMaxConcurrentDirectVideoProcesses(
+	cpuCapacity: number = getContainerCpuLimit() || os.availableParallelism(),
+): number {
+	return Math.max(
+		1,
+		Math.min(MAX_DEFAULT_DIRECT_VIDEO_PROCESSES, Math.floor(cpuCapacity / 2)),
+	);
+}
+
+const defaultMaxDirectVideoProcesses =
+	getDefaultMaxConcurrentDirectVideoProcesses();
 
 let activeDirectVideoProcessCount = 0;
 
@@ -18,7 +33,7 @@ export function getActiveDirectVideoProcessCount(): number {
 export function getMaxConcurrentDirectVideoProcesses(): number {
 	return configuredMaxDirectVideoProcesses > 0
 		? configuredMaxDirectVideoProcesses
-		: DEFAULT_MAX_CONCURRENT_DIRECT_VIDEO_PROCESSES;
+		: defaultMaxDirectVideoProcesses;
 }
 
 export function tryAcquireDirectVideoProcessSlot(
diff --git a/apps/web/content/docs/self-hosting.mdx b/apps/web/content/docs/self-hosting.mdx
index 45219a81bd0..762a91210f6 100644
--- a/apps/web/content/docs/self-hosting.mdx
+++ b/apps/web/content/docs/self-hosting.mdx
@@ -106,6 +106,15 @@ By default, login links are printed to the server logs. To send emails:
    RESEND_FROM_DOMAIN=yourdomain.com
    ```
 
+## Media Server Tuning
+
+The media server converts uploads in parallel based on the CPUs it can use: half the available CPUs, at least 1 and at most 4. It still turns work away when CPU or memory pressure is high. Override this with:
+
+```bash
+MEDIA_SERVER_MAX_CONCURRENT_DIRECT_CONVERSIONS=2   # direct /video/convert requests
+MEDIA_SERVER_MAX_CONCURRENT_VIDEO_PROCESSES=4      # all video jobs
+```
+
 ## Optional Features
 
 ### AI Features
diff --git a/docker-compose.coolify.yml b/docker-compose.coolify.yml
index 539d245f2ec..82743a1519d 100644
--- a/docker-compose.coolify.yml
+++ b/docker-compose.coolify.yml
@@ -46,7 +46,10 @@ services:
   media-server:
     image: 'ghcr.io/capsoftware/cap-media-server:latest'
     restart: unless-stopped
+    stop_grace_period: 30s
     environment:
+      # Finish active work for up to 25s on stop (below stop_grace_period).
+      MEDIA_SERVER_SHUTDOWN_GRACE_MS: '25000'
       PORT: 3456
       MEDIA_SERVER_WEBHOOK_SECRET: '${SERVICE_HEX_32_MEDIASERVER}'
     healthcheck:
diff --git a/docker-compose.template.yml b/docker-compose.template.yml
index 1360b3d8715..37992a0393c 100644
--- a/docker-compose.template.yml
+++ b/docker-compose.template.yml
@@ -55,7 +55,10 @@ services:
       context: ./apps/media-server
       dockerfile: Dockerfile.standalone
     restart: unless-stopped
+    stop_grace_period: 30s
     environment:
+      # Finish active work for up to 25s on stop (below stop_grace_period).
+      MEDIA_SERVER_SHUTDOWN_GRACE_MS: "25000"
       PORT: 3456
       MEDIA_SERVER_WEBHOOK_SECRET: fe337b52749070bb7b5d2c78cff9948439ea73cbc1869ba39d350e6c24db53b1
     ports:
diff --git a/docker-compose.yml b/docker-compose.yml
index 7759c6b638b..bf886a72eac 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -49,7 +49,10 @@ services:
       context: ./apps/media-server
       dockerfile: Dockerfile.standalone
     restart: unless-stopped
+    stop_grace_period: 30s
     environment:
+      # Finish active work for up to 25s on stop (below stop_grace_period).
+      MEDIA_SERVER_SHUTDOWN_GRACE_MS: "25000"
       PORT: 3456
       MEDIA_SERVER_WEBHOOK_SECRET: ${MEDIA_SERVER_WEBHOOK_SECRET:-fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210}
     healthcheck:

From 670383b899aed9a431e0ae970255e781852ece5b Mon Sep 17 00:00:00 2001
From: 07rjain <07rjain@users.noreply.github.com>
Date: Fri, 23 Oct 2026 19:04:52 +0000
Subject: [PATCH 2/4] fix(self-host): give the media server enough stop time
 for drain, cancel webhooks and cleanup

A 25s drain plus webhooks for jobs aborted at shutdown (an in-flight attempt up to 5s, then 3 x 5s with 1.5s backoff) needs 46.5s before cleanup, more than the 30s stop_grace_period, so Docker could SIGKILL mid-cleanup. Raise stop_grace_period to 60s in all three compose files and document the budget.
---
 apps/web/content/docs/self-hosting.mdx | 2 ++
 docker-compose.coolify.yml             | 7 +++++--
 docker-compose.template.yml            | 7 +++++--
 docker-compose.yml                     | 7 +++++--
 4 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/apps/web/content/docs/self-hosting.mdx b/apps/web/content/docs/self-hosting.mdx
index 762a91210f6..2679a9ac749 100644
--- a/apps/web/content/docs/self-hosting.mdx
+++ b/apps/web/content/docs/self-hosting.mdx
@@ -115,6 +115,8 @@ MEDIA_SERVER_MAX_CONCURRENT_DIRECT_CONVERSIONS=2   # direct /video/convert reque
 MEDIA_SERVER_MAX_CONCURRENT_VIDEO_PROCESSES=4      # all video jobs
 ```
 
+On `docker compose stop` the media server stops taking new work and lets active work finish for up to `MEDIA_SERVER_SHUTDOWN_GRACE_MS` (25s in the bundled compose files). It then cancels what is left and sends each cancelled job's webhook: an attempt already in flight can take up to 5s, then up to 3 tries of 5s with 1.5s of backoff (16.5s). That is 46.5s before cleanup, so the compose files set `stop_grace_period: 60s`. If you raise the grace period, raise `stop_grace_period` by the same amount, or Docker kills the container before it finishes.
+
 ## Optional Features
 
 ### AI Features
diff --git a/docker-compose.coolify.yml b/docker-compose.coolify.yml
index 82743a1519d..347fcecff26 100644
--- a/docker-compose.coolify.yml
+++ b/docker-compose.coolify.yml
@@ -46,9 +46,12 @@ services:
   media-server:
     image: 'ghcr.io/capsoftware/cap-media-server:latest'
     restart: unless-stopped
-    stop_grace_period: 30s
+    # Shutdown budget: up to 25s drain (MEDIA_SERVER_SHUTDOWN_GRACE_MS), then
+    # cancel webhooks for aborted jobs (an in-flight attempt finishes first, up
+    # to 5s, then 3 tries x 5s + 1.5s backoff = 16.5s), then cleanup.
+    # 25 + 5 + 16.5 = 46.5s, so 60s leaves ~13s for cleanup before SIGKILL.
+    stop_grace_period: 60s
     environment:
-      # Finish active work for up to 25s on stop (below stop_grace_period).
       MEDIA_SERVER_SHUTDOWN_GRACE_MS: '25000'
       PORT: 3456
       MEDIA_SERVER_WEBHOOK_SECRET: '${SERVICE_HEX_32_MEDIASERVER}'
diff --git a/docker-compose.template.yml b/docker-compose.template.yml
index 37992a0393c..01827db1ded 100644
--- a/docker-compose.template.yml
+++ b/docker-compose.template.yml
@@ -55,9 +55,12 @@ services:
       context: ./apps/media-server
       dockerfile: Dockerfile.standalone
     restart: unless-stopped
-    stop_grace_period: 30s
+    # Shutdown budget: up to 25s drain (MEDIA_SERVER_SHUTDOWN_GRACE_MS), then
+    # cancel webhooks for aborted jobs (an in-flight attempt finishes first, up
+    # to 5s, then 3 tries x 5s + 1.5s backoff = 16.5s), then cleanup.
+    # 25 + 5 + 16.5 = 46.5s, so 60s leaves ~13s for cleanup before SIGKILL.
+    stop_grace_period: 60s
     environment:
-      # Finish active work for up to 25s on stop (below stop_grace_period).
       MEDIA_SERVER_SHUTDOWN_GRACE_MS: "25000"
       PORT: 3456
       MEDIA_SERVER_WEBHOOK_SECRET: fe337b52749070bb7b5d2c78cff9948439ea73cbc1869ba39d350e6c24db53b1
diff --git a/docker-compose.yml b/docker-compose.yml
index bf886a72eac..2757bfd5f47 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -49,9 +49,12 @@ services:
       context: ./apps/media-server
       dockerfile: Dockerfile.standalone
     restart: unless-stopped
-    stop_grace_period: 30s
+    # Shutdown budget: up to 25s drain (MEDIA_SERVER_SHUTDOWN_GRACE_MS), then
+    # cancel webhooks for aborted jobs (an in-flight attempt finishes first, up
+    # to 5s, then 3 tries x 5s + 1.5s backoff = 16.5s), then cleanup.
+    # 25 + 5 + 16.5 = 46.5s, so 60s leaves ~13s for cleanup before SIGKILL.
+    stop_grace_period: 60s
     environment:
-      # Finish active work for up to 25s on stop (below stop_grace_period).
       MEDIA_SERVER_SHUTDOWN_GRACE_MS: "25000"
       PORT: 3456
       MEDIA_SERVER_WEBHOOK_SECRET: ${MEDIA_SERVER_WEBHOOK_SECRET:-fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210}

From 1537a7b8d5958d2090907f230d8bce21ea26f4d7 Mon Sep 17 00:00:00 2001
From: Rishabh Bothra <07rishabhjain@gmail.com>
Date: Fri, 23 Oct 2026 23:34:41 +0000
Subject: [PATCH 3/4] fix(media-server): respect CPU sets and forward compose
 capacity settings

---
 .../src/__tests__/lib/video-capacity.test.ts   | 18 ++++++++++++------
 apps/media-server/src/lib/video-capacity.ts    |  7 ++++++-
 apps/web/content/docs/self-hosting.mdx         |  4 +++-
 docker-compose.coolify.yml                     |  2 ++
 docker-compose.template.yml                    |  2 ++
 docker-compose.yml                             |  2 ++
 6 files changed, 27 insertions(+), 8 deletions(-)

diff --git a/apps/media-server/src/__tests__/lib/video-capacity.test.ts b/apps/media-server/src/__tests__/lib/video-capacity.test.ts
index d73be931803..eb0e260bf30 100644
--- a/apps/media-server/src/__tests__/lib/video-capacity.test.ts
+++ b/apps/media-server/src/__tests__/lib/video-capacity.test.ts
@@ -3,14 +3,20 @@ import { getDefaultMaxConcurrentDirectVideoProcesses } from "../../lib/video-cap
 
 describe("getDefaultMaxConcurrentDirectVideoProcesses", () => {
 	test("keeps one conversion on small machines", () => {
-		expect(getDefaultMaxConcurrentDirectVideoProcesses(1)).toBe(1);
-		expect(getDefaultMaxConcurrentDirectVideoProcesses(2)).toBe(1);
-		expect(getDefaultMaxConcurrentDirectVideoProcesses(0.5)).toBe(1);
+		expect(getDefaultMaxConcurrentDirectVideoProcesses(1, 0)).toBe(1);
+		expect(getDefaultMaxConcurrentDirectVideoProcesses(2, 0)).toBe(1);
+		expect(getDefaultMaxConcurrentDirectVideoProcesses(0.5, 0)).toBe(1);
 	});
 
 	test("uses half the CPUs, capped at four", () => {
-		expect(getDefaultMaxConcurrentDirectVideoProcesses(4)).toBe(2);
-		expect(getDefaultMaxConcurrentDirectVideoProcesses(8)).toBe(4);
-		expect(getDefaultMaxConcurrentDirectVideoProcesses(32)).toBe(4);
+		expect(getDefaultMaxConcurrentDirectVideoProcesses(4, 0)).toBe(2);
+		expect(getDefaultMaxConcurrentDirectVideoProcesses(8, 0)).toBe(4);
+		expect(getDefaultMaxConcurrentDirectVideoProcesses(32, 0)).toBe(4);
+	});
+
+	test("respects both the CPU set and quota", () => {
+		expect(getDefaultMaxConcurrentDirectVideoProcesses(2, 8)).toBe(1);
+		expect(getDefaultMaxConcurrentDirectVideoProcesses(8, 2)).toBe(1);
+		expect(getDefaultMaxConcurrentDirectVideoProcesses(8, 0.5)).toBe(1);
 	});
 });
diff --git a/apps/media-server/src/lib/video-capacity.ts b/apps/media-server/src/lib/video-capacity.ts
index 97fbebeb365..be16b57f08b 100644
--- a/apps/media-server/src/lib/video-capacity.ts
+++ b/apps/media-server/src/lib/video-capacity.ts
@@ -13,8 +13,13 @@ const configuredMaxDirectVideoProcesses =
 const MAX_DEFAULT_DIRECT_VIDEO_PROCESSES = 4;
 
 export function getDefaultMaxConcurrentDirectVideoProcesses(
-	cpuCapacity: number = getContainerCpuLimit() || os.availableParallelism(),
+	availableCpus: number = os.availableParallelism(),
+	containerCpuLimit: number = getContainerCpuLimit(),
 ): number {
+	const cpuCapacity =
+		containerCpuLimit > 0
+			? Math.min(availableCpus, containerCpuLimit)
+			: availableCpus;
 	return Math.max(
 		1,
 		Math.min(MAX_DEFAULT_DIRECT_VIDEO_PROCESSES, Math.floor(cpuCapacity / 2)),
diff --git a/apps/web/content/docs/self-hosting.mdx b/apps/web/content/docs/self-hosting.mdx
index f468279d8ad..14b32e83986 100644
--- a/apps/web/content/docs/self-hosting.mdx
+++ b/apps/web/content/docs/self-hosting.mdx
@@ -108,13 +108,15 @@ By default, login links are printed to the server logs. To send emails:
 
 ## Media Server Tuning
 
-The media server converts uploads in parallel based on the CPUs it can use: half the available CPUs, at least 1 and at most 4. It still turns work away when CPU or memory pressure is high. Override this with:
+The media server converts uploads in parallel based on the CPUs it can use: half the available CPUs, at least 1 and at most 4. It still turns work away when CPU or memory pressure is high. The CPU quota and assigned CPU set both limit this default. To override it in the bundled Compose deployments, add these values to `.env` (the media-server service forwards them):
 
 ```bash
 MEDIA_SERVER_MAX_CONCURRENT_DIRECT_CONVERSIONS=2   # direct /video/convert requests
 MEDIA_SERVER_MAX_CONCURRENT_VIDEO_PROCESSES=4      # all video jobs
 ```
 
+Apply changes with `docker compose up -d --force-recreate media-server` (`cap-media-server` for the template and Coolify services). For a custom Compose file, also add these variables to the media-server service’s `environment` mapping; `.env` alone does not pass variables into a container.
+
 On `docker compose stop` the media server stops taking new work and lets active work finish for up to `MEDIA_SERVER_SHUTDOWN_GRACE_MS` (25s in the bundled compose files). It then cancels what is left and sends each cancelled job's webhook: an attempt already in flight can take up to 5s, then up to 3 tries of 5s with 1.5s of backoff (16.5s). That is 46.5s before cleanup, so the compose files set `stop_grace_period: 60s`. If you raise the grace period, raise `stop_grace_period` by the same amount, or Docker kills the container before it finishes.
 
 ## Optional Features
diff --git a/docker-compose.coolify.yml b/docker-compose.coolify.yml
index 14f479b8ff9..824e4353f55 100644
--- a/docker-compose.coolify.yml
+++ b/docker-compose.coolify.yml
@@ -55,6 +55,8 @@ services:
     stop_grace_period: 60s
     environment:
       MEDIA_SERVER_SHUTDOWN_GRACE_MS: '25000'
+      MEDIA_SERVER_MAX_CONCURRENT_DIRECT_CONVERSIONS: ${MEDIA_SERVER_MAX_CONCURRENT_DIRECT_CONVERSIONS:-0}
+      MEDIA_SERVER_MAX_CONCURRENT_VIDEO_PROCESSES: ${MEDIA_SERVER_MAX_CONCURRENT_VIDEO_PROCESSES:-0}
       PORT: 3456
       MEDIA_SERVER_WEBHOOK_SECRET: '${SERVICE_HEX_32_MEDIASERVER}'
     healthcheck:
diff --git a/docker-compose.template.yml b/docker-compose.template.yml
index 01827db1ded..b0f33ad3645 100644
--- a/docker-compose.template.yml
+++ b/docker-compose.template.yml
@@ -62,6 +62,8 @@ services:
     stop_grace_period: 60s
     environment:
       MEDIA_SERVER_SHUTDOWN_GRACE_MS: "25000"
+      MEDIA_SERVER_MAX_CONCURRENT_DIRECT_CONVERSIONS: ${MEDIA_SERVER_MAX_CONCURRENT_DIRECT_CONVERSIONS:-0}
+      MEDIA_SERVER_MAX_CONCURRENT_VIDEO_PROCESSES: ${MEDIA_SERVER_MAX_CONCURRENT_VIDEO_PROCESSES:-0}
       PORT: 3456
       MEDIA_SERVER_WEBHOOK_SECRET: fe337b52749070bb7b5d2c78cff9948439ea73cbc1869ba39d350e6c24db53b1
     ports:
diff --git a/docker-compose.yml b/docker-compose.yml
index 174b279de2e..0760218cb1c 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -58,6 +58,8 @@ services:
     stop_grace_period: 60s
     environment:
       MEDIA_SERVER_SHUTDOWN_GRACE_MS: "25000"
+      MEDIA_SERVER_MAX_CONCURRENT_DIRECT_CONVERSIONS: ${MEDIA_SERVER_MAX_CONCURRENT_DIRECT_CONVERSIONS:-0}
+      MEDIA_SERVER_MAX_CONCURRENT_VIDEO_PROCESSES: ${MEDIA_SERVER_MAX_CONCURRENT_VIDEO_PROCESSES:-0}
       PORT: 3456
       MEDIA_SERVER_WEBHOOK_SECRET: ${MEDIA_SERVER_WEBHOOK_SECRET:-fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210}
     healthcheck:

From 0f77e8d6fa5d50e4b5fb82ed4b145156859238e1 Mon Sep 17 00:00:00 2001
From: Rishabh Bothra <07rishabhjain@gmail.com>
Date: Sat, 24 Oct 2026 08:11:12 +0000
Subject: [PATCH 4/4] docs(self-host): correct media-server tuning commands for
 Coolify

---
 apps/web/content/docs/self-hosting.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/web/content/docs/self-hosting.mdx b/apps/web/content/docs/self-hosting.mdx
index 14b32e83986..1c4aad62f59 100644
--- a/apps/web/content/docs/self-hosting.mdx
+++ b/apps/web/content/docs/self-hosting.mdx
@@ -115,7 +115,7 @@ MEDIA_SERVER_MAX_CONCURRENT_DIRECT_CONVERSIONS=2   # direct /video/convert reque
 MEDIA_SERVER_MAX_CONCURRENT_VIDEO_PROCESSES=4      # all video jobs
 ```
 
-Apply changes with `docker compose up -d --force-recreate media-server` (`cap-media-server` for the template and Coolify services). For a custom Compose file, also add these variables to the media-server service’s `environment` mapping; `.env` alone does not pass variables into a container.
+Apply changes with `docker compose up -d --force-recreate media-server`. With `docker-compose.template.yml`, use `docker compose -f docker-compose.template.yml up -d --force-recreate cap-media-server`. In Coolify, update the environment variables and redeploy the `media-server` service. For a custom Compose file, also add these variables to the media-server service’s `environment` mapping; `.env` alone does not pass variables into a container.
 
 On `docker compose stop` the media server stops taking new work and lets active work finish for up to `MEDIA_SERVER_SHUTDOWN_GRACE_MS` (25s in the bundled compose files). It then cancels what is left and sends each cancelled job's webhook: an attempt already in flight can take up to 5s, then up to 3 tries of 5s with 1.5s of backoff (16.5s). That is 46.5s before cleanup, so the compose files set `stop_grace_period: 60s`. If you raise the grace period, raise `stop_grace_period` by the same amount, or Docker kills the container before it finishes.