Containers Development Space (CDS)

A powerful framework for building and managing development environment containers with consistent, reproducible workflows across teams and platforms.

---

📋 Table of Contents

• Containers Development Space (CDS)
  • 📋 Table of Contents
  • 🎯 Overview
    • Why CDS?
  • ✨ Features
  • 📦 Prerequisites
    • Optional Tools
  • 🚀 Installation
    • From Source
  • ⚡ Quick Start
    • Running the CDS Client
    • Running the API Agent
    • Generate TLS Certificates
    • Run Tests
  • 📖 Usage
    • Client Commands
    • Configuration
    • Working with Projects
    • Certificate Management
  • 🏗️ Project Structure
    • Key Directories
  • 🛠️ Development
    • Building from Source
    • Generating Protocol Buffers
    • Code Quality
    • Dependency Management
    • Platform-Specific Notes
      • Windows
      • Linux
      • macOS
  • 🤝 Contributing
    • Getting Started
    • Development Guidelines
    • Code Style
    • Testing
    • Reporting Issues
  • 📄 License
  • 🙏 Acknowledgments
    • References & Resources
  • 📞 Support

---

🎯 Overview

Containers Development Space (CDS) is a Go-based framework designed to streamline the creation, management, and orchestration of development environment containers (devcontainers). CDS provides a structured approach to building consistent development environments that work seamlessly across different machines, operating systems, and team configurations.

Why CDS?

• Consistency: Ensure all developers work in identical environments
• Portability: Development environments that work on Linux, macOS, and Windows
• Security: Built-in TLS/SSL support with certificate management
• Integration: Native support for Git, Artifactory, and Bitbucket
• Extensibility: Modular architecture with gRPC-based APIs

---

✨ Features

• 🐳 Container Orchestration: Build and manage development containers with ease
• 🔐 Secure Communication: Built-in TLS/SSL certificate generation and management
• 🌐 gRPC API: High-performance API for agent-based communication
• 🔄 SCM Integration: Native support for Git, Bitbucket, and other version control systems
• 📦 Artifact Management: Integration with JFrog Artifactory
• 🖥️ Cross-Platform: Support for Linux, macOS, and Windows
• 🔧 Systemd Integration: Native systemd support for Linux environments
• 📊 Structured Logging: Advanced logging with Go's log/slog
• 🧪 Testing Framework: Comprehensive test suite using Ginkgo and Gomega
• 🎨 Rich CLI: Beautiful terminal output with pterm

---

📦 Prerequisites

Before installing CDS, ensure you have the following dependencies:

• Go: Version 1.24.0 or higher (Download)
• Protocol Buffers Compiler: protoc for gRPC code generation (Installation Guide)
• Make: Build automation tool
  • Linux/macOS: Usually pre-installed
  • Windows: Use Git Bash or WSL
• OpenSSL: For TLS certificate operations (usually pre-installed on Linux/macOS)

Optional Tools

• golangci-lint: For code quality checks (Installation)

---

🚀 Installation

From Source

1. Clone the repository:

   git clone https://github.com/AmadeusITGroup/CDS.git
   cd CDS

2. Install dependencies:

   go mod download

3. Install Protocol Buffer tools:

   go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
   go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

4. Build the project:

   make install

---

⚡ Quick Start

Running the CDS Client

make run-client

Running the API Agent

make run-api-agent

Generate TLS Certificates

make gencert

Run Tests

make test

---

📖 Usage

Client Commands

The CDS client provides several commands for managing your development spaces:

# Initialize a new project
cds project init

# Initialize a new space
cds space init

# Check version
cds version

Configuration

CDS configuration is stored in ~/.cds/ directory. You can customize settings through:

• Configuration files
• Environment variables
• Command-line flags

Working with Projects

# Create a new project scaffold
make scaffold

Certificate Management

Generate and manage TLS certificates for secure communication:

# Verify certificates
openssl verify -CAfile ca_cert.pem server_cert.pem

