✨ add docker, TLS, and OCSP zettelkasten notes

Author: chanjunren

www/docs/zettelkasten/infrastructure/docker/container_registries.md

@@ -0,0 +1,84 @@
+🗓️ 03042026 2100
+
+# container_registries
+
+**What it is:**
+- Services that store, distribute, and manage [[docker_image]] containers
+- The "Git repo" equivalent for container images — push to share, pull to deploy
+- Standardized by the [[oci_spec]] Distribution Specification
+
+**Problem it solves:**
+- Need a central place to push images from CI and pull onto production servers
+- Multi-client setups need organized image management with access control
+- Without a registry strategy: images live only on build machines, no audit trail, no scanning
+
+## Registry Types
+
+### Public (Docker Hub)
+- Default registry, largest image library
+- Free for public images
+- Rate-limited: 100 pulls/6h anonymous, 200 pulls/6h authenticated
+
+### Cloud-hosted (ECR, GCR, ACR, etc.)
+- Managed by cloud provider, integrated with their IAM and CI/CD
+- Per-repo access control, vulnerability scanning, geo-replication
+- Trade-off: convenience and integration vs. cloud lock-in
+
+### Self-hosted (Harbor, GitLab Registry)
+- Full control over access, storage, policies
+- Required when compliance mandates data stays on-premise
+- Operational burden: you manage uptime, backups, security patches
+
+## Tagging Strategies
+
+### Semantic versioning (`v1.2.3`)
+- Clear release tracking, easy rollback to known version
+- Best for production deployments
+
+### Git SHA (`abc123f`)
+- Ties image directly to source code commit
+- Best for CI/CD pipelines and debugging
+
+### `latest` tag
+- Mutable — points to different image over time
+- Never use in production; acceptable for local development only
+
+Pattern: Tag with both semver and git SHA. Use semver for human communication, SHA for traceability.
+
+## Multi-Client Access Control
+
+For deploying different client stacks from one server:
+- Organize repos by client: `registry.example.com/client-a/app`, `registry.example.com/client-b/app`
+- Per-repo pull credentials — each client stack only has access to its own images
+- Audit logs track who pulled what and when
+- Vulnerability scanning ensures no client gets deployed with known CVEs
+
+## When to Use What
+
+### Starting out / single server
+- Docker Hub (authenticated) or cloud registry with free tier
+- Simple, minimal setup
+
+### Multi-client production
+- Private registry (cloud-hosted or self-hosted) with per-client repos
+- Access control and scanning are non-negotiable
+
+### Compliance-heavy environments
+- Self-hosted (Harbor) for full data sovereignty
+- Air-gapped registries for restricted networks
+
+```ad-danger
+**Public registries expose images to everyone**: Never push images containing client data, proprietary code, or secrets to public repos. Even "unlisted" doesn't mean secure.
+```
+
+```ad-warning
+**Docker Hub rate limits**: Anonymous pulls limited to 100/6h. Production deployments should use authenticated pulls or a private registry to avoid deployment failures from rate limiting.
+```
+
+---
+
+## References
+
+- https://docs.docker.com/docker-hub/
+- https://distribution.github.io/distribution/
+- https://goharbor.io/

www/docs/zettelkasten/infrastructure/docker/docker_buildx.md

