README
¶
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)
🎯 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.26.2 or higher (Download)
- Protocol Buffers Compiler: protoc for gRPC code generation (Installation Guide)
- Make: Build automation tool
- OpenSSL: For TLS certificate operations (usually pre-installed on Linux/macOS)
Optional Tools
- golangci-lint: For code quality checks (Installation)
🚀 Installation
From Source
-
Clone the repository:
git clone https://github.com/AmadeusITGroup/CDS.git cd CDS -
Install dependencies:
go mod download -
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 -
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
# Bootstrap an agent host
cds space host add
cds space host add https://agent.example:8443
# Manage configured agent hosts
cds space host list
cds space host get https://agent.example:8443
cds space host delete https://agent.example:8443
# 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
- Fork the repository
- Create a feature branch: git checkout -b feature/amazing-feature
- Make your changes
- Run tests: make test
- Run linter: make lint
- Commit your changes: git commit -m 'Add amazing feature'
- Push to the branch: git push origin feature/amazing-feature
- 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
Directories
Click to show internal directories.
Click to hide internal directories.