docker_skill

Overview

This skill manages Docker containerization and docker-compose orchestration for the Sorcha platform. It provides patterns and runnable commands to build, run, and debug multi-service stacks using distroless (chiseled) images, multi-stage builds, health checks, and shared networks.

How this skill works

The skill inspects and edits docker-compose YAML and Dockerfiles to define services, networks, volumes, and health checks. It guides adding new microservices, rebuilding single services after code changes, and starting just infrastructure components for development. It also prescribes secure runtime images, multi-stage build stages, and common service dependency patterns.

When to use it

• Starting or stopping the full Sorcha stack locally for development or testing
• Adding a new microservice and wiring it into docker-compose with proper env, volumes, and depends_on
• Rebuilding a single service after code changes without bringing down the entire stack
• Running database or messaging infrastructure only (infrastructure-only compose)
• Debugging container startup, health checks, or inter-service networking issues

Best practices

• Use multi-stage Dockerfiles: build with the SDK stage, publish artifacts, and run with a chiseled distroless runtime stage
• Prefer chiseled/distroless runtime images for smaller attack surface and consistent production parity
• Declare health checks and use depends_on with service_healthy to manage startup ordering
• Centralize shared environment blocks using YAML anchors to avoid drift and ensure consistent telemetry/jwt settings
• Mount persistent volumes for keys and state (e.g., dataprotection-keys) and place services on a shared bridge network for DNS resolution

Example use cases

• Start the full stack: docker-compose up -d and tail logs for a specific service
• Rebuild and replace a single service after code edits: docker-compose build <service> && docker-compose up -d --force-recreate <service>
• Run only infrastructure for front-end or Aspire development: docker-compose -f docker-compose.infrastructure.yml up -d
• Add a new .NET microservice: create multi-stage Dockerfile, add service block with env anchors, volumes, and depends_on
• Resolve networking issues by testing service DNS (http://<service-name>:<port>) on the shared bridge network