@@ -0,0 +1,90 @@
+🗓️ 03042026 2100
+
+# docker_buildx
+
+**What it is:**
+- Docker CLI plugin for extended build capabilities, powered by **BuildKit** engine
+- Replaces the legacy builder with parallel execution, better caching, and multi-platform support
+
+**Problem it solves:**
+- Default builder is sequential, slow, and lacks advanced caching
+- Building for multiple architectures (amd64 + arm64) requires separate machines or manual emulation
+- Passing secrets during build (e.g., private repo credentials) means baking them into image layers
+
+## BuildKit Improvements Over Legacy Builder
+
+### Parallel stage execution
+- [[docker_multistage_build]] stages that don't depend on each other build concurrently
+- Significant speedup for complex multi-stage builds
+
+### Better layer caching
+- Cache-mount for package managers: reuse downloaded packages across builds
+- Cache isn't invalidated as aggressively as legacy builder
+
+### Build secrets
+- `--secret` flag mounts secrets during build without persisting in [[docker_image]] layers
+- Safer than build args (`ARG`) which are visible in image history
+- Use for private registry auth, API keys needed during build
+
+### SSH forwarding
+- Mount SSH agent during build for private repo cloning
+- No SSH keys copied into image layers
+
+## Multi-Platform Builds
+
+Build for multiple architectures in a single command:
+- `--platform linux/amd64,linux/arm64` builds both
+- Uses QEMU emulation or cross-compilation
+- Push multi-arch manifest to [[container_registries]] — correct image pulled automatically based on host architecture
+- Relevant if deploying to mixed server types or ARM-based cloud instances
+
+## Cache Backends
+
+### Local cache
+- Default, stored on build machine
+- Fast but not shared across CI runners
+
+### Registry cache (`--cache-to type=registry`)
+- Push cache layers to registry, pull on next build
+- Shared across CI runners and developers
+- Trade-off: extra registry storage and pull time
+
+### GitHub Actions cache
+- Built-in integration for GitHub CI
+- Free within GitHub Actions storage limits
+
+## When to Use
+
+Use for:
+- CI/CD pipelines (parallel builds, shared caching)
+- Multi-architecture deployments
+- Builds needing private repo access (SSH, secrets)
+- Any project where build time matters
+
+Skip for:
+- Simple single-platform builds where the default builder is fast enough
+- Local development where build speed isn't a bottleneck
+
+## Enabling BuildKit
+
+- Docker Desktop: enabled by default
+- Linux servers: set `DOCKER_BUILDKIT=1` or configure in `/etc/docker/daemon.json`
+- Docker Engine 23.0+: BuildKit is the default builder
+
+See [[dockerfile_best_practices]] for writing Dockerfiles that maximize BuildKit's cache efficiency.
+
+```ad-warning
+**BuildKit may need explicit enabling on Linux servers**: Docker Desktop includes it by default, but production Linux hosts running older Docker versions need `DOCKER_BUILDKIT=1` or daemon config. Verify before assuming cache features work.
+```
+
+```ad-example
+**Build secrets**: Mount a database password during build for a migration step — `docker buildx build --secret id=db_pass,src=./secret.txt .` — the secret is available during build but never appears in any image layer.
+```
+
+---
+
+## References
+
+- https://docs.docker.com/build/buildkit/
+- https://docs.docker.com/build/building/multi-platform/
+- https://docs.docker.com/build/cache/

www/docs/zettelkasten/infrastructure/docker/docker_compose.md

@@ -19,6 +19,8 @@ A `docker-compose.yml` defines:
 ### Services
 - Containers to run
 - Each service specifies image/build context, ports, environment variables, dependencies, health checks
+- For selectively running subsets, see [[docker_compose_profiles]]
+- For reusing service definitions across clients, see [[docker_compose_extends]]
 
 ### Networks
 - How containers communicate
@@ -45,6 +47,7 @@ Skip for:
 - Only waits for containers to start, NOT for services to be ready
 - Combine with `condition: service_healthy` to wait for [[docker_healthcheck]] to pass
 - Without health checks, app might try connecting to database that's still initializing
+- For advanced dependency strategies including init containers, see [[docker_compose_dependencies]]
 
 ## Environment Variables and Config
 
@@ -54,7 +57,7 @@ Configuration options:
 - Substitute from host environment
 - Mount config files via volumes
 
-Pattern: Use environment variables for secrets and runtime config, mount files for complex configuration.
+Pattern: Use environment variables for secrets and runtime config, mount files for complex configuration. For detailed patterns, see [[docker_env_management]].
 
 ## Compose vs Orchestration
 
