DDC Quick Start Guide

Get up and running with DDC (Dievilz Deploy Control) in 5 minutes.

Installation

Option 1: Download Binary (Fastest)

# Linux
curl -L https://github.com/dievilz/ddc/releases/latest/download/ddc-linux-amd64 -o ddc
chmod +x ddc
sudo mv ddc /usr/local/bin/

# macOS
curl -L https://github.com/dievilz/ddc/releases/latest/download/ddc-darwin-amd64 -o ddc
chmod +x ddc
sudo mv ddc /usr/local/bin/

Option 2: Build from Source

git clone https://github.com/dievilz/ddc.git
cd ddc
make build
sudo cp build/ddc /usr/local/bin/

Verify Installation

ddc version

Example 1: Publish Docker Image

Step 1: Build your Docker image locally

docker build -t myapp:v1.0.0 .

Step 2: Configure registry credentials

export REGISTRY_PROD_URL=registry.example.com
export REGISTRY_PROD_USERNAME=myuser
export REGISTRY_PROD_PASSWORD=mypassword

Step 3: Configure image details

export IMAGE_NAME=myapp
export IMAGE_TAG=v1.0.0

Step 4: Publish with DDC

ddc run publish-image

Expected Output

╔═══════════════════════════════════════════════════════════╗
║                                                           ║
║   DDC — Dievilz Deploy Control                           ║
║   CI/CD Action Executor                                   ║
║                                                           ║
╚═══════════════════════════════════════════════════════════╝

============================================================
[+0.001s] PHASE: Initializing
============================================================
[+0.002s] INFO: Action: publish-image
[+0.003s] INFO: Version: 0.1.0

============================================================
[+0.010s] PHASE: Detecting Capabilities
============================================================
[+0.011s] INFO: Discovered 1 capabilities
[+0.012s] INFO:   ✓ registry-prod [docker-registry] - available

============================================================
[+0.015s] PHASE: Executing Action: publish-image
============================================================
[+0.016s] INFO: Validation passed
[+0.017s] INFO: Found 1 available capabilities
[+0.018s] INFO: Attempting capability: registry-prod (type: docker-registry)
[+2.341s] INFO: ✓ Success with registry-prod (duration: 2.325s)
[+2.342s] INFO: Policy satisfied: 1/1 successful executions

============================================================
[+2.343s] PHASE: Execution Complete: SUCCESS
============================================================
[+2.344s] INFO: Total duration: 2.343s
[+2.345s] INFO: Successes: 1, Failures: 0
[+2.346s] INFO: Result written to: ddc-result.json

============================================================
[+2.350s] PHASE: Final Result
============================================================
[+2.351s] INFO: Decision: SUCCESS
[+2.352s] INFO: Reason: Policy satisfied: 1/1 successful executions
[+2.353s] INFO: Exit Code: 0

Example 2: Deploy Docker Compose Stack

Step 1: Prepare your docker-compose.yml

version: '3.8'
services:
  web:
    image: registry.example.com/myapp:v1.0.0
    ports:
      - "80:8080"
    restart: unless-stopped

Step 2: Configure SSH target

export SSH_PROD_HOST=server.example.com
export SSH_PROD_USER=deploy
export SSH_PROD_KEY=~/.ssh/id_rsa

Step 3: Configure deployment

export COMPOSE_FILE=docker-compose.yml
export PROJECT_NAME=myapp
export REMOTE_DIR=/opt/myapp

Step 4: Deploy with DDC

ddc run deploy-compose

Example 3: Multi-Registry Publish with Fallback

Publish to multiple registries with automatic fallback:

# Primary registry
export REGISTRY_PRIMARY_URL=registry1.example.com
export REGISTRY_PRIMARY_USERNAME=user1
export REGISTRY_PRIMARY_PASSWORD=pass1

# Backup registry
export REGISTRY_BACKUP_URL=registry2.example.com
export REGISTRY_BACKUP_USERNAME=user2
export REGISTRY_BACKUP_PASSWORD=pass2

# Image details
export IMAGE_NAME=myapp
export IMAGE_TAG=v1.0.0

# Policy: require at least 1 success, try primary first
export DDC_MIN_SUCCESS=1
export DDC_PRIORITY_ORDER=registry-primary,registry-backup

# Execute
ddc run publish-image --verbose

Result: DDC will try the primary registry first. If it fails, it automatically falls back to the backup registry.

Example 4: Redundant Deployment to Multiple Hosts

Deploy to multiple production servers:

# Configure multiple hosts
export SSH_PROD1_HOST=prod1.example.com
export SSH_PROD1_USER=deploy
export SSH_PROD1_KEY=~/.ssh/id_rsa

export SSH_PROD2_HOST=prod2.example.com
export SSH_PROD2_USER=deploy
export SSH_PROD2_KEY=~/.ssh/id_rsa

# Deployment config
export COMPOSE_FILE=docker-compose.yml
export PROJECT_NAME=myapp

# Policy: require BOTH to succeed
export DDC_MIN_SUCCESS=2

# Execute
ddc run deploy-compose

Result: DDC deploys to both servers and only reports success if both deployments succeed.

GitLab CI Integration

Add to your .gitlab-ci.yml:

deploy:
  stage: deploy
  image: alpine:latest
  before_script:
    - apk add --no-cache docker-cli curl openssh-client
    - curl -L https://github.com/dievilz/ddc/releases/latest/download/ddc-linux-amd64 -o /usr/local/bin/ddc
    - chmod +x /usr/local/bin/ddc
  script:
    - ddc run publish-image
  only:
    - main

GitHub Actions Integration

Add to your .github/workflows/deploy.yml:

