📝 Docker notes / virtualization

Author: chanjunren

www/.claude/rules/zettelkasten.mdc

@@ -6,56 +6,58 @@ alwaysApply: false
 # Zettelkasten: atomic notes for learning and reference
 
 ## Structure
-- Template: 🗓️ created datetime (DDMMYYYY HHmm), h1 title, content, References
+- Template: 🗓️ datetime (DDMMYYYY HHmm), h1 title, content, References
 - Filename = h1 title (snake_case)
 - One atomic concept per note
-- Organized by topic subdirectories (backend, frontend, infrastructure, etc.)
 
-## Writing Style
-- **Core Concept**: Point form bullets when multiple aspects, one sentence if single aspect
-- Structure: **Core Concept → Why → When to Use → Trade-offs**
-- Short sentences. Bullets. No fluff. Cut ruthlessly.
-- Minimize analogies (only if genuinely clarifying)
-- Focus on concepts, not code (unless cheatsheet requested)
+## Content
 
-## Content Requirements
+**Opening (required):**
+- **What it is**: Clear definition (1-2 sentences)
+- **Problem it solves**: Why this concept exists
 
-**Must have:**
-- Core Concept
-- Why it matters (1-2 sentences)
+**Body (use if relevant):**
 - When to use / when not to use
-- Trade-offs
-
-**Optional:**
 - Key distinctions (A vs B)
-- Common pitfalls
-- Comparisons
-- Common patterns (conceptual only)
+- Trade-offs or gotchas
+- How it works (high-level only)
+
+**Style:**
+- Point form by default (bullet points, short statements)
+- Use h3 headings for subsections instead of bolded items
+- Bold key terms on first mention
+- Cut ruthlessly - details only if they aid understanding
+- No historical background unless it explains WHY
+- No obvious explanations
 
-**Only if user asks for cheatsheet:**
-- Quick Reference (syntax/code examples)
-- Implementation examples
-- Configuration snippets
+## Formatting
 
-**Forbidden:**
-- Excessive analogies or mental models
-- Historical background (unless explains WHY)
-- Code examples (unless cheatsheet requested)
-- Obvious explanations
+**Headings:**
+- h2 for main sections, h3 for subsections
+- Never use h4+
+- Use natural headings (not generic "Why", "When")
+- Prefer h3 subsections over bolded list items for structure
 
-## Linking
-- Link inline with explicit relationship: "This builds on [[prerequisite]] because..."
+**Tables:**
+- Definitions of related terms
+- Comparisons
+- Structured data
+
+**Links:**
+- Inline naturally: "See [[other_note]] for X"
+- NO "related to X because..." explanations
 - NO "Related Concepts" sections
 - Link only when: prerequisite, contrast, or logical next step
 
-## Formatting
-- h2-h3 for sections
-- Bold key terms on first mention
-- Tables for comparisons
-- Admonitions sparingly (max 2): `ad-warning`, `ad-danger`, `ad-example`
-
-## Accuracy
-- Verify facts before writing
-- Search credible sources when uncertain
-- Only link to notes that exist
-- Cite sources for complex information
+**Admonitions:**
+- Max 2 per note
+- Types: `ad-warning`, `ad-danger`, `ad-example`
+- Use for: common pitfalls, critical gotchas, important examples
+- Keep concise (1-2 sentences)
+
+**References:**
+- Only verified sources at bottom
+
+## Code/Implementation
+- Default: concepts only, no code
+- If user asks for cheatsheet: add Quick Reference section with syntax/examples

