the_information_nexus/tech_docs/docker_primer.md

Here’s a **no-nonsense Docker CLI guide** focused on the **20% of commands that deliver 80% of the value** for senior engineers, with real-world examples and troubleshooting tips:

---

# **Docker CLI: The Senior Engineer’s Cheat Sheet**  
**Goal:** Master Docker’s command-line interface for **debugging, optimization, and orchestration**.

---

## **1. Core Commands (The Essentials)**  
| **Command**                          | **What It Does**                                  | **Key Flags**                     |
|--------------------------------------|--------------------------------------------------|-----------------------------------|
| `docker run`                         | Start a container                                | `-d` (detached), `-p 80:80` (port map) |
| `docker ps`                          | List running containers                          | `-a` (show stopped)               |
| `docker exec -it`                    | Run a command in a running container            | `-it` (interactive TTY)           |
| `docker logs`                        | View container logs                              | `-f` (follow), `--tail 100`       |
| `docker stop` / `docker rm`          | Stop or remove a container                       | `-f` (force remove running)       |

**Pro Tip:**  
- Use `docker run --rm` to **auto-remove containers** after they exit (great for testing).

---

## **2. Image Management**  
| **Command**                          | **What It Does**                                  | **Key Flags**                     |
|--------------------------------------|--------------------------------------------------|-----------------------------------|
| `docker build`                       | Build an image from a Dockerfile                 | `-t my-image:tag` (tag image)     |
| `docker images`                      | List local images                                | `-q` (quiet, just IDs)            |
| `docker pull`                        | Download an image from a registry                | `--platform linux/amd64`          |
| `docker push`                        | Upload an image to a registry                    |                                   |
| `docker image prune`                 | Delete unused images                             | `-a` (remove all dangling)        |

**Critical Knowledge:**  
- **Image Layers**: Each `RUN`, `COPY`, etc., in a Dockerfile creates a layer (cacheable).  
- **Multi-Platform Builds**:  
  ```bash
  docker buildx build --platform linux/amd64,linux/arm64 -t my-image:multiarch .
  ```

---

## **3. Networking & Ports**  
| **Command**                          | **What It Does**                                  | **Example**                       |
|--------------------------------------|--------------------------------------------------|-----------------------------------|
| `docker network ls`                  | List networks                                    |                                   |
| `docker network inspect`             | Show network details (IPs, gateways)            | `docker network inspect bridge`   |
| `docker port`                        | List port mappings                               | `docker port my-container`        |
| `docker run --network`               | Attach to a specific network                    | `--network host` (host mode)      |

**Key Concepts:**  
- **Bridge Network**: Default (NAT’d containers).  
- **Host Network**: Bypasses Docker networking (faster, less secure).  
- **Overlay Network**: For multi-host Swarm/Kubernetes.  

---

## **4. Storage & Volumes**  
| **Command**                          | **What It Does**                                  | **Example**                       |
|--------------------------------------|--------------------------------------------------|-----------------------------------|
| `docker volume ls`                   | List volumes                                     |                                   |
| `docker volume create`               | Create a named volume                            | `docker volume create my-vol`     |
| `docker run -v`                      | Mount a volume or bind mount                    | `-v /data:/app/data`              |
| `docker cp`                          | Copy files between host/container               | `docker cp my-container:/file .`  |

**Pro Tips:**  
- **Named Volumes**: Managed by Docker (best for databases).  
- **Bind Mounts**: Link to host dir (great for development):  
  ```bash
  docker run -v $(pwd):/app my-image
  ```

---

## **5. Debugging & Troubleshooting**  
| **Command**                          | **What It Does**                                  | **When to Use**                   |
|--------------------------------------|--------------------------------------------------|-----------------------------------|
| `docker stats`                       | Live resource usage (CPU/mem/IO)                | Identify resource hogs            |
| `docker top`                         | View processes inside a container               | Debug hung processes              |
| `docker inspect`                     | Low-level container/image details               | Find IPs, volumes, configs        |
| `docker events`                      | Real-time Docker daemon events                  | Audit container lifecycles        |
| `docker system df`                   | Show disk usage (images, containers, volumes)   | Cleanup decisions                 |

**Critical Flags for `docker inspect`:**  
```bash
docker inspect -f '{{.NetworkSettings.IPAddress}}' my-container  # Get container IP
docker inspect -f '{{.LogPath}}' my-container                   # Find log file path
```

---

## **6. Cleanup & Maintenance**  
| **Command**                          | **What It Does**                                  | **Nuclear Option**                |
|--------------------------------------|--------------------------------------------------|-----------------------------------|
| `docker container prune`             | Remove stopped containers                        |                                   |
| `docker image prune`                 | Remove dangling images                           | `-a` (remove all unused)          |
| `docker system prune`                | Remove **everything** unused                     | `--volumes` (include volumes)     |

**Warning:**  
- `docker system prune --all --volumes` **deletes all unused images, containers, and volumes** (use with caution!).

---

## **7. Docker Compose (Bonus)**  
| **Command**                          | **What It Does**                                  |  
|--------------------------------------|--------------------------------------------------|  
| `docker-compose up`                  | Start services defined in `docker-compose.yml`   |  
| `docker-compose down`                | Stop and remove services                         |  
| `docker-compose logs`                | View aggregated logs                             |  
| `docker-compose exec`                | Run a command in a service container             |  

**Pro Tip:**  
- Use `docker-compose --profile` to enable/disable services (e.g., dev vs. prod):  
  ```yaml
  services:
    redis:
      profiles: ["prod"]
  ```

---

## **8. Real-World Scenarios**  
### **1. Debug a Crashing Container**  
```bash
docker logs -f my-container       # Check logs
docker exec -it my-container sh  # Shell into it
docker inspect my-container      # Check exit code
```

### **2. Simulate Out-of-Memory (OOM) Killer**  
```bash
docker run -m 100m --rm alpine tail /dev/zero  # Trigger OOM
dmesg | grep -i kill                           # Find OOM event
```

### **3. Optimize Builds**  
```dockerfile
# Bad (creates huge layers):
RUN apt-get update && apt-get install -y python
RUN pip install -r requirements.txt

# Good (single layer):
RUN apt-get update && apt-get install -y python && \
    pip install -r requirements.txt && \
    apt-get clean
```

---

## **9. Interview Questions**  
1. **How do you reduce Docker image size?**  
   - Use multi-stage builds, Alpine-based images, and clean up temp files in the same `RUN` layer.  

2. **What’s the difference between `CMD` and `ENTRYPOINT`?**  
   - `ENTRYPOINT` defines the executable; `CMD` provides default args (can be overridden by `docker run`).  

3. **How do you persist data in Docker?**  
   - Volumes (`-v my-vol:/data`) or bind mounts (`-v /host/path:/data`).  

---

## **10. Cheat Sheet**  
```bash
# Start a container with a shell
docker run -it --rm alpine sh

# Build and tag an image
docker build -t my-app:1.0 .

# Clean up everything unused
docker system prune -a --volumes
```

**Next Steps:**  
- Learn **Docker Swarm** (`docker swarm init`).  
- Dive into **Kubernetes** (`kubectl`).  
- Master **eBPF for container tracing** (`bpftrace`).  

Need a **deep dive on Docker security** or **multi-host networking**? Let me know! 🐳