From 02e65d18258f499af4ca15ded009cdb29fa1050c Mon Sep 17 00:00:00 2001
From: Max Schmitt <max@schmitt.mx>
Date: Mon, 3 Mar 2025 11:23:33 +0100
Subject: [PATCH] docs: update Docker configuration recommendations (#34986)

---
 docs/src/ci.md     | 10 +---------
 docs/src/docker.md | 11 ++++++++---
 2 files changed, 9 insertions(+), 12 deletions(-)

diff --git a/docs/src/ci.md b/docs/src/ci.md
index 89ce6242fb..a6fa5bc44d 100644
--- a/docs/src/ci.md
+++ b/docs/src/ci.md
@@ -454,15 +454,7 @@ jobs:
 
 ### Docker
 
-We have a [pre-built Docker image](./docker.md) which can either be used directly or as a reference to update your existing Docker definitions.
-
-Suggested configuration
-1. Using `--ipc=host` is also recommended when using Chromium. Without it Chromium can run out of memory
-   and crash. Learn more about this option in [Docker docs](https://docs.docker.com/reference/cli/docker/container/run/#ipc).
-1. Seeing other weird errors when launching Chromium? Try running your container
-   with `docker run --cap-add=SYS_ADMIN` when developing locally.
-1. Using `--init` Docker flag or [dumb-init](https://github.com/Yelp/dumb-init) is recommended to avoid special
-   treatment for processes with PID=1. This is a common reason for zombie processes.
+We have a [pre-built Docker image](./docker.md) which can either be used directly or as a reference to update your existing Docker definitions. Make sure to follow the [Recommended Docker Configuration](./docker.md#recommended-docker-configuration) to ensure the best performance.
 
 ### Azure Pipelines
 
diff --git a/docs/src/docker.md b/docs/src/docker.md
index abb647e35b..a50850dc7d 100644
--- a/docs/src/docker.md
+++ b/docs/src/docker.md
@@ -94,10 +94,15 @@ docker run -it --rm --ipc=host --user pwuser --security-opt seccomp=seccomp_prof
 }
 ```
 
-:::note
-Using `--ipc=host` is recommended when using Chrome ([Docker docs](https://docs.docker.com/engine/reference/run/#ipc-settings---ipc)). Chrome can run out of memory without this flag.
-:::
+### Recommended Docker Configuration
 
+When running Playwright in Docker, the following configuration is recommended:
+
+1. **Using [`--init`](https://docs.docker.com/reference/cli/docker/container/run/#init)** Docker flag is recommended to avoid special treatment for processes with PID=1. This is a common reason for zombie processes.
+
+1. **Using `--ipc=host`** is recommended when using Chromium. Without it, Chromium can run out of memory and crash. Learn more about this option in [Docker docs](https://docs.docker.com/reference/cli/docker/container/run/#ipc).
+
+1. **If seeing weird errors when launching Chromium**, try running your container with `docker run --cap-add=SYS_ADMIN` when developing locally.
 
 ### Using on CI