www/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(mkdir:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

www/docs/zettelkasten/backend/os/virtualization.md

@@ -0,0 +1,119 @@
+🗓️ 12112024 0930
+
+# virtualization
+
+**What it is:**
+- Technology that creates isolated virtual versions of computing resources
+- Abstracts physical hardware from software
+- Enables multiple operating systems or applications to run on single physical machine
+
+**Problem it solves:**
+- Running multiple workloads on dedicated hardware is wasteful and inflexible
+- Without virtualization: need separate physical machines for each application
+- Result: Poor resource utilization, high costs, difficult migration
+
+## Hardware vs OS-level Virtualization
+
+**Hardware virtualization (VMs):**
+- Each virtual machine runs complete OS with own kernel on top of hypervisor
+- Full isolation between VMs
+- Heavier resource overhead
+
+**OS-level virtualization (containers):**
+- Multiple isolated user spaces share same kernel
+- Lightweight and fast
+- Can only run applications compatible with host kernel
+- See [[docker_overview]] for container details
+
+Key distinction: VMs virtualize hardware (can run different OS types), containers virtualize OS (share kernel).
+
+## Hypervisor Types
+
+**Type 1 (Bare Metal):**
+- Runs directly on hardware without host OS
+- Examples: VMware ESXi, Hyper-V, KVM, Xen
+- Better performance, lower overhead
+- Used in production data centers and cloud infrastructure
+
+**Type 2 (Hosted):**
+- Runs on top of host OS
+- Examples: VirtualBox, VMware Workstation, Parallels
+- Easier to set up, more overhead
+- Used for development and testing
+
+Pattern: Type 1 for production workloads and server consolidation. Type 2 for development and desktop virtualization.
+
+## VMs vs Containers
+
+**VMs:**
+- Full OS per instance, GBs in size, minutes to start
+- Complete kernel isolation
+- Use when need different OS types on same hardware, maximum security isolation, or legacy applications requiring specific OS versions
+
+**Containers:**
+- Shared kernel, MBs in size, seconds to start
+- Process-level isolation
+- Use when application-level isolation sufficient, need fast startup/scaling, want resource efficiency, or building microservices
+- Covered in [[docker_overview]]
+
+Pattern: VMs for OS isolation, containers for application isolation. Or combine: run containers within VMs for both levels.
+
+## When to Use VMs
+
+Use for:
+- Multiple OS environments on single hardware
+- Strong isolation between workloads for security
+- Legacy application support requiring specific OS versions
+- Disaster recovery with snapshots and migration
+- Resource consolidation to reduce hardware costs
+- Dev/test environments isolated from production
+
+Skip for:
+- Performance-critical applications where overhead unacceptable
+- Simple application isolation (containers more lightweight)
+- Resource-constrained environments
+- Bare-metal performance required (GPUs, high-frequency trading)
+
+## Key Benefits and Trade-offs
+
+**Benefits:**
+- Complete OS isolation
+- Run different OS types on same hardware
+- Strong security boundaries
+- Hardware independence
+- Easy backup/recovery with snapshots
+- Live migration between hosts
+
+**Drawbacks:**
+- Resource overhead (each VM runs full OS)
+- Slower startup times
+- Larger storage requirements
+- More complex management
+- License costs for guest operating systems
+
+## Virtualization in Cloud Computing
+
+Cloud IaaS built on virtualization:
+- AWS EC2, Azure VMs, Google Compute Engine
+- On-demand virtual machines without managing physical hardware
+- Cloud provider handles hypervisor layer
+
+For container workloads in cloud, see [[docker_orchestration]] for managing containerized applications at scale.
+
+## Common Pitfalls
+
+```ad-warning
+**Over-provisioning VMs**: Allocating too many resources (CPU, RAM) wastes capacity. VMs don't use what they're allocated, they use what they need. Monitor actual usage and right-size allocations.
+```
+
+```ad-danger
+**VM sprawl**: Unmanaged VM creation leads to wasted resources and security risks. Implement VM lifecycle policies, regular audits, and automated cleanup of unused VMs.
+```
+
+---
+
+## References
+
+- https://www.vmware.com/topics/glossary/content/virtualization.html
+- https://www.redhat.com/en/topics/virtualization/what-is-virtualization
+- https://aws.amazon.com/what-is/virtualization/

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

@@ -0,0 +1,84 @@
+🗓️ 11112024 1450
+
+# docker_compose
+
+**What it is:**
+- Tool for defining and running multi-container applications
+- Uses YAML configuration file
+- Single command starts entire application stack with dependencies, networks, volumes
+
+**Problem it solves:**
+- Running multi-container apps with `docker run` means typing long commands for each service
+- Must manually create networks, manage startup order, remember all flags
+- Compose replaces this with declarative config file and simple commands
+
+## Structure
+
+A `docker-compose.yml` defines:
+
+### Services
+- Containers to run
+- Each service specifies image/build context, ports, environment variables, dependencies, health checks
+
+### Networks
+- How containers communicate
+
+### Volumes
+- Persistent data
+
+## When to Use
+
+Use for:
+- Multi-container applications (app + database + cache)
+- Local development environments with multiple services
+- Integration testing requiring full stack
+- Small single-host production deployments
+
+Skip for:
+- Single containers (just use `docker run`)
+- Production at scale (use [[docker_orchestration]] like Kubernetes)
+- Multi-host deployments needing auto-scaling and rolling updates
+
+## Dependency Management
+
+`depends_on` controls startup order:
+- 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
+
+## Environment Variables and Config
+
+Configuration options:
+- Set inline in YAML
+- Load from `.env` files
+- Substitute from host environment
+- Mount config files via volumes
+
+Pattern: Use environment variables for secrets and runtime config, mount files for complex configuration.
+
+## Compose vs Orchestration
+
+Differences:
+- Compose: Single-host, development-focused
+- [[docker_orchestration]]: Multi-host, production-grade
+- Compose orchestrates containers but doesn't manage clusters
+- Many start with Compose for dev, move to Kubernetes for prod
+
+For production needing auto-scaling, rolling updates, self-healing: use orchestration platforms.
+
+## Common Pitfalls
+
+```ad-warning
+**Ignoring health checks**: Using `depends_on` without health checks means dependent services start before dependencies are ready. Always add [[docker_healthcheck]] to services that need startup time.
+```
+
+```ad-danger
+**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.
+```
+
+---
+
+## References
+
+- https://docs.docker.com/compose/
+- https://docs.docker.com/compose/compose-file/