OCI Artifact Usage¶

This page provides comprehensive documentation on using doco-cd with OCI (Open Container Initiative) artifacts, including webhook payloads, and artifact packaging conventions.

Overview¶

Doco-CD supports pulling deployment configurations from OCI registries (e.g., Docker Hub, GitHub Container Registry, private registries) in addition to Git repositories. This allows you to:

• Store deployment configuration as versioned OCI artifacts
• Use container registries as your source of truth for deployments
• Trigger deployments via OCI webhook events
• Validate artifact signatures before deployment
• Use the same registry infrastructure for both container images and configuration

Getting Started¶

To use OCI artifacts with doco-cd, you need to:

1. Package your deployment configuration according to the doco.v1 layout specification, see the example below for details.
2. Push the artifact to an OCI registry
3. Configure doco-cd with either polling or webhooks to pull the artifact and trigger deployments
4. (Optional) Configure signature verification with trust policies

Supported OCI Registries¶

Doco-cd can pull artifacts from any OCI-compliant registry that supports OCI Image Spec v1.0 or later. This includes, but is not limited to:

• Docker Hub (docker.io)
• GitHub Container Registry (ghcr.io)
• GitLab Container Registry (registry.gitlab.com)
• Amazon ECR (*.dkr.ecr.*.amazonaws.com)
• Google Artifact Registry (*.pkg.dev)
• Azure Container Registry (*.azurecr.io)
• Private/Self-hosted registries (supporting OCI Image Spec v1.0+)

doco.v1 Artifact Layout¶

The doco.v1 layout (see version in deploy config) is a strict, versioned specification for packaging deployment configurations as OCI artifacts. It ensures consistency and enables validation.

Artifact Structure¶

A doco.v1 artifact must have a root-level deployment configuration file (.doco-cd.y(a)ml) in the root (/) of the artifact.

The rest of the artifact can contain any files needed for deployment, as with deployments from Git repository (e.g., compose files, app configuration, assets, scripts), see Deploy Settings.

artifact-root/
├── .doco-cd.yaml        # Main deployment config
├── docker-compose.yml    # Docker Compose configuration
└── (other files as needed)

artifact-root/
├── .doco-cd.yaml        # Main deployment config
├── web/
│   ├── .doco-cd.yaml    # Extra deployment config for web service
│   └── docker-compose.yml
│   └── config/
│       └── nginx.conf
└── app/
    └── docker-compose.yml
    └── app.env
    └── migrations/
        └── 001-init.sql

Required Files¶

• .doco-cd.y(a)ml: Required

  The main deployment configuration file.

  .doco-cd.yaml Example

  name: production
  compose_files:
    - docker-compose.yml
  profiles:
    - production
  

Example: Creating an OCI Artifact¶

Here's a complete example of creating and pushing a doco.v1 OCI artifact:

1. Create the artifact directory

   mkdir -p artifact
   
   # Create deployment configuration
   cat > artifact/.doco-cd.yaml << 'EOF'
   name: web-app
   compose_files:
     - docker-compose.yml
   EOF
   
   # Create docker-compose.yml
   cat > artifact/docker-compose.yml << 'EOF'
   services:
     nginx:
       image: nginx:latest
   EOF
   

2. Create the OCI artifact

   Using Docker CLIUsing OCI tools

   # Create a minimal Dockerfile inside the artifact directory
   cat > artifact/Dockerfile << 'EOF'
   FROM scratch
   COPY . /
   EOF
   
   # Build and push the artifact
   docker build -t ghcr.io/myorg/myapp-config:main artifact/
   docker push ghcr.io/myorg/myapp-config:main
   

   We use skopeo to copy the directory directly to an OCI registry without needing to create a Docker image:

   # Using skopeo or similar tools
   skopeo copy dir://artifact oci:oras-artifact:latest