Documentation/Doc/Containerisation/Docker/Basics.md

# 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)