fixup! [docs] Added description how to run task inside a docker container

Author: Michal Tichák

README.md

@@ -190,8 +190,7 @@ There are two ways of interacting with AliECS:
       * [Hashing to aggregate](/docs/metrics.md#hashing-to-aggregate)
       * [Sampling reservoir](/docs/metrics.md#sampling-reservoir)
   * [OCC API debugging with grpcc](/docs/using_grpcc_occ.md#occ-api-debugging-with-grpcc)
-  * [Running tasks inside docker](/docs/running_docker.md#running-task-inside-a-docker-container)
-
+  * [Running tasks inside docker](/docs/running_docker.md#running-a-task-inside-a-docker-container)
 * Resources
   * T. Mrnjavac et. al, [AliECS: A New Experiment Control System for the ALICE Experiment](https://doi.org/10.1051/epjconf/202429502027), CHEP23
 

docs/running_docker.md

@@ -1,37 +1,112 @@
-# Running task inside a docker container
+# Running a Task Inside a Docker Container
 
-> **WARNING**: This method is not meant for the production use and is meant only as a POC to test docker images as a part of existing pipeline. Right now it was tested with outdated alma8-flp-node image running readout
+> ⚠️ **Warning**
+> This method is **not intended for production use**.
+> It serves only as a **proof of concept (POC)** for testing Docker images as part of an existing pipeline.
+>
+> Currently, it has been tested with the `alma9-flp-node` image running the *readout* component.
 
-## How to
+---
 
-As a first step we need to be sure that required host computer has installed `docker`. At the time of writing this document `docker` needs to be installed manually.
+## How To
 
-In order to run task inside a docker image on the executor we can simply wrap the binary call into the docker image inside the [ControlWorkflow](https://github.com/AliceO2Group/ControlWorkflows) repository. For example in order to run readout we can modify `_plain_command` part of [`readout.yaml`](https://github.com/AliceO2Group/ControlWorkflows/blob/master/tasks/readout.yaml) by adding `docker run image command`. Obviously we need to have docker image that contains required binary with proper settings (creating one is outside of this document). A bit tricky part is that we need to manually (for now) specify all ENV variables with `-e` option in `docker run` call. Moreover we might need to add `--network=host` and `--ipc=host` to the call itself. Michal Tichak was able to run readout inside the alma8-flp-node as a part of workflow using following:
+### 1. Manual Setup
 
-```
-"/usr/bin/docker run --network=host --ipc=host -v /tmp:/tmp -e O2_DETECTOR={{ detector }} -e O2_PARTITION={{ environment_id }} -e OCC_CONTROL_PORT=31000 -e O2_SYSTEM=FLP -e O2_ROLE=mtichak-ostack gitlab-registry.cern.ch/aliceo2group/dockerfiles/alma8-flp-node:latest /opt/o2/bin/o2-readout-exe"
+Before running tasks in Docker, ensure that the host machine has **Docker** installed.
+At the time of writing, Docker must be installed **manually**.
+
+> ⚠️ **Security Note**
+> The `flp` user must be able to run `sudo` **without a password**, because Docker requires root privileges.
+>
+> This setup is **not safe for production systems**.
+
+Run the following commands as `root`:
+
+```bash
+usermod -aG wheel flp
+echo '%wheel ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/90-wheel-nopasswd
 ```
 
-In order to figure out all of the ENV variables required one can take a look into the ECS gui environment details page and find task in question where all of the env variables are defined while running the binary outside of docker.
+---
 
-## Tips and tricks
+### 2. Modifying ControlWorkflows
 
-Production systems run RHEL which doesn't install native `docker` by running `dnf install docker` but they are emulating the functionality by using `podman` which might behave different.
+To run a task inside a Docker container on the executor, wrap the binary call in a `docker run` command within the [ControlWorkflows](https://github.com/AliceO2Group/ControlWorkflows) repository.
 
-In order to debug whether ECS is even starting the container we can use
+For example, to run **readout**, modify the `_plain_command` section of [`readout.yaml`](https://github.com/AliceO2Group/ControlWorkflows/blob/master/tasks/readout.yaml) by adding a Docker command.
 
-```
-docker ps -a
-```
+> 🧩 **Note**
+> You must already have a Docker image that includes the required binary and configuration.
+> (Creating such an image is **outside the scope** of this document.)
 
-This will show all of the containers which were run/are runinng on the system under current user. However there is a catch: ECS is using user `flp` so in order to figure out which container was running under this user, we need to switch the user by
+#### Example Command
 
-```
-su - flp
+When running *readout*, **Michal Tichak** successfully used the following command inside the `alma9-flp-node` image:
+
+```bash
+sudo /usr/bin/docker run --name readout --replace \
+  --user "$(id -u flp):$(id -u flp)" \
+  --network=host --ipc=host \
+  -e O2_DETECTOR -e O2_PARTITION -e OCC_CONTROL_PORT \
+  -e O2_SYSTEM -e O2_ROLE \
+  gitlab-registry.cern.ch/aliceo2group/dockerfiles/alma9-flp-node:2 \
+  /opt/o2/bin/o2-readout-exe
 ```
 
-You can show logs directly from docker itself by using:
+#### Environment Variables
 
+To identify all required environment variables:
+
+1. Open the **ECS GUI**.
+2. Go to the **Environment Details** page for the relevant task.
+3. Review the variables defined there — these match those used when running the binary outside Docker.
+
+#### Shared Memory Communication
+
+To enable shared memory communication between processes, add the `--ipc=host` flag when running the container.
+However, doing so requires **elevated privileges**.
+
+While **Podman** can run without root privileges, it pauses other Podman processes for the same user.
+This means commands like `podman ps -a` or starting multiple containers in parallel will not work.
+
+Therefore, you should run containers using the same user as the rest of the pipeline:
+
+```bash
+--user "$(id -u flp):$(id -u flp)"
 ```
-docker logs [container-id|name]
-```
+
+This ensures shared memory segments are created under the same user context.
+
+---
+
+## Tips and Tricks
+
+* Production systems running **RHEL** do not install native Docker via:
+
+  ```bash
+  dnf install docker
+  ```
+
+  Instead, they use **Podman**, which emulates Docker’s behavior but may differ in certain aspects.
+
+* To check whether ECS has started a container, run:
+
+  ```bash
+  docker ps -a
+  ```
+
+  This lists all containers that have run (or are currently running) under the current user.
+
+  > ECS typically runs as the `flp` user, so to inspect its containers, switch users first:
+  >
+  > ```bash
+  > su - flp
+  > ```
+
+* To view container logs directly from Docker:
+
+  ```bash
+  docker logs <container-id|name>
+  ```
+
+---