# Inspect certificate details
openssl x509 -in server_cert.pem -text -noout

---

🏗️ Project Structure

CDS/
├── cmd/                    # Application entry points
│   ├── api-agent/         # API agent service
│   └── client/            # CDS CLI client
├── internal/              # Private application code
│   ├── agent/            # Agent implementation
│   ├── api/              # gRPC API definitions
│   ├── ar/               # Artifactory integration
│   ├── authmgr/          # Authentication management
│   ├── bo/               # Business objects
│   ├── bootstrap/        # Application bootstrapping
│   ├── cenv/             # Environment management
│   ├── cerr/             # Error handling
│   ├── clog/             # Logging framework
│   ├── command/          # CLI commands
│   ├── config/           # Configuration management
│   ├── db/               # Database/storage layer
│   ├── host/             # Host management
│   ├── profile/          # Profile management
│   ├── scm/              # Source control management
│   ├── shexec/           # Shell execution utilities
│   ├── systemd/          # Systemd integration
│   ├── term/             # Terminal utilities
│   └── tls/              # TLS/certificate management
├── test/                  # Test resources
├── go.mod                 # Go module definition
├── makefile               # Build automation
└── LICENSE                # Apache 2.0 License

Key Directories

• cmd/: Contains the main applications. Each subdirectory is a separate executable.
• internal/: Private packages not intended for external import. Contains the core business logic.
• test/: Test fixtures, resources, and integration tests.

---

🛠️ Development

Building from Source

# Build all binaries
make build

# Build specific components
make build-client
make build-api-agent

Generating Protocol Buffers

When modifying .proto files:

make build-pb

Or manually:

protoc --go_out=. --go_opt=paths=source_relative \
       --go-grpc_out=. --go-grpc_opt=paths=source_relative \
       internal/api/v1/*.proto

Code Quality

# Run linter
make lint

# Run linter with auto-fix
make lint-weak

# Run tests
make test

# Generate coverage report
make coverage

Dependency Management

# Tidy dependencies
make go-tidy

Platform-Specific Notes

Windows

• Use Git Bash or Windows Subsystem for Linux (WSL) to run make commands
• Ensure paths are properly escaped when working with Windows paths

Linux

• Systemd integration is available for service management
• Check systemd service files in internal/systemd/

macOS

• Boot configuration available in internal/bootstrap/boot_darwin.go

---

🤝 Contributing

We welcome contributions from the community! Here's how you can help:

Getting Started

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: make test
5. Run linter: make lint
6. Commit your changes: git commit -m 'Add amazing feature'
7. Push to the branch: git push origin feature/amazing-feature
8. Open a Pull Request

Development Guidelines

• Follow Go best practices and idioms
• Write comprehensive tests for new features
• Update documentation for API changes
• Ensure all tests pass before submitting PR
• Keep commits atomic and well-described

Code Style

This project uses golangci-lint to enforce code quality. Run the linter before submitting:

make lint

Testing

• Write unit tests for new functionality
• Update integration tests when changing APIs
• Aim for high test coverage

Reporting Issues

Found a bug? Have a feature request? Please open an issue with:

• Clear description of the problem
• Steps to reproduce (for bugs)
• Expected vs actual behavior
• Environment details (OS, Go version, etc.)

---

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

---

🙏 Acknowledgments

Built with these excellent open-source projects:

• Go - The Go Programming Language
• gRPC - High-performance RPC framework
• Protocol Buffers - Data serialization
• Cobra - CLI framework
• Viper - Configuration management
• Ginkgo & Gomega - Testing framework
• pterm - Beautiful terminal output
• go-git - Git implementation in Go

References & Resources

• TLS/Certificate Management: Inspired by Cloudflare CFSSL
• Logging: Built with Go's log/slog - Guide
• Observability: OpenTelemetry for Go
• gRPC Instrumentation: OpenTelemetry gRPC

---

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with ❤️ by the CDS community