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

40 - Guides/containers/docker-compose-patterns.md

@@ -0,0 +1,156 @@
+---
+title: Docker Compose Patterns
+description: Reusable patterns for structuring Docker Compose applications in homelab and development environments
+tags:
+  - containers
+  - docker
+  - compose
+category: containers
+created: 2026-03-14
+updated: 2026-03-14
+---
+
+# Docker Compose Patterns
+
+## Introduction
+
+Docker Compose defines multi-container applications in a single declarative file. It is a good fit for homelab stacks, local development, and small self-hosted services that do not require a full orchestrator.
+
+## Purpose
+
+Compose helps when you need:
+
+- Repeatable service definitions
+- Shared networks and volumes for a stack
+- Environment-specific overrides
+- A clear deployment artifact that can live in Git
+
+## Architecture Overview
+
+A Compose application usually includes:
+
+- One or more services
+- One or more shared networks
+- Persistent volumes
+- Environment variables and mounted configuration
+- Optional health checks and startup dependencies
+
+## Step-by-Step Guide
+
+### 1. Start with a minimal Compose file
+
+```yaml
+services:
+  app:
+    image: ghcr.io/example/app:1.2.3
+    ports:
+      - "8080:8080"
+```
+
+Start it:
+
+```bash
+docker compose up -d
+docker compose ps
+```
+
+### 2. Add persistent storage and configuration
+
+```yaml
+services:
+  app:
+    image: ghcr.io/example/app:1.2.3
+    ports:
+      - "8080:8080"
+    environment:
+      APP_BASE_URL: "https://app.example.com"
+    volumes:
+      - app-data:/var/lib/app
+
+volumes:
+  app-data:
+```
+
+### 3. Add dependencies with health checks
+
+```yaml
+services:
+  db:
+    image: postgres:16
+    environment:
+      POSTGRES_DB: app
+      POSTGRES_USER: app
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U app"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    volumes:
+      - db-data:/var/lib/postgresql/data
+
+  app:
+    image: ghcr.io/example/app:1.2.3
+    depends_on:
+      db:
+        condition: service_healthy
+    environment:
+      DATABASE_URL: postgres://app:${POSTGRES_PASSWORD}@db:5432/app
+    ports:
+      - "8080:8080"
+
+volumes:
+  db-data:
+```
+
+## Common Patterns
+
+### Use one project directory per stack
+
+Keep the Compose file, `.env` example, and mounted config together in one directory.
+
+### Use user-defined networks
+
+Private internal services should communicate over Compose networks rather than the host network.
+
+### Prefer explicit volumes
+
+Named volumes are easier to back up and document than anonymous ones.
+
+### Use profiles for optional services
+
+Profiles are useful for dev-only services, one-shot migration jobs, or optional observability components.
+
+## Troubleshooting Tips
+
+### Services start in the wrong order
+
+- Use health checks instead of only container start order
+- Ensure the application retries database or dependency connections
+
+### Configuration drift between hosts
+
+- Commit the Compose file to Git
+- Keep secrets out of the file and inject them separately
+- Avoid host-specific bind mount paths when portability matters
+
+### Containers cannot resolve each other
+
+- Check that the services share the same Compose network
+- Use the service name as the hostname
+- Verify the application is not hard-coded to `localhost`
+
+## Best Practices
+
+- Omit the deprecated top-level `version` field in new Compose files
+- Keep secrets outside the Compose YAML when possible
+- Pin images to intentional versions
+- Use health checks for stateful dependencies
+- Treat Compose as deployment code and review changes like application code
+
+## References
+
+- [Docker: Compose file reference](https://docs.docker.com/reference/compose-file/)
+- [Docker: Compose application model](https://docs.docker.com/compose/intro/compose-application-model/)
+- [Docker: Control startup and shutdown order in Compose](https://docs.docker.com/compose/how-tos/startup-order/)
+- [Compose Specification](https://compose-spec.io/)