Add network & containerisation

2026-03-10 20:31:37 +01:00
parent a63a0cdc3c
commit 42b8971744
11 changed files with 1102 additions and 52 deletions
@@ -0,0 +1,112 @@
+# Containerisation – Basics
+
+Generic concepts behind containerisation, applicable to any runtime.
+
+Related pages:
+
+- [Containerisation / Docker Basics](./Docker/Basics.md)
+
+---
+
+## 1. What Is Containerisation?
+
+Containerisation is a lightweight form of virtualisation. Instead of emulating hardware, it isolates applications at the operating-system level: each container runs in its own namespace but shares the host kernel.
+
+Key benefits:
+
+- **Portability** – a container image packages the application and its dependencies together and runs the same way on any compatible host.
+- **Isolation** – processes inside a container cannot directly affect other containers or the host.
+- **Efficiency** – containers start in milliseconds and consume far less overhead than virtual machines.
+- **Reproducibility** – images are versioned and built from explicit definitions, making deployments predictable.
+
+---
+
+## 2. Containers vs Virtual Machines
+
+|                | Container                               | Virtual Machine                                  |
+|----------------|-----------------------------------------|--------------------------------------------------|
+| Kernel         | Shared with host                        | Separate (emulated or paravirtualised)           |
+| Startup time   | Seconds or less                         | Seconds to minutes                               |
+| Overhead       | Very low                                | Higher (memory, CPU)                             |
+| Isolation      | Process-level                           | Hardware-level                                   |
+| Portability    | Image-based, very portable              | Depends on hypervisor                            |
+
+Containers are generally chosen when the goal is to package and run applications efficiently. Virtual machines are preferred when stronger isolation or a different operating-system kernel is required.
+
+---
+
+## 3. Core Concepts
+
+### 3.1 Image
+
+An image is a read-only template used to create containers. It bundles:
+
+- A base operating-system layer (for example a minimal Debian or Alpine image).
+- Application binaries and their dependencies.
+- Configuration and entrypoint instructions.
+
+Images are built from a definition file (for Docker, a `Dockerfile`) and are composed of **layers**. Each layer represents a change on top of the previous one, and layers are cached and reused across images.
+
+### 3.2 Container
+
+A container is a running instance of an image. It is:
+
+- Isolated from the host and other containers through Linux namespaces.
+- Resource-limited using control groups (cgroups).
+- Ephemeral by default – its writable layer is discarded when the container is removed.
+
+Persistent data must be stored outside the container lifecycle using **volumes** or **bind mounts**.
+
+### 3.3 Registry
+
+A registry is a server that stores and distributes container images. Common examples include:
+
+- **Docker Hub** – the default public registry.
+- **GitHub Container Registry (GHCR)**.
+- **Self-hosted** registries (for example Gitea's built-in package registry or a dedicated Harbor instance).
+
+Images are referenced as `registry/name:tag`. The tag identifies a specific version.
+
+### 3.4 Volume
+
+A volume is a mechanism for persisting data independently of the container lifecycle. Two common forms:
+
+- **Managed volumes** – created and tracked by the container runtime; stored in a dedicated area on the host.
+- **Bind mounts** – a specific host directory exposed inside the container at a given path.
+
+---
+
+## 4. Linux Primitives Behind Containers
+
+Containers rely on two core Linux kernel features.
+
+### 4.1 Namespaces
+
+Namespaces provide process-level isolation for system resources so that each container sees only its own view of the system:
+
+- **PID namespace** – containers see their own process tree.
+- **Network namespace** – each container gets its own network stack and interfaces.
+- **Mount namespace** – containers see their own filesystem tree.
+- **UTS namespace** – each container can have a distinct hostname.
+- **User namespace** – container user IDs can be remapped to different host IDs.
+
+### 4.2 cgroups (control groups)
+
+cgroups limit and account for resource consumption per process group:
+
+- CPU usage.
+- Memory limits.
+- I/O bandwidth.
+
+This prevents a single container from monopolising host resources.
+
+---
+
+## 5. Container Runtimes
+
+Several implementations exist:
+
+- **Docker** – the most widely adopted; includes a CLI, a build system, and Docker Compose for multi-container setups. See [Docker / Basics](./Docker/Basics.md).
+- **Podman** – daemonless and Docker-compatible; supports rootless containers by default.
+- **containerd** – a lower-level runtime used by Kubernetes and sometimes by Docker as its engine backend.
+- **LXC / LXD** – older but still used for system containers, which behave more like lightweight virtual machines than application containers.
@@ -0,0 +1,176 @@
+# Docker – Basics
+
+Docker-specific concepts: architecture, images, containers, volumes, networks, and Compose.
+
+For generic containerisation concepts, see:
+
+- [Containerisation / Basics](../Basics.md)
+
+---
+
+## 1. What Is Docker?
+
+Docker is a platform built around Linux containers. It provides:
+
+- A **container runtime** (`dockerd`, the Docker daemon).
+- A **CLI** (`docker`) for building images, running containers, and managing the system.
+- A **build system** based on `Dockerfile`.
+- **Docker Compose** for defining and running multi-container applications from a single file.
+
+Docker was the tool that popularised application containers and remains the most widely used runtime in self-hosted and production environments.
+
+---
+
+## 2. Architecture
+
+Docker uses a client–server model:
+
+- **Docker client** (`docker`) – the CLI used to issue commands.
+- **Docker daemon** (`dockerd`) – the background service that manages images, containers, networks, and volumes.
+- **Registry** – where images are stored and fetched (default: Docker Hub).
+
+When you run `docker run nginx`, the client sends a request to the daemon, which pulls the image from the registry if not already present, then starts the container.
+
+---
+
+## 3. Images
+
+### 3.1 Dockerfile
+
+A `Dockerfile` is a plain text file that describes how to build an image step by step.
+
+```dockerfile
+FROM debian:bookworm-slim
+
+RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*
+
+COPY entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+ENTRYPOINT ["/entrypoint.sh"]
+```
+
+Each instruction creates a new layer. Docker caches layers to speed up rebuilds – only layers that change (and everything after them) are re-executed.
+
+### 3.2 Building Images
+
+Images are built with `docker build`. Common flags:
+
+- `-t name:tag` – assign a name and tag.
+- `-f Dockerfile.custom` – specify a non-default Dockerfile.
+- `--no-cache` – ignore cached layers and rebuild from scratch.
+
+See [Docker / Commands](./Commands.md) for practical examples.
+
+### 3.3 Image Tags
+
+A tag identifies a specific version of an image: `nginx:1.25`, `nginx:stable`, or `nginx:latest`. Using explicit version tags is safer than `latest`, which always points to the most recent build and can change without notice.
+
+---
+
+## 4. Containers
+
+### 4.1 Lifecycle
+
+A container moves through several states:
+
+- **Created** – exists but has not started yet.
+- **Running** – the main process is active.
+- **Paused** – processes are suspended.
+- **Stopped / Exited** – the main process has ended.
+- **Removed** – the container is deleted; its writable layer is discarded.
+
+Only data stored in volumes or bind mounts survives beyond the container's removal.
+
+### 4.2 Common Run Flags
+
+| Flag                       | Purpose                                      |
+|----------------------------|----------------------------------------------|
+| `-d`                       | Detached mode (run in background)            |
+| `--name`                   | Assign a name to the container               |
+| `-p host:container`        | Publish a port to the host                   |
+| `-v host:container`        | Bind mount a directory or attach a volume    |
+| `-e KEY=VALUE`             | Set an environment variable                  |
+| `--restart unless-stopped` | Restart policy (survives reboots)            |
+| `--network`                | Attach to a specific Docker network          |
+
+---
+
+## 5. Volumes and Bind Mounts
+
+### 5.1 Named Volumes
+
+Volumes are managed by Docker and stored under `/var/lib/docker/volumes/`. They persist across container restarts and removals (unless explicitly deleted with `docker volume rm`).
+
+Use named volumes for data that must survive the container lifecycle: databases, application state, generated files.
+
+### 5.2 Bind Mounts
+
+Bind mounts surface a specific host path inside the container at a chosen mount point. They are suitable for:
+
+- Configuration files managed on the host.
+- Application data stored in a known host directory.
+
+Unlike named volumes, bind mounts depend directly on the host filesystem layout and are not tracked by Docker.
+
+---
+
+## 6. Networks
+
+Docker provides several network drivers:
+
+- **bridge** (default) – containers on the same bridge network can reach each other by container name. User-defined bridges (created explicitly) support automatic DNS resolution between containers.
+- **host** – the container shares the host's network stack directly; no network isolation is applied.
+- **none** – the container has no network access.
+- **overlay** – multi-host communication (Swarm/Kubernetes); not relevant for single-host setups.
+
+Creating a dedicated user-defined bridge network for each application stack is the recommended approach; it avoids exposing containers to unrelated services.
+
+---
+
+## 7. Docker Compose
+
+Docker Compose defines a multi-container application in a single `compose.yaml` (or `docker-compose.yml`) file.
+
+A minimal example:
+
+```yaml
+services:
+  app:
+    image: myapp:latest
+    restart: unless-stopped
+    ports:
+      - "8080:80"
+    volumes:
+      - /host/appdata/myapp:/data
+    environment:
+      - APP_ENV=production
+
+  db:
+    image: postgres:16
+    restart: unless-stopped
+    volumes:
+      - db_data:/var/lib/postgresql/data
+    environment:
+      - POSTGRES_PASSWORD=secret
+
+volumes:
+  db_data:
+```
+
+Key Compose concepts:
+
+- **services** – each service becomes one container.
+- **volumes** – named volumes declared here are managed by Docker.
+- **networks** – Compose creates a default user-defined bridge network per project; services reach each other by service name.
+- **env_file** – loads environment variables from a file; useful to keep secrets out of `compose.yaml`.
+
+For Compose command examples, see [Docker / Commands](./Commands.md).
+
+---
+
+## 8. Relation to Other Documents
+
+- [Containerisation / Basics](../Basics.md)
+- [Docker / Commands](./Commands.md)
+- [Home-Server / Docker Stacks](../../Home-Server/Containers/Stacks.md)
@@ -0,0 +1,183 @@
+# Docker – Commands
+
+Practical Docker and Docker Compose command reference. Each block groups related commands with inline comments.
+
+For the concepts behind these commands, see:
+
+- [Docker / Basics](./Basics.md)
+
+---
+
+## 1. Images
+
+```bash
+# List local images
+docker images
+
+# Pull an image from a registry
+docker pull nginx:stable
+
+# Build an image from a Dockerfile in the current directory
+docker build -t myapp:1.0 .
+
+# Build with a custom Dockerfile
+docker build -f Dockerfile.prod -t myapp:prod .
+
+# Tag an existing image
+docker tag myapp:1.0 myapp:latest
+
+# Remove an image
+docker rmi myapp:1.0
+
+# Remove all unused images (dangling and unreferenced)
+docker image prune -a
+```
+
+---
+
+## 2. Container Lifecycle
+
+```bash
+# Run a container in detached mode
+docker run -d --name myapp -p 8080:80 nginx:stable
+
+# Run with a bind mount, environment variable, and restart policy
+docker run -d \
+  --name myapp \
+  -v /host/data:/app/data \
+  -e APP_ENV=production \
+  --restart unless-stopped \
+  myapp:1.0
+
+# Start / stop / restart a container
+docker start myapp
+docker stop myapp
+docker restart myapp
+
+# List running containers
+docker ps
+
+# List all containers (including stopped)
+docker ps -a
+
+# Remove a stopped container
+docker rm myapp
+
+# Stop and remove in one go
+docker stop myapp && docker rm myapp
+```
+
+---
+
+## 3. Logs and Inspection
+
+```bash
+# View container logs
+docker logs myapp
+
+# Follow logs in real time
+docker logs -f myapp
+
+# Show last 50 lines
+docker logs --tail 50 myapp
+
+# Execute a command inside a running container
+docker exec -it myapp bash       # interactive shell
+docker exec myapp ls /app        # one-off command
+
+# Inspect container configuration and networking
+docker inspect myapp
+
+# Show live resource usage for all running containers
+docker stats
+```
+
+---
+
+## 4. Volumes
+
+```bash
+# List volumes
+docker volume ls
+
+# Create a named volume
+docker volume create mydata
+
+# Inspect a volume (shows mount path on host)
+docker volume inspect mydata
+
+# Remove a volume
+docker volume rm mydata
+
+# Remove all unused volumes
+docker volume prune
+```
+
+---
+
+## 5. Networks
+
+```bash
+# List networks
+docker network ls
+
+# Create a user-defined bridge network
+docker network create mynet
+
+# Connect a running container to a network
+docker network connect mynet myapp
+
+# Inspect a network (shows connected containers)
+docker network inspect mynet
+
+# Remove a network
+docker network rm mynet
+```
+
+---
+
+## 6. Docker Compose
+
+```bash
+# Start all services in detached mode
+docker compose up -d
+
+# Stop and remove containers (volumes are kept)
+docker compose down
+
+# Stop and remove containers AND named volumes
+docker compose down -v
+
+# Rebuild images before starting
+docker compose up -d --build
+
+# Restart a single service
+docker compose restart app
+
+# View logs for all services
+docker compose logs -f
+
+# View logs for one service
+docker compose logs -f app
+
+# List containers for the current project
+docker compose ps
+
+# Execute a command inside a service container
+docker compose exec app bash
+```
+
+---
+
+## 7. System Cleanup
+
+```bash
+# Show disk usage by Docker objects (images, containers, volumes, cache)
+docker system df
+
+# Remove all stopped containers, unused networks, dangling images, and build cache
+docker system prune
+
+# Same but also remove unused non-dangling images
+docker system prune -a
+```