From 32615bf6157ab6455f2e8c1042ea5dac642fd770 Mon Sep 17 00:00:00 2001 From: RadinPirouz Date: Sat, 24 Jan 2026 00:13:06 +0330 Subject: [PATCH] docker doc : updated setup doc --- Docs/Libs/Docker/01-Setup.md | 274 +++++++++++++++++++++++++++++++++++ 1 file changed, 274 insertions(+) diff --git a/Docs/Libs/Docker/01-Setup.md b/Docs/Libs/Docker/01-Setup.md index e69de29..b04ec25 100644 --- a/Docs/Libs/Docker/01-Setup.md +++ b/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/)