Skip to main content

Complete Agent Docker Project Structure

# Complete Agent Docker Project Structure

## Full Production-Ready Structure for `/common_npm/agent-docker/`

agent-docker/ .agents/ # OSSA v0.1.9 agent definitions orchestrators/ container-orchestrator/ agent.yml openapi.yml behaviors/ container-orchestrator.behavior.yml image-management.behavior.yml network-orchestration.behavior.yml data/ orchestration-config.yml running-containers.yml state/ handlers/ container.handlers.ts compose.handlers.ts integrations/ docker-engine/ kubernetes/ swarm/ schemas/ input/ output/ compose-orchestrator/ [same structure]

workers/
   image-builder/
      [full agent structure]
   container-manager/
      [full agent structure]
   registry-manager/
      [full agent structure]
   volume-manager/
       [full agent structure]

monitors/
   container-monitor/
      [full agent structure]
   resource-monitor/
      [full agent structure]
   health-monitor/
       [full agent structure]

integrators/
   docker-hub-integrator/
      [full agent structure]
   ecr-integrator/
      [full agent structure]
   harbor-integrator/
       [full agent structure]

critics/
   dockerfile-analyzer/
       [full agent structure]

registry.yml                 # Central agent registry

frontend/ # Next.js 14+ App Router (Docker Dashboard) app/ (containers)/ layout.tsx dashboard/ page.tsx containers/ page.tsx [id]/ page.tsx logs/ page.tsx exec/ page.tsx images/ page.tsx [id]/ page.tsx volumes/ page.tsx networks/ page.tsx compose/ page.tsx (registry)/ registry/ page.tsx builds/ page.tsx api/ proxy/[...path]/ route.ts layout.tsx page.tsx error.tsx

components/
   ui/
      container-card.tsx
      image-list.tsx
      log-viewer.tsx
      terminal.tsx
      resource-gauge.tsx
   forms/
      container-create-form.tsx
      dockerfile-editor-form.tsx
      compose-editor-form.tsx
   layouts/
      docker-layout.tsx
   features/
       container-list.tsx
       image-layers.tsx
       network-topology.tsx
       volume-browser.tsx
       resource-monitor.tsx

hooks/
   use-docker.ts
   use-containers.ts
   use-logs.ts

lib/
   docker-client.ts
   stream-logs.ts

next.config.js
package.json

backend/ # Express 5 API (Docker Management Server) src/ api/ http/ routes/ v1/ containers.routes.ts images.routes.ts volumes.routes.ts networks.routes.ts compose.routes.ts registry.routes.ts controllers/ containers.controller.ts images.controller.ts volumes.controller.ts networks.controller.ts compose.controller.ts middleware/ auth.middleware.ts docker.middleware.ts rate-limit.middleware.ts error.middleware.ts websocket/ server.ts handlers/ logs.handler.ts stats.handler.ts adapters/ docker-to-dto.adapter.ts response.adapter.ts

   cli/
      commands/
         container.command.ts
         image.command.ts
         compose.command.ts
         registry.command.ts
      utils/
          docker-inspect.ts
          cli.util.ts
  
   docker/                   # Docker core implementations
      engine/
         docker-client.ts
         container-engine.ts
         image-engine.ts
      compose/
         compose-parser.ts
         compose-validator.ts
         stack-manager.ts
      build/
         dockerfile-builder.ts
         build-context.ts
         layer-cache.ts
      registry/
          registry-client.ts
          manifest-parser.ts
  
   services/
      domain/
         container.service.ts
         image.service.ts
         volume.service.ts
         network.service.ts
         compose.service.ts
         registry.service.ts
      adapters/
         postgres.adapter.ts
         redis.adapter.ts
         docker.adapter.ts
         docker-hub.adapter.ts
         ecr.adapter.ts
         harbor.adapter.ts
      ports/
          container.repository.ts
          image.repository.ts
          docker.provider.ts
  
   config/
      env/
         docker.env.ts
         registry.env.ts
      schemas/
         docker.schema.ts
      defaults/
          docker.defaults.ts
  
   types/
      dto/
         container.dto.ts
         image.dto.ts
         compose.dto.ts
      models/
         container.model.ts
         image.model.ts
         network.model.ts
      errors/
          docker.error.ts
  
   utils/
      validation/
         dockerfile.validator.ts
      parsing/
         compose.parser.ts
         dockerfile.parser.ts
      logging/
          logger.factory.ts
  
   index.ts                  # Bootstrap

