Running containers with kubedock (crw-3367)

modules/administration-guide/pages/running-containers-with-kubedock.adoc

@@ -0,0 +1,62 @@
+:_content-type: ASSEMBLY
+:description: Running containers with kubedock
+:keywords: kubedock, container
+:navtitle: Running containers with kubedock
+:page-aliases:
+
+[id="running-containers-with-kubedock"]
+= Running containers with kubedock
+
+link:https://github.com/joyrex2001/[Kubedock] is a minimal container engine implementation that gives you a podman-/docker-like experience inside a {prod-short} workspace. Kubedock is especially useful when you are dealing with ad-hoc, ephemeral, and testing containers, such as in the use cases listed below:
+
+* Executing application tests which rely on link:https://testcontainers.com/[Testcontainers] framework.
+
+* Using link:https://quarkus.io/guides/dev-services[Quarkus Dev Services].
+
+* Running a container stored in remote container registry, for local development purposes
+
+[IMPORTANT]
+====
+The image you choose to use with kubedock must be compliant with Openshift security requirements.
+Otherwise, running the image with kubedock will result in a failure even though the same image runs locally without issues.
+====
+
+.Enabling kubedock
+
+After enabling the kubedock environment variable, kubedock will run the following `podman` commands:
+
+* `podman run`
+* `podman ps`
+* `podman exec`
+* `podman cp`
+* `podman logs`
+* `podman inspect`
+* `podman kill`
+* `podman rm`
+* `podman wait`
+* `podman stop`
+* `podman start`
+
+Other commands such as `podman build` are started by the local podman instead.
+
+[IMPORTANT]
+====
+Using `podman` commands with kubedock has following limitations
+
+* The `podman build -t <image> . && podman run <image>` command will fail. Use `podman build -t <image> . && podman push <image> && podman run <image>` instead.
+* The `podman generate kube` command is not supported.
+* `--env` option causes the `podman run` command to fail.
+====
+
+.Prerequisites
+* An image compliant with Openshift security requirements.
+
+.Process
+. Add `KUBEDOCK_ENABLED=true` environment variable to the devfile.
+
+[NOTE]
+====
+You must configure podman or docker API to point to kubedock setting
+`CONTAINER_HOST=tcp://127.0.0.1:2475` or `DOCKER_HOST=tcp://127.0.0.1:2475` when running containers.
+However, you must configure podman to point to local podman when building the container.
+====