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
- 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

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

Name		Name	Last commit message	Last commit date
.github		.github
cmd		cmd
internal		internal
test		test
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
SUPPORT.md		SUPPORT.md
go.mod		go.mod
go.sum		go.sum
makefile		makefile
makefile.delivery		makefile.delivery

Uh oh!

Latest commit

History

Folders and files

Repository files navigation