tests/
   unit/
      docker/
      services/
      setup/
   integration/
      containers/
      setup/
   e2e/
       specs/

package.json

lib/ # NPM Package Exports (Docker SDK) index.ts client/ docker-client.ts container-client.ts image-client.ts server/ docker-server.ts container-manager.ts registry-server.ts compose/ compose-client.ts stack-manager.ts types.ts

shared/ # Shared between frontend/backend types/ docker.types.ts container.types.ts compose.types.ts constants/ docker.constants.ts

templates/ # Docker templates dockerfiles/ node.Dockerfile python.Dockerfile multi-stage.Dockerfile compose/ development.yml production.yml

infrastructure/ docker/ frontend.Dockerfile backend.Dockerfile agent.Dockerfile compose/ docker-compose.yml k8s/ [kubernetes configs]

docs/ architecture/ docker-integration.md container-lifecycle.md guides/ dockerfile-best-practices.md compose-guide.md api/ openapi.yaml

examples/ basic/ simple-container.ts build-image.ts advanced/ multi-stage-build.ts compose-stack.ts

openapi/ agent-docker.openapi.yml schemas/ docker.schema.yml

bin/ agent-docker.js

.gitlab-ci.yml ossa.config.yaml package.json tsconfig.json README.md LICENSE


## Key Configuration Files

### `ossa.config.yaml`
```yaml
ossa:
  version: "0.1.9"
  compliance_level: "gold"
  namespace: "agent-docker"
  registry:
    url: "https://ossa-registry.bluefly.io"
  agents:
    base_path: ".agents"
    auto_discover: true
  docker:
    socket: "/var/run/docker.sock"
    registries:
      - docker.io
      - ecr
      - harbor
    compose_version: "3.9"

[object Object]

// Bootstrap - wiring only
import express from 'express';
import { createServer } from 'http';
import { WebSocketServer } from './api/websocket/server';
import { configureRoutes } from './api/http/routes';
import { DockerClient } from './docker/engine/docker-client';
import { ContainerEngine } from './docker/engine/container-engine';

const app = express();
const httpServer = createServer(app);

// Initialize Docker client
DockerClient.getInstance().initialize();
ContainerEngine.getInstance().initialize();

// Start WebSocket for logs/stats streaming
new WebSocketServer(httpServer);

// Configure routes
configureRoutes(app);

httpServer.listen(3000);

This structure provides:

  • Complete Docker container management
  • Image building and registry management
  • Docker Compose support
  • Volume and network management
  • Real-time logs and stats streaming
  • Multi-registry support (Docker Hub, ECR, Harbor)
  • Dockerfile analysis and validation
  • Container orchestration
  • Resource monitoring
  • Full OSSA compliance

```sh
 Currently In Progress

  - Express routes and controllers (partially done - containers route created)

   Remaining Backend Tasks

  1. Create controllers for all Docker operations (containers, images, volumes, networks,
  compose, registry, system)
  2. Create middleware (auth, validation, error handling, logging, docker connectivity)
  3. Create validation schemas for all API endpoints
  4. Create utility functions (async handlers, logger factory, response formatters)
  5. Set up WebSocket streaming for real-time logs, stats, and events

   Frontend Tasks

  6. Build Next.js Docker dashboard with:
    - Container management UI
    - Image operations interface
    - Real-time monitoring dashboard
    - Volume and network management
    - Docker Compose stack management

   Additional Files Needed

  - 5 more route files (images, volumes, networks, compose, system, registry)
  - 6 controller files for each route group
  - 4-5 middleware files (auth, validation, error, logging, docker)
  - Validation schemas for all API endpoints
  - Logger factory and utilities
  - WebSocket server with event handlers
  - Complete Next.js frontend (10-15 components)

  We've completed about 25% of the backend implementation. The foundation is solid with Docker
   engines, types, constants, and OSSA agents. Now we need to finish the Express API layer and
   build the frontend dashboard.

  Should I continue with the controllers, middleware, and remaining backend components first,
  or would you prefer to see the WebSocket implementation or frontend development?