- name: Publish with DDC
  env:
    REGISTRY_PROD_URL: ${{ secrets.REGISTRY_URL }}
    REGISTRY_PROD_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
    REGISTRY_PROD_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
    IMAGE_NAME: myapp
    IMAGE_TAG: ${{ github.sha }}
  run: |
    curl -L https://github.com/dievilz/ddc/releases/latest/download/ddc-linux-amd64 -o ddc
    chmod +x ddc
    ./ddc run publish-image

Understanding the Result File

DDC always generates a ddc-result.json file:

{
  "ActionName": "publish-image",
  "StartTime": "2024-01-15T10:30:00Z",
  "EndTime": "2024-01-15T10:30:02Z",
  "TotalDuration": 2340000000,
  "CapabilitiesEvaluated": ["registry-prod"],
  "Attempts": [
    {
      "CapabilityName": "registry-prod",
      "Success": true,
      "Error": "",
      "Attempt": 1,
      "Duration": 2325000000,
      "Metadata": {
        "image_ref": "registry.example.com/myapp:v1.0.0",
        "registry": "registry.example.com",
        "pushed_at": "2024-01-15T10:30:02Z"
      }
    }
  ],
  "SuccessCount": 1,
  "FailureCount": 0,
  "PolicySatisfied": true,
  "Decision": "SUCCESS",
  "Reason": "Policy satisfied: 1/1 successful executions",
  "Artifacts": {
    "image_ref": "registry.example.com/myapp:v1.0.0"
  }
}

Use this in CI/CD pipelines to make decisions or pass data to subsequent jobs.

Common Patterns

Pattern 1: Fail Fast

Stop immediately on first failure:

export DDC_FAIL_FAST=true
ddc run publish-image

Pattern 2: Retry Failed Operations

Retry up to 3 times per capability:

export DDC_MAX_RETRIES=3
ddc run publish-image

Pattern 3: Require All to Succeed

When deploying to multiple targets:

export DDC_MIN_SUCCESS=3  # If you have 3 targets
ddc run deploy-compose

Pattern 4: Verbose Logging

Get detailed debug information:

ddc run publish-image --verbose

Troubleshooting

"No capabilities found"

Problem: No registries or hosts configured.

Solution: Check your environment variables match the naming pattern:

Registries: REGISTRY_<NAME>_URL, REGISTRY_<NAME>_USERNAME, etc.
SSH hosts: SSH_<NAME>_HOST, SSH_<NAME>_USER, etc.

"docker command not found"

Problem: Docker CLI not available.

Solution: Install Docker CLI or run DDC from a container with Docker.

"Policy not satisfied"

Problem: Not enough successful executions.

Solution: Check the ddc-result.json file to see which capabilities failed and why. Adjust DDC_MIN_SUCCESS if needed.

"Validation failed"

Problem: Missing required environment variables.

Solution: Run with --verbose to see which variables are missing:

ddc run publish-image --verbose

Exit Codes

Code	Meaning	Action
0	Success	Continue pipeline
1	Policy not met	Check capabilities and retry
2	Invalid config	Fix environment variables
3	No capabilities	Configure registries/hosts
4	Action failed	Check logs and fix issues
5	Validation failed	Provide required inputs

Next Steps

Read the full README.md for comprehensive documentation
Check examples/ for CI/CD integration examples
Read TECHNICAL_SUMMARY.md to understand the design
See CONTRIBUTING.md to contribute

Getting Help

Issues: https://github.com/dievilz/ddc/issues
Discussions: https://github.com/dievilz/ddc/discussions
Examples: See the examples/ directory

You're ready to use DDC! Start with simple examples and gradually adopt more advanced patterns.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DDC Quick Start Guide

Installation

Option 1: Download Binary (Fastest)

Option 2: Build from Source

Verify Installation

Example 1: Publish Docker Image

Step 1: Build your Docker image locally

Step 2: Configure registry credentials

Step 3: Configure image details

Step 4: Publish with DDC

Expected Output

Example 2: Deploy Docker Compose Stack

Step 1: Prepare your docker-compose.yml

Step 2: Configure SSH target

Step 3: Configure deployment

Step 4: Deploy with DDC

Example 3: Multi-Registry Publish with Fallback

Example 4: Redundant Deployment to Multiple Hosts

GitLab CI Integration

GitHub Actions Integration

Understanding the Result File

Common Patterns

Pattern 1: Fail Fast

Pattern 2: Retry Failed Operations

Pattern 3: Require All to Succeed

Pattern 4: Verbose Logging

Troubleshooting

"No capabilities found"

"docker command not found"

"Policy not satisfied"

"Validation failed"

Exit Codes

Next Steps

Getting Help

FilesExpand file tree

QUICKSTART.md

Latest commit

History

QUICKSTART.md

File metadata and controls

DDC Quick Start Guide

Installation

Option 1: Download Binary (Fastest)

Option 2: Build from Source

Verify Installation

Example 1: Publish Docker Image

Step 1: Build your Docker image locally

Step 2: Configure registry credentials

Step 3: Configure image details

Step 4: Publish with DDC

Expected Output

Example 2: Deploy Docker Compose Stack

Step 1: Prepare your docker-compose.yml

Step 2: Configure SSH target

Step 3: Configure deployment

Step 4: Deploy with DDC

Example 3: Multi-Registry Publish with Fallback

Example 4: Redundant Deployment to Multiple Hosts

GitLab CI Integration

GitHub Actions Integration

Understanding the Result File

Common Patterns

Pattern 1: Fail Fast

Pattern 2: Retry Failed Operations

Pattern 3: Require All to Succeed

Pattern 4: Verbose Logging

Troubleshooting

"No capabilities found"

"docker command not found"

"Policy not satisfied"

"Validation failed"

Exit Codes

Next Steps

Getting Help