docker doc : updated setup doc

Docs/Libs/Docker/01-Setup.md

@@ -0,0 +1,274 @@
+# Docker SDK for Python – Setup and First Steps
+
+This document introduces the **Docker SDK for Python (`docker` library)** and explains how to connect to the Docker Engine, inspect its status, and authenticate with a registry. The goal is not just to show code, but to clearly explain **what each part does, why it exists, and when you would use it**.
+
+This guide assumes you already understand basic Docker concepts (images, containers, daemon) and are approaching this from a DevOps perspective.
+
+---
+
+## 1. Installing the Docker SDK for Python
+
+Before Python can communicate with Docker, we need to install the official SDK.
+
+```bash
+pip install docker
+```
+
+### What this does
+
+* Installs the **docker** Python package (often called *docker-py*).
+* This package acts as a **client wrapper** around Docker’s REST API.
+* All interactions ultimately talk to the Docker daemon (`dockerd`) over a socket or TCP connection.
+
+Important note:
+
+* Installing the library alone is not enough.
+* Docker **must already be installed and running** on the system.
+
+---
+
+## 2. Connecting to Docker Using Environment Configuration
+
+The simplest and most common way to create a Docker client is by using environment-based configuration.
+
+```python
+import docker
+
+client = docker.from_env()
+version = client.version()
+ping_docker = client.ping()
+
+print(version, ping_docker)
+```
+
+### Step-by-step explanation
+
+#### `import docker`
+
+* Imports the Docker SDK.
+* This module exposes high-level objects for interacting with Docker resources.
+
+#### `docker.from_env()`
+
+* Automatically creates a `DockerClient` instance.
+* Reads Docker connection details from environment variables such as:
+
+  * `DOCKER_HOST`
+  * `DOCKER_TLS_VERIFY`
+  * `DOCKER_CERT_PATH`
+* On Linux, this usually resolves to:
+
+  * `unix:///var/run/docker.sock`
+
+This is why `from_env()` is preferred:
+
+* Works across Linux, macOS, Windows, and CI systems
+* Requires no hardcoded connection strings
+
+#### `client.version()`
+
+* Calls the Docker Engine `/version` API endpoint.
+* Returns detailed metadata such as:
+
+  * Docker Engine version
+  * API version
+  * Go version
+  * OS and architecture
+
+This is commonly used for:
+
+* Debugging
+* Compatibility checks
+* Logging runtime environment details
+
+#### `client.ping()`
+
+* Sends a lightweight request to the Docker daemon.
+* Returns `True` if Docker is reachable and responsive.
+
+This is a **health check**, often used in:
+
+* Startup validation
+* Monitoring scripts
+* CI/CD pipelines
+
+---
+
+## 3. What Does “from_env” Actually Mean?
+
+Using `from_env()` tells the SDK:
+
+> “Figure out how to connect to Docker using the same configuration the Docker CLI uses.”
+
+Behind the scenes, it:
+
+* Detects whether Docker is local or remote
+* Determines socket vs TCP
+* Applies TLS settings if required
+
+### When should you use it?
+
+* Local development
+* Kubernetes nodes
+* CI runners
+* Most production automation
+
+### When not to use it?
+
+* When you need explicit control over connection parameters
+* When connecting to a **remote Docker daemon** with custom networking
+
+---
+
+## 4. Creating a Docker Client Explicitly
+
+Instead of relying on environment detection, you can create a client manually.
+
+```python
+import docker
+
+client = docker.DockerClient(base_url='unix://var/run/docker.sock')
+version = client.version()
+ping_docker = client.ping()
+
+print(version, ping_docker)
+```
+
+### Explanation
+
+#### `docker.DockerClient(...)`
+
+* Directly instantiates a Docker client object.
+* Requires you to specify how to reach the Docker daemon.
+
+#### `base_url='unix://var/run/docker.sock'`
+
+* Points to the Unix socket used by Docker on Linux systems.
+* This socket is owned by root and the `docker` group.
+
+Important implications:
+
+* Your Python process must have permission to access the socket
+* Usually means running as root or a user in the `docker` group
+
+### When this approach is useful
+
+* Controlled environments
+* Educational examples
+* Explicit infrastructure scripts
+
+### Why it is less common
+
+* Not portable across OSes
+* Hardcodes infrastructure assumptions
+
+---
+
+## 5. Inspecting Docker and Authenticating
+
+Once connected, the client can retrieve detailed system information and authenticate with registries.
+
+```python
+import docker
+
+client = docker.DockerClient(base_url='unix://var/run/docker.sock')
+version = client.version()
+ping_docker = client.ping()
+information = client.info()
+
+client.login(
+    username='user',
+    password='password',
+    registry='registry_link'
+)
+
+print(information, ping_docker)
+```
+
+### `client.info()`
+
+* Calls the Docker `/info` endpoint.
+* Returns a comprehensive snapshot of the Docker host, including:
+
+  * Number of containers (running/stopped)
+  * Number of images
+  * Storage driver
+  * Cgroup and kernel features
+  * Security options (AppArmor, seccomp)
+
+This is extremely valuable for:
+
+* Capacity planning
+* Debugging runtime issues
+* Auditing host configuration
+
+### `client.login(...)`
+
+* Authenticates Docker with a container registry.
+* Stores credentials in Docker’s credential store.
+
+Parameters:
+
+* `username`: registry account username
+* `password`: registry password or access token
+* `registry`: registry URL (e.g. Docker Hub or private registry)
+
+Common use cases:
+
+* Pulling private images
+* Pushing images in CI/CD pipelines
+* Automating registry interactions
+
+Security note:
+
+* Avoid hardcoding credentials in source code
+* Prefer environment variables or secret managers
+
+---
+
+## 6. High-Level vs Low-Level API (Important Concept)
+
+What you are using here is the **high-level Docker client**.
+
+Characteristics:
+
+* Pythonic object model
+* Resource-oriented (containers, images, networks)
+* Easier to read and maintain
+
+The SDK also exposes a **low-level API**:
+
+* Direct access to Docker REST endpoints
+* More control, less abstraction
+
+As a DevOps engineer, you will typically:
+
+* Use high-level API for automation
+* Drop to low-level API for advanced edge cases
+
+---
+
+## 7. Summary
+
+In this setup phase, you learned how to:
+
+* Install the Docker SDK for Python
+* Connect to Docker using environment-based configuration
+* Explicitly define Docker connection settings
+* Verify Docker availability
+* Retrieve system-level Docker information
+* Authenticate with container registries
+
+This foundation is critical before moving on to:
+
+* Managing containers
+* Building images
+* Working with volumes and networks
+
+---
+
+## References
+
+Official Docker SDK for Python documentation:
+
+* [https://docker-py.readthedocs.io/](https://docker-py.readthedocs.io/)