Docker SDK: Added Network doc ( not complated )

Docs/Libs/Docker/03-Containers.md

@@ -0,0 +1,284 @@
+# Docker SDK for Python – Working with Containers
+
+This document explains how to **manage Docker containers** using the Docker SDK for Python. Containers are the runtime unit of Docker, so this section focuses on lifecycle management: listing, creating, running, starting, stopping, restarting, pausing, and inspecting logs.
+
+The goal is to understand **how container state changes**, how the Python SDK maps to Docker CLI behavior, and how these operations are typically used in real DevOps automation.
+
+---
+
+## 1. Creating the Docker Client
+
+```python
+import docker
+import time
+
+client = docker.DockerClient(base_url='unix://var/run/docker.sock')
+ping_docker = client.ping()
+```
+
+### Explanation
+
+* Establishes a connection to the Docker daemon via the Unix socket.
+* `ping()` is used as a sanity check before executing container operations.
+
+In production-grade scripts, this check prevents:
+
+* Silent failures
+* Partial execution when Docker is down
+
+---
+
+## 2. Listing Running Containers
+
+```python
+def get_containers_list():
+    containers = client.containers.list()
+
+    for c in containers:
+        print(c.id, c.name, c.status)
+```
+
+### Explanation
+
+* `containers.list()` returns **only running containers** by default.
+* Each returned object represents a live container instance.
+
+Common attributes:
+
+* `id`: unique container identifier
+* `name`: human-readable container name
+* `status`: runtime state (running)
+
+This is equivalent to:
+
+* `docker ps`
+
+---
+
+## 3. Listing All Containers (Including Stopped)
+
+```python
+def get_all_containers_list():
+    containers = client.containers.list(all=True)
+
+    for c in containers:
+        print(c.id, c.name, c.status)
+```
+
+### Explanation
+
+* `all=True` includes stopped, exited, and created containers.
+* Useful for cleanup, auditing, and lifecycle reconciliation.
+
+Equivalent CLI command:
+
+* `docker ps -a`
+
+---
+
+## 4. Creating a Container (Without Starting It)
+
+```python
+def create_container():
+    container = client.containers.create(
+        image="nginx:latest",
+        name="my_nginx",
+        ports={"80/tcp": 8080},
+        detach=True
+    )
+```
+
+### Explanation
+
+This creates a container in the **created** state.
+
+Key parameters:
+
+* `image`: base image for the container
+* `name`: explicit container name
+* `ports`: port mapping (container → host)
+* `detach=True`: container runs in background when started
+
+Important distinction:
+
+* `create()` does **not** start the container
+* This mirrors `docker create`
+
+Use cases:
+
+* Deferred startup
+* Multi-step initialization
+
+---
+
+## 5. Running a Container (Create + Start)
+
+```python
+def run_container():
+    container = client.containers.run(
+        "nginx:latest",
+        name="nginx_run",
+        ports={"80/tcp": 8081},
+        detach=True
+    )
+```
+
+### Explanation
+
+* `run()` is a convenience method.
+* Internally performs `create()` followed by `start()`.
+
+Equivalent CLI command:
+
+* `docker run -d -p 8081:80 nginx:latest`
+
+This is the most common approach for:
+
+* Short-lived workloads
+* Simple services
+
+---
+
+## 6. Managing Container Lifecycle
+
+```python
+def start_container():
+    container = client.containers.get("my_nginx")
+
+    container.start()
+    time.sleep(1000)
+
+    container.restart()
+    time.sleep(1000)
+
+    container.pause()
+    container.unpause()
+    time.sleep(1000)
+
+    container.stop(timeout=10)
+```
+
+### Explanation
+
+This function demonstrates multiple lifecycle transitions.
+
+#### `containers.get(name)`
+
+* Retrieves an existing container by name or ID.
+* Raises an exception if the container does not exist.
+
+#### `start()`
+
+* Transitions container from `created` or `stopped` → `running`.
+
+#### `restart()`
+
+* Stops and immediately starts the container.
+* Often used after configuration changes.
+
+#### `pause()` / `unpause()`
+
+* Freezes container processes using cgroups.
+* Network and filesystem state remain intact.
+
+#### `stop(timeout=10)`
+
+* Sends SIGTERM, then SIGKILL after timeout.
+* Allows graceful shutdown.
+
+The `sleep()` calls simulate:
+
+* Long-running services
+* Observing container behavior between states
+
+---
+
+## 7. Reading Container Logs
+
+```python
+def log_container():
+    container = client.containers.get("my_nginx")
+    logs = container.logs(tail=20)
+    print(logs.decode())
+```
+
+### Explanation
+
+* Retrieves logs from the container’s stdout/stderr.
+* `tail=20` limits output to the last 20 lines.
+
+Important details:
+
+* Logs are returned as bytes
+* Decoding is required for readable output
+
+Equivalent CLI command:
+
+* `docker logs --tail 20 my_nginx`
+
+This is critical for:
+
+* Debugging runtime issues
+* Health checks
+* Observability tooling
+
+---
+
+## 8. Conditional Execution Based on Docker Availability
+
+```python
+if ping_docker:
+    get_containers_list()
+```
+
+### Explanation
+
+* Ensures container operations only run if Docker is reachable.
+* Prevents unhandled API errors.
+
+This pattern is common in:
+
+* Entry-point scripts
+* Health probes
+* Automation jobs
+
+---
+
+## 9. Container States (Conceptual Model)
+
+Understanding container states is essential:
+
+* `created`: container exists but is not running
+* `running`: container processes are active
+* `paused`: execution is suspended
+* `exited`: container stopped normally
+* `dead`: container failed unexpectedly
+
+Every method in this document transitions the container between these states.
+
+---
+
+## 10. Summary
+
+In this section, you learned how to:
+
+* List running and stopped containers
+* Create containers separately from starting them
+* Run containers in a single step
+* Control container lifecycle states
+* Read container logs
+* Safely execute operations based on Docker availability
+
+This container-level control is the foundation for:
+
+* Service orchestration
+* CI/CD job execution
+* Debugging and recovery automation
+
+---
+
+## References
+
+Official Docker SDK for Python documentation:
+
+* [https://docker-py.readthedocs.io/](https://docker-py.readthedocs.io/)