first version of the knowledge base :)

40 - Guides/containers/docker-basics.md

@@ -0,0 +1,125 @@
+---
+title: Docker Basics
+description: Practical introduction to Docker images, containers, and everyday command-line workflows
+tags:
+  - containers
+  - docker
+  - linux
+category: containers
+created: 2026-03-14
+updated: 2026-03-14
+---
+
+# Docker Basics
+
+## Introduction
+
+Docker packages applications and their dependencies into images that run as isolated containers. For homelab and developer workflows, it is commonly used to deploy repeatable services without building a full virtual machine for each workload.
+
+## Purpose
+
+Docker is useful when you need:
+
+- Repeatable application packaging
+- Simple local development environments
+- Fast service deployment on Linux hosts
+- Clear separation between host OS and application runtime
+
+## Architecture Overview
+
+Core Docker concepts:
+
+- Image: immutable application package template
+- Container: running instance of an image
+- Registry: source for pulling and pushing images
+- Volume: persistent storage outside the writable container layer
+- Network: connectivity boundary for one or more containers
+
+Typical flow:
+
+```text
+Dockerfile -> Image -> Registry or local cache -> Container runtime
+```
+
+## Step-by-Step Guide
+
+### 1. Verify Docker is installed
+
+```bash
+docker version
+docker info
+```
+
+### 2. Pull and run a container
+
+```bash
+docker pull nginx:stable
+docker run -d --name web -p 8080:80 nginx:stable
+```
+
+### 3. Inspect the running container
+
+```bash
+docker ps
+docker logs web
+docker exec -it web sh
+```
+
+### 4. Stop and remove it
+
+```bash
+docker stop web
+docker rm web
+```
+
+## Configuration Example
+
+Run a service with a persistent named volume:
+
+```bash
+docker volume create app-data
+docker run -d \
+  --name app \
+  -p 3000:3000 \
+  -v app-data:/var/lib/app \
+  ghcr.io/example/app:latest
+```
+
+Inspect resource usage:
+
+```bash
+docker stats
+```
+
+## Troubleshooting Tips
+
+### Container starts and exits immediately
+
+- Check `docker logs <container>`
+- Verify the image's default command is valid
+- Confirm required environment variables or mounted files exist
+
+### Port publishing does not work
+
+- Verify the service is listening inside the container
+- Confirm the host port is not already in use
+- Check host firewall rules
+
+### Data disappears after recreation
+
+- Use a named volume or bind mount instead of the writable container layer
+- Confirm the application writes data to the mounted path
+
+## Best Practices
+
+- Pin images to a known tag and update intentionally
+- Use named volumes for application state
+- Prefer non-root containers when supported by the image
+- Keep containers single-purpose and externalize configuration
+- Use Compose for multi-service stacks instead of long `docker run` commands
+
+## References
+
+- [Docker: Docker overview](https://docs.docker.com/get-started/docker-overview/)
+- [Docker: Get started](https://docs.docker.com/get-started/)
+- [Docker: Volumes](https://docs.docker.com/engine/storage/volumes/)