← Documentation Home

Agent Docker Developer Guide

Overview

Package: @bluefly/agent-docker Version: 0.1.0 License: MIT

AI-powered Docker container orchestration and management platform with OSSA v0.1.9 compliance. Provides intelligent container lifecycle management, image operations, and multi-registry support.

Key Features

Installation

npm install @bluefly/agent-docker

# Or globally for CLI
npm install -g @bluefly/agent-docker

Quick Start

CLI Usage

# List containers
agent-docker container list

# Create and start container
agent-docker container create nginx --name web-server -p 8080:80

# Build image
agent-docker image build -t my-app:latest .

# Deploy Compose stack
agent-docker compose deploy -f docker-compose.yml my-stack

# Check system health
agent-docker health

API Usage

import { DockerClient } from '@bluefly/agent-docker';

const client = new DockerClient({
  baseUrl: 'http://localhost:3000',
  apiKey: 'your-api-key'
});

// List containers
const containers = await client.listContainers({ all: true });

// Create container
const result = await client.createContainer({
  name: 'my-app',
  image: 'nginx:latest',
  ports: { '80/tcp': [{ HostPort: '8080' }] },
  environment: ['NODE_ENV=production']
});

// Start container
await client.startContainer(result.id);

API Reference

Container Operations

createContainer(options)

Create a new container.

Parameters: - name (string): Container name - image (string): Image to use - ports (object): Port mappings - environment (string[]): Environment variables - volumes (object): Volume mounts - command (string[]): Override default command

Returns: Promise<{id: string, warnings: string[]}>

startContainer(id)

Start a container.

stopContainer(id, timeout?)

Stop a container gracefully.

removeContainer(id, options?)

Remove a container.

Image Operations

buildImage(options)

Build Docker image from Dockerfile.

await client.buildImage({
  context: '/path/to/build/context',
  tag: 'my-app:latest',
  dockerfile: 'Dockerfile',
  buildArgs: {
    NODE_VERSION: '20'
  }
});

pullImage(name, options?)

Pull image from registry.

pushImage(name, options?)

Push image to registry.

Network Operations

createNetwork(options)

Create Docker network.

await client.createNetwork({
  name: 'app-network',
  driver: 'bridge',
  ipam: {
    config: [{ subnet: '172.20.0.0/16' }]
  }
});

Volume Operations

createVolume(options)

Create Docker volume.

await client.createVolume({
  name: 'app-data',
  driver: 'local',
  driverOpts: {
    type: 'nfs',
    device: ':/path/to/dir'
  }
});

Configuration

Environment Variables

# API Server
NODE_ENV=production
API_PORT=3000
DOCKER_SOCKET_PATH=/var/run/docker.sock

# Database
POSTGRES_URL=postgresql://user:pass@localhost:5432/agent_docker
REDIS_URL=redis://localhost:6379

# Authentication
JWT_SECRET=your-jwt-secret
API_KEY=your-api-key

# Monitoring
PROMETHEUS_PORT=9090
GRAFANA_PORT=3002

OSSA Configuration

ossa.config.yaml:

ossa:
  version: '0.1.9'
  compliance_level: 'gold'
  namespace: 'agent-docker'
  agents:
    base_path: '.agents'
    auto_discover: true
  docker:
    socket: '/var/run/docker.sock'
    registries: [docker.io, ecr, harbor]

Examples

Multi-Container Application

// Deploy full stack
await client.composeUp({
  projectName: 'my-stack',
  services: {
    web: {
      image: 'nginx:latest',
      ports: ['80:80'],
      depends_on: ['api']
    },
    api: {
      build: './api',
      environment: ['DATABASE_URL=postgresql://db:5432/app'],
      depends_on: ['db']
    },
    db: {
      image: 'postgres:15',
      volumes: ['db-data:/var/lib/postgresql/data']
    }
  },
  volumes: {
    'db-data': {}
  }
});

Security Scanning

// Scan image for vulnerabilities
const scan = await client.scanImage('my-app:latest');

console.log('Vulnerabilities:', scan.vulnerabilities);
console.log('Risk Level:', scan.riskLevel);
console.log('Recommendations:', scan.recommendations);

Kubernetes Generation

# Generate Kubernetes manifests from Docker Compose
agent-docker k8s generate --project ./infrastructure

# Validate manifests
agent-docker k8s validate --manifest-dir ./infrastructure/generated

Agent Architecture

Agent Docker includes 11 specialized OSSA agents:

Orchestrators

Workers

Monitors

Critics

Integrators

Observability

Metrics

# Prometheus metrics endpoint
curl http://localhost:9090/metrics

# Key metrics:
# - agent_docker_containers_total
# - agent_docker_images_total
# - agent_docker_build_duration_seconds
# - agent_docker_registry_operations_total

Grafana Dashboards

Pre-built dashboards available in infrastructure/grafana/: - Container Performance Overview - Image Build Metrics - Registry Operations - Security Scan Results

Testing

# Run tests
npm test

# Integration tests
npm run test:integration

# OSSA validation
ossa validate .agents/

# Agent orchestration test
npm run agents:orchestrate

Deployment

Docker

# Run via Docker Compose
npm run docker:up

Kubernetes

# Deploy
kubectl apply -f infrastructure/kubernetes/

# Check status
kubectl get pods -n agent-docker

Documentation