[Feature] Add Docker Engine Support for Local Development and Simple Deployments

[JacksonMei]

Checklist

• This feature will maintain backward compatibility with the current APIs in api-service/controller/ and api-service/service/. If not, please raise a refactor issue first.

Background

Is your feature request related to an enhancement or a new use case? Please describe.

Current Situation: AEnvironment currently only supports Kubernetes as the sandbox engine through the Controller component. While Kubernetes provides excellent orchestration capabilities for production environments, it requires a full Kubernetes cluster setup, which can be complex for local development, testing, and small-scale deployments.

Use Cases:

1. Local Development: Developers want to test and develop environments locally without requiring a Kubernetes cluster
2. CI/CD Pipelines: Integration testing in CI/CD environments where Kubernetes might be overkill or unavailable
3. Small-Scale Deployments: Users who need AEnvironment capabilities but don't have Kubernetes infrastructure
4. Docker Compose Integration: Support for Docker Compose-based deployments for simpler multi-container setups
5. Edge Computing: Lightweight deployments on edge devices or single-node servers

Benefits:

• Lower barrier to entry for new users
• Faster iteration cycles for development
• Reduced infrastructure complexity for small deployments
• Better alignment with Docker-native workflows
• Enables Docker Compose-based multi-service deployments

Potential Solution

A clear and concise description of the potential implementation or how similar features are handled in other frameworks.

Implementation Approach

1. Docker Engine Adapter: Implement a DockerEngine adapter that implements the SandboxEngine interface (as defined in the sandbox engine abstraction refactor)

   type DockerEngine struct {
       dockerClient *docker.Client
       config       *DockerEngineConfig
   }
   
   func (e *DockerEngine) CreateInstance(ctx context.Context, spec *InstanceSpec) (*Instance, error) {
       // Create Docker container from image
       // Configure networking, volumes, environment variables
       // Start container and return instance info
   }

2. Docker Compose Support: Extend the Docker engine to support Docker Compose for multi-container environment deployments

   # docker-compose.yml for AEnvironment
   version: '3.8'
   services:
     aenv-instance:
       image: ${AENV_IMAGE}
       environment:
         - AENV_ENV_NAME=${ENV_NAME}
       volumes:
         - ./workspace:/workspace
       networks:
         - aenv-network

3. Container Lifecycle Management:

   • Container creation with proper resource limits (CPU, memory)
   • Health checks and status monitoring
   • Log aggregation and streaming
   • Volume management for persistent storage
   • Network isolation and port mapping

4. Configuration:

   • Add Docker engine configuration to API Service
   • Support Docker daemon connection (local socket or remote)
   • Environment variable-based engine selection: AENV_SANDBOX_ENGINE=docker
   • Docker-specific settings (network mode, volume mounts, etc.)

5. Integration Points:

   • Extend api-service/engine/factory.go to support Docker engine creation
   • Add Docker-specific instance spec fields (network config, volume mounts)
   • Implement Docker health checks and status polling
   • Support Docker Compose file parsing and deployment

Similar Implementations

• Docker-in-Docker (DinD): Similar to how CI/CD systems use Docker for containerized builds
• Docker Desktop Integration: Leverage Docker Desktop's API for local development
• Portainer: Uses Docker API for container management, similar approach
• Docker Compose: Standard tooling for multi-container orchestration

Deployment Modes

1. Standalone Docker: Single Docker daemon for simple deployments
2. Docker Swarm: Docker's native orchestration for multi-host deployments
3. Docker Compose: File-based multi-container deployments
4. Remote Docker: Connect to remote Docker daemon via TCP/TLS

Additional Information

Related Issues/PRs

• Sandbox Engine Abstraction refactor (prerequisite)
• Architecture documentation: docs/architecture/architecture.md mentions Docker Compose Mode as "Planning"

Technical Considerations

1. Resource Management: Docker's resource limits vs Kubernetes resource requests/limits
2. Networking: Docker bridge networks vs Kubernetes service networking
3. Storage: Docker volumes vs Kubernetes persistent volumes
4. Scaling: Docker Swarm vs Kubernetes horizontal scaling
5. Security: Docker security contexts vs Kubernetes security policies

Configuration Example

# api-service config
sandbox:
  engine: docker
  docker:
    host: unix:///var/run/docker.sock
    network_mode: bridge
    default_network: aenv-network
    compose_enabled: true
    resource_limits:
      cpu: "2.0"
      memory: "4Gi"

Testing Strategy

• Unit tests for Docker engine adapter
• Integration tests with Docker daemon
• Docker Compose deployment tests
• Performance comparison with Kubernetes engine
• Local development workflow validation

Documentation Updates Needed

• Docker engine setup guide
• Docker Compose deployment guide
• Local development workflow documentation
• Migration guide from Kubernetes to Docker (if applicable)
• Architecture diagram updates

Community Impact

This feature significantly lowers the barrier to entry for AEnvironment adoption, enabling:

• Developers to get started without Kubernetes knowledge
• Small teams to deploy AEnvironment with minimal infrastructure
• Better integration with existing Docker-based workflows
• Easier contribution and testing for community members