@@ -76,6 +79,8 @@ For production needing auto-scaling, rolling updates, self-healing: use orchestr
 **Using Compose for production scale**: Compose has no auto-scaling, no rolling updates, no multi-host support. Great for single-host deployments but not designed for production scale. Use [[docker_orchestration]] platforms instead.
 ```
 
+For resource constraints per service, see [[docker_resource_limits]]. For log management, see [[docker_logging]].
+
 ---
 
 ## References

www/docs/zettelkasten/infrastructure/docker/docker_compose_dependencies.md

@@ -0,0 +1,73 @@
+🗓️ 03042026 2100
+
+# docker_compose_dependencies
+
+**What it is:**
+- Strategies beyond basic `depends_on` to manage service startup order and readiness in [[docker_compose]]
+- Uses health checks and completion conditions to ensure services are truly ready before dependents start
+
+**Problem it solves:**
+- Basic `depends_on` only waits for container start, not readiness
+- Database container "started" but still initializing — app connects and crashes
+- In multi-client stacks, a shared database must be fully ready before any client service connects
+
+## Condition Options
+
+### `service_started` (default)
+- Waits for container to start, nothing more
+- Sufficient when the dependency starts fast or the app handles retries
+
+### `service_healthy`
+- Waits for [[docker_healthcheck]] to pass
+- The correct choice for databases, caches, message brokers — anything with initialization time
+- Requires a `healthcheck` defined on the dependency service
+
+### `service_completed_successfully`
+- Waits for a one-shot container to exit with code 0
+- Perfect for init/migration containers that must finish before the app starts
+- If the init container fails (non-zero exit), dependent services won't start
+
+## Init Container Pattern
+
+Run setup tasks before the main application:
+- Database migration container runs and exits
+- Schema seeding or data loading completes
+- App service has `depends_on` with `condition: service_completed_successfully`
+- Guarantees migrations are applied before any client traffic hits the app
+
+## Restart Policies
+
+What happens when a dependency crashes after startup:
+- `restart: unless-stopped` — restarts on crash, stays stopped if manually stopped
+- `restart: on-failure` — restarts only on non-zero exit codes
+- `restart: always` — restarts no matter what, including after host reboot
+- Choose based on whether the service should self-heal or require manual intervention
+
+## When to Skip depends_on
+
+Sometimes application-level resilience is better:
+- App has connection retry logic with backoff — more resilient than strict ordering
+- Microservices that gracefully degrade when a dependency is down
+- `depends_on` only helps at startup; it doesn't restart your app if the dependency crashes later
+
+## Transitive Dependencies
+
+A depends on B depends on C:
+- Compose resolves the chain transitively — C starts first, then B, then A
+- But startup time compounds: if C takes 30s and B takes 20s, A waits 50s+
+- Keep dependency chains shallow where possible
+
+```ad-warning
+**`service_completed_successfully` kills dependents on failure**: If the init container exits non-zero, dependent services never start. Always handle errors in init scripts and provide clear exit codes.
+```
+
+```ad-example
+**Migration container pattern**: DB starts → migration container runs `flyway migrate` and exits → app starts only after migration succeeds. This guarantees schema consistency across all client stacks.
+```
+
+---
+
+## References
+
+- https://docs.docker.com/compose/startup-order/
+- https://docs.docker.com/compose/compose-file/05-services/#depends_on

www/docs/zettelkasten/infrastructure/docker/docker_compose_extends.md

@@ -0,0 +1,82 @@
+🗓️ 03042026 2100
+
+# docker_compose_extends
+
+**What it is:**
+- Mechanisms to reuse and override Compose configuration without copy-pasting
+- Three approaches: `extends` keyword, YAML anchors (`&`/`*`/`<<`), and `x-` extension fragments
+
+**Problem it solves:**
+- Multi-client setups duplicate service definitions across files
+- Copy-pasting configs leads to drift — change one, forget the others
+- Need a way to define a base service once and override per client or environment
+
+## extends Keyword
+
+Pulls base service config from another file or same file, then overrides specific fields:
+- `extends.file` + `extends.service` references a base definition
+- Overriding file adds or replaces fields on top of base
+- Good for per-client overrides: `base.yml` defines the service, `client-a.yml` extends and customizes
+
+### Limitations
+- Cannot extend services that use `depends_on` with `condition` — restructure dependencies in the extending file
+- Lists (like `ports`, `volumes`) are appended, not replaced — can lead to duplicates
+- Single inheritance only — no chaining extends through multiple levels
+
+## YAML Anchors and Aliases
+
+DRY within a single file using native YAML:
+- `&anchor` defines a reusable block
+- `*anchor` references it
+- `<<: *anchor` merges the block into current mapping
+
+### When to prefer anchors
+- Repetitive config within one file (same [[docker_logging]] config, same resource limits for all services)
+- Simpler than extends for same-file reuse
+
+## x- Extension Fragments
+
+Compose ignores top-level keys starting with `x-`:
+- Define reusable blocks as `x-common-env`, `x-logging`, etc.
+- Reference with YAML anchors
+- Cleaner than anchors buried inside service definitions
+- Compose v2+ feature
+
+## When to Use What
+
+### extends
+- Cross-file reuse (base.yml + per-client overrides)
+- Environment-specific configs (dev.yml extends base.yml)
+
+### Anchors / x- fragments
+- Same-file repetition (shared logging, labels, deploy config)
+- Quick DRY without extra files
+
+### Separate compose files
+- When clients need fully isolated namespaces and you combine with [[docker_compose_profiles]] isn't sufficient
+- `docker compose -f base.yml -f client-a.yml up`
+
+## Trade-offs
+
+### extends
+- Compose-aware, readable, explicit inheritance
+- Limited: no list merging control, no multi-level chaining
+
+### YAML anchors
+- Flexible, works at YAML level
+- Harder to debug — resolved before Compose processes the file, mistakes produce silent wrong config
+
+```ad-warning
+**extends + depends_on condition**: `extends` cannot extend services using `depends_on` with `condition: service_healthy`. Move dependency declarations to the extending file instead.
+```
+
+```ad-danger
+**Silent anchor failures**: YAML anchors are resolved before Compose validates the file. A typo in an anchor name or wrong merge produces incorrect config with no Compose-level error — only runtime surprises.
+```
+
+---
+
+## References
+
+- https://docs.docker.com/compose/extends/
+- https://docs.docker.com/compose/compose-file/11-extension/