DOCSEARCHbyAlgolia
Submit Docs

Doco CD

repository·main·Indexed 23 days ago

https://github.com/kimdre/doco-cd

A lightweight GitOps continuous delivery tool for Docker Compose and Docker Swarm. It automates the deployment and updating of services by monitoring Git repositories or OCI artifacts via polling or webhooks. Key features include support for external secret management, SOPS encryption, Prometheus metrics, job scheduling, and a REST API for managing deployment runs and Swarm stacks.

Tokens
61.7K
Snippets
122
Records
252
Agent score
78%

What's inside doco-cd

  1. Overview of Doco CD

    main
    Doco CD is a lightweight, declarative GitOps continuous delivery tool designed for Docker. It automatically deploys and updates Docker Compose projects/services and Swarm stacks using either polling or webhooks. It serves as a lightweight alternative to tools like Portainer or ArgoCD specifically for Docker environments.

  2. Advanced features in doco-cd

    main

    Doco-CD includes several advanced capabilities for production environments:

    • Encrypted Secrets: Support for encrypting sensitive data in Git using SOPS.
    • External Secret Providers: Ability to fetch secrets from providers like OpenBao, AWS Secrets Manager, and Bitwarden.
    • Private Registries: Support for pulling images from private container registries.
    • Self-Updating: A recommended two-instance setup for automated self-updates.
    • Job Scheduling: Support for cron jobs and periodic tasks.
    • Notifications: Integration with various services to send deployment event notifications.
    • Observability: Provides a REST API for programmatic interaction and Prometheus metrics for monitoring.

  3. Overview of OCI Signature Verification in doco-cd

    main

    OCI Signature Verification is an experimental security feature in doco-cd that ensures deployment artifacts are signed by trusted entities before deployment. It protects against unauthorized deployments, artifact tampering, and compromised registries.

    Note: Signature verification is disabled by default. It must be explicitly enabled via global configuration or a per-deployment override.

  4. Overview of OCI Artifact Usage in doco-cd

    main

    Doco-CD supports pulling deployment configurations from OCI-compliant registries (e.g., Docker Hub, GHCR, ECR, etc.) instead of just Git repositories. This allows you to treat your deployment configurations as versioned artifacts, using the same registry infrastructure and workflows as your container images.

    Key capabilities:

    • Store versioned deployment configurations in OCI registries.
    • Trigger deployments via OCI webhook events.
    • Validate artifact signatures before deployment.
    • Use registries as a single source of truth for both images and configuration.

  5. How Doco-CD works using GitOps

    main

    Doco-CD operates on a GitOps model where your Git repository serves as the single source of truth for both application code and deployment configuration.

    The Workflow:

    1. A change is pushed to your Git repository.
    2. Doco-CD detects the change via a Webhook (event-based) or Polling (time-based).
    3. Doco-CD clones the repository.
    4. Doco-CD applies the desired state (defined in your docker-compose.yml and .doco-cd.yml) to your Docker environment.

  6. Target remote Docker hosts using Docker Contexts

    main

    By default, doco-cd deploys to the local Docker host via the mounted /var/run/docker.sock. To manage multiple hosts or clusters, use the context option in your deployment configuration to target a specific Docker context.

    Supported transports include:

    • TCP: tcp://host:2376 (use TLS for production).
    • TCP+TLS: Secure TCP with TLS certs.
    • SSH: ssh://user@host (uses the bundled ssh binary).

  7. Choose a Job Execution Mode

    main

    The cd.doco.job.execution_mode label determines how doco-cd manages the lifecycle of a scheduled job. Scheduled jobs never run during a deployment; they only run when the schedule triggers.

    restart mode (Default)

    In restart mode, the service is created during deployment and then re-started at the scheduled time. The service remains in the system after the job completes.

    Docker Swarm Limitation: In Swarm, restart mode jobs are deployed with 0 replicas. Because global services cannot be scaled to 0, a global service using restart mode will run on deployment. For global services, use one_off mode instead.

    one_off mode

    In one_off mode, a new ephemeral container is created for each run and removed immediately after completion.

    Note: You cannot view containers or logs for completed one_off jobs. Ensure you use persistent logging (e.g., Loki) or notifications to track job success/failure.

    Docker Swarm Behavior: one_off does not change the original service mode. Instead, doco-cd creates a temporary job service (e.g., replicated-job or global-job) for the execution and removes it afterward.

    cd.doco.job.execution_modeWhat doco-cd acts onService mode after run
    restartExisting serviceUnchanged
    one_offTemporary cloneSource unchanged

    Note: one_shot is deprecated; use one_off instead.

    services:
  backup:
    image: example/backup:latest
    labels:
      cd.doco.job.enabled: "true"
      cd.doco.job.schedule: "@every 15m"
      cd.doco.job.execution_mode: "one_off"

  9. Key features of Doco CD

    main

    Doco CD provides several capabilities for GitOps-driven Docker deployments:

    • Deployment Methods: Supports deployment via webhooks and/or polling.
    • Configuration Sources: Supports both Git repositories and OCI artifacts for deployment configurations.
    • Target Environments: Supports Docker Compose projects and Swarm stacks (in Swarm mode).
    • Security: Supports external secret management providers and data encryption via SOPS.
    • Observability: Provides Prometheus metrics and notifications.
    • Automation: Supports Job Scheduling / Cron Jobs for periodic tasks.
    • Efficiency: Built in Go with minimal RAM/CPU requirements and runs using a minimal distroless image.

  10. Understand job scheduling timezone and DST behavior

    main

    Scheduled jobs are triggered based on the timezone of the doco-cd instance. This is determined by the TZ environment variable, defaulting to UTC if not set.

    Daylight Saving Time (DST) handling:

    • Skipped times: If a scheduled time is skipped due to clocks moving forward, the job will not run at that time.
    • Duplicate times: If a scheduled time occurs twice due to clocks moving backward, the job will run at both occurrences.

  11. Handle reconciliation notifications

    main

    When a notification is triggered by a reconciliation event:

    1. The title includes a [R] marker (e.g., ✅ [R] Deployment completed).
    2. The body includes a reconciliation: metadata block.

    Metadata fields for reconciliation:

    Docker Standalone:

    • event: reconciliation event that triggered the action
    • container_id: affected container name
    • container_name: affected container name
    • trace_id: reconciliation trace ID for log correlation

    Docker Swarm:

    • event: reconciliation event that triggered the action
    • service_id: affected service name
    • service_name: affected service name
    • trace_id: reconciliation trace ID for log correlation

  12. How auto-discovery works in doco-cd

    main

    Auto-discovery allows doco-cd to automatically find and deploy projects by scanning subdirectories within a specified working_dir for Docker Compose files.

    Key Behaviors:

    • Generation: doco-cd generates new deployment configs based on the directory name and inherits settings from the root .doco-cd.yml.
    • Cleanup: If a directory/compose file is removed from the working_dir, doco-cd automatically removes the corresponding stack from the Docker host (if delete: true).
    • Nested Configs: Each discovered directory can contain its own .doco-cd.y(a)ml file to override root settings.
      • Merge Rules: Maps (like environment) are merged key-by-key; Slices (lists) are replaced if the nested value is non-empty; Scalars are overridden; Objects are merged recursively.
      • Constraint: Nested files must contain exactly one YAML document.
    # Root config
working_dir: apps/
auto_discovery:
  enabled: true
  depth: 1

# apps/wordpress/.doco-cd.yml (Nested config)
name: wordpress-prod
environment:
  WP_ENV: production