Runtainer - Container Orchestrator

🐳 Runtainer is a powerful REST + Socket.IO microservice designed to orchestrate containers with CCW (Container Control Worker) pre-installed for Node.js, Python, Rust, Go, and Java environments. It provides real-time control over filesystem, network, and shell operations through a secure, token-based authentication system.

🚀 Features

Multi-Language Support: Pre-built images for Node.js, Python, Rust, Go, and Java with CCW integration
Real-time Control: WebSocket support for live filesystem, network, and shell operations
Secure Authentication: Master tokens and per-container JWT tokens with scoped permissions
ZIP Initialization: Create containers from scratch or initialize with ZIP archives
REST + WebSocket APIs: Comprehensive HTTP REST API with WebSocket support for real-time operations
Production Ready: Docker support, health checks, graceful shutdown, and structured logging

🏃 Quick Start

Using Docker Compose (Recommended)

# Clone the repository
git clone https://github.com/sammwyy/runtainer.git
cd runtainer

# Start the services
make docker-up

# The server will be available at http://localhost:8080

Local Development

# Install dependencies
make deps

# Start development server
make run

# Or with hot reloading
make dev

💾 Installation

Prerequisites

Go 1.21+
Docker and Docker Compose
Make (optional, for convenience commands)

Build from Source

# Build server binary
make build

# Build CLI client
make build-cli

# Build both
make build-all

Using Pre-built Binaries

Download the latest release from the releases page.

⚙️ Configuration

Runtainer uses environment variables for configuration:

Variable	Default	Description
`RUNTIME_MASTER_TOKEN`	`default-master-token`	Master authentication token
`PORT`	`8080`	Server port
`DOCKER_HOST`	`unix:///var/run/docker.sock`	Docker daemon socket
`ALLOWED_IMAGES`	`ccw-node:latest,ccw-python:latest,...`	Comma-separated list of allowed images
`MAX_CONTAINERS`	`10`	Maximum number of containers
`CONTAINER_TIMEOUT`	`3600`	Container timeout in seconds

Example Configuration

export RUNTIME_MASTER_TOKEN="your-secure-master-token"
export PORT="8080"
export MAX_CONTAINERS="20"
export CONTAINER_TIMEOUT="7200"

📚 API Documentation

Authentication

All API requests require authentication via Bearer token:

curl -H "Authorization: Bearer your-master-token" \
     http://localhost:8080/containers

Container Management

Create Container

POST /containers

Request Body:

{
  "image": "ccw-node:latest",
  "config": {
    "env": {"NODE_ENV": "development"},
    "ports": [{"host": 3000, "container": 3000}],
    "volumes": [{"host_path": "/data", "container_path": "/app/data"}]
  },
  "initZipBase64": "UEsDBBQAAAAIA..." // optional
}

Response:

{
  "container_id": "uuid-here",
  "instance_token": "jwt.token.here",
  "status": "created",
  "ccw_port": 49160
}

List Containers

GET /containers

Get Container

GET /containers/{id}

Start Container

POST /containers/{id}/start

Stop Container

POST /containers/{id}/stop

Delete Container

DELETE /containers/{id}

CCW Integration

File System Operations

# List directory
GET /containers/{id}/fs/listdir?path=/app

# Write file
POST /containers/{id}/fs/write
{
  "path": "/app/file.txt",
  "content": "Hello World"
}

Network Operations

# Download file
POST /containers/{id}/net/download
{
  "url": "https://example.com/file.zip",
  "path": "/app/file.zip"
}

Shell Operations

# Execute command
POST /containers/{id}/shell/exec
{
  "command": "ls",
  "args": ["-la"],
  "workdir": "/app"
}

🖥️ CLI Usage

The Runtainer CLI provides a convenient way to manage containers from the command line.

Installation

# Build CLI
make build-cli

# Or download from releases

Basic Commands

# Set your master token
export RUNTAINER_TOKEN="your-master-token"
export RUNTAINER_URL="http://localhost:8080"

# List containers
./bin/runtainer-cli -token=$RUNTAINER_TOKEN -cmd=list

# Create a new Node.js container
./bin/runtainer-cli -token=$RUNTAINER_TOKEN -cmd=create -image=ccw-node:latest

# Create with configuration file
./bin/runtainer-cli -token=$RUNTAINER_TOKEN -cmd=create -image=ccw-python:latest -config=config.json

# Start a container
./bin/runtainer-cli -token=$RUNTAINER_TOKEN -cmd=start -id=container-id

# Stop a container
./bin/runtainer-cli -token=$RUNTAINER_TOKEN -cmd=stop -id=container-id

# Delete a container
./bin/runtainer-cli -token=$RUNTAINER_TOKEN -cmd=delete -id=container-id

# Get container status
./bin/runtainer-cli -token=$RUNTAINER_TOKEN -cmd=status -id=container-id

Configuration Files

Create JSON configuration files for container creation:

node-config.json:

{
  "env": {
    "NODE_ENV": "development",
    "PORT": "3000"
  },
  "ports": [
    {"host": 3000, "container": 3000}
  ],
  "volumes": [
    {"host_path": "/tmp/node-data", "container_path": "/app/data"}
  ]
}

Examples

# Generate example configurations
make mock-data

# Show CLI usage examples
make examples

🔌 WebSocket Events

Connect to WebSocket endpoints for real-time container interaction:

// Connect to container WebSocket
const ws = new WebSocket('ws://localhost:8080/ws/containers/container-id?token=your-token');

// File system events
ws.send(JSON.stringify({
  type: 'fs',
  event: 'watch',
  req_id: 'req-1'
}));

// Shell operations
ws.send(JSON.stringify({
  type: 'shell',
  event: 'spawn',
  req_id: 'req-2'
}));

// Network monitoring
ws.send(JSON.stringify({
  type: 'net',
  event: 'monitor:start',
  req_id: 'req-3'
}));

Supported Events

File System: fs:watch, fs:listdir, fs:change
Network: net:monitor:start, net:port:changes
Shell: shell:spawn, shell:input, shell:output, shell:kill

🛠️ Development

Setup Development Environment

# Install dependencies
make deps

# Run tests
make test

# Run tests with coverage
make test-coverage

# Format code
make fmt

# Lint code
make lint

# Start development server with hot reloading
make dev

Project Structure

runtainer/
├── cmd/                   # Application entry points
│   ├── server/            # Main server application
│   └── cli/               # CLI client application
├── internal/              # Private application code
│   ├── auth/              # Authentication middleware and JWT handling
│   ├── config/            # Configuration management
│   ├── container/         # Container business logic
│   ├── ccw/               # CCW client integration
│   └── websocket/         # WebSocket handling
├── pkg/                   # Public packages
│   ├── logger/            # Structured logging
│   └── errors/            # Custom error types
├── api/                   # API route definitions
├── test-data/             # Test configuration files
├── bin/                   # Built binaries
└── tmp/                   # Development hot-reload files

Testing

# Run unit tests
go test ./...

# Run tests with verbose output
make test

# Generate coverage report
make test-coverage

# Run specific package tests
go test ./internal/container -v

Adding New Features

Create Feature Branch: git checkout -b feature/new-feature
Implement Changes: Follow Go best practices and project structure
Add Tests: Ensure good test coverage for new code
Update Documentation: Update README and API documentation
Submit PR: Create a pull request with detailed description

Code Style Guidelines

Use gofmt for formatting
Follow Go naming conventions
Add meaningful comments for exported functions
Use structured logging with context
Handle errors properly with custom error types
Write tests for all public functions

🚀 Production Deployment

Docker Deployment

# Build production image
make docker-build

# Deploy with Docker Compose
docker-compose -f docker-compose.prod.yml up -d

Kubernetes Deployment

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: runtainer
spec:
  replicas: 3
  selector:
    matchLabels:
      app: runtainer
  template:
    metadata:
      labels:
        app: runtainer
    spec:
      containers:
      - name: runtainer
        image: runtainer:latest
        ports:
        - containerPort: 8080
        env:
        - name: RUNTIME_MASTER_TOKEN
          valueFrom:
            secretKeyRef:
              name: runtainer-secrets
              key: master-token
        - name: MAX_CONTAINERS
          value: "50"
        - name: CONTAINER_TIMEOUT
          value: "7200"
        volumeMounts:
        - name: docker-sock
          mountPath: /var/run/docker.sock
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 5
      volumes:
      - name: docker-sock
        hostPath:
          path: /var/run/docker.sock
---
apiVersion: v1
kind: Service
metadata:
  name: runtainer-service
spec:
  selector:
    app: runtainer
  ports:
  - port: 80
    targetPort: 8080
  type: LoadBalancer

Environment-Specific Configurations

Production Environment Variables

# Security
export RUNTIME_MASTER_TOKEN="$(openssl rand -base64 32)"

# Performance
export MAX_CONTAINERS="100"
export CONTAINER_TIMEOUT="14400"  # 4 hours

# Monitoring
export LOG_LEVEL="info"
export METRICS_ENABLED="true"

# Docker
export DOCKER_HOST="unix:///var/run/docker.sock"

Health Checks and Monitoring

# Health check endpoint
curl http://localhost:8080/health

# Expected response
{
  "status": "healthy",
  "service": "runtainer", 
  "version": "1.0.0"
}

Security Considerations

Token Security: Use strong, randomly generated master tokens
Network Security: Deploy behind a reverse proxy with SSL/TLS
Container Isolation: Use Docker security features and user namespaces
Resource Limits: Configure memory and CPU limits for containers
Access Control: Implement proper RBAC for production deployments

Scaling

Horizontal Scaling: Deploy multiple Runtainer instances behind a load balancer
Container Limits: Adjust MAX_CONTAINERS based on available resources
Resource Monitoring: Monitor CPU, memory, and disk usage
Auto-scaling: Implement auto-scaling based on container demand

📊 Monitoring and Logging

Structured Logging

Runtainer uses structured logging with contextual information:

logger.Info("Container created", "id", containerID, "image", image)
logger.Error("Failed to start container", "id", containerID, "error", err)

Metrics Collection

Integration points for metrics collection:

Container creation/destruction rates
Active container count
API request rates and latencies
WebSocket connection counts
Resource usage per container

Log Aggregation

For production deployments, consider log aggregation with:

ELK Stack (Elasticsearch, Logstash, Kibana)
Grafana + Prometheus for metrics
Jaeger for distributed tracing

🔧 Troubleshooting

Common Issues

Container Creation Fails

# Check Docker daemon
docker info

# Verify image availability
docker images | grep ccw

# Check logs
tail -f /var/log/runtainer.log

Authentication Errors

# Verify master token
curl -H "Authorization: Bearer $RUNTIME_MASTER_TOKEN" \
     http://localhost:8080/health

# Check JWT token expiration
# Tokens expire after 24 hours by default

WebSocket Connection Issues

# Test WebSocket connection
wscat -c "ws://localhost:8080/ws/containers/container-id?token=your-token"

# Check firewall settings
sudo iptables -L

Performance Issues

# Monitor resource usage
docker stats

# Check container limits
docker inspect container-id | grep -i memory

# Review logs for bottlenecks
journalctl -u runtainer -f

Debug Mode

Enable debug logging for development:

export LOG_LEVEL="debug"
make run

Getting Help

Check Documentation: Review this README and API documentation
Search Issues: Look through GitHub Issues
Create Issue: Report bugs or request features
Community Support: Join our Discord/Slack community

🤝 Contributing

We welcome contributions from the community! Here's how to get started:

Development Setup

Fork the Repository
Clone Your Fork: git clone https://github.com/sammwyy/runtainer.git
Create Branch: git checkout -b feature/amazing-feature
Install Dependencies: make deps
Make Changes: Follow our coding standards
Run Tests: make test
Commit Changes: git commit -m 'Add amazing feature'
Push Branch: git push origin feature/amazing-feature
Open Pull Request

Contribution Guidelines

Code Quality: Maintain high code quality with tests
Documentation: Update documentation for new features
Backward Compatibility: Avoid breaking changes when possible
Security: Follow security best practices
Performance: Consider performance implications

Types of Contributions

🐛 Bug Reports: Report issues with detailed reproduction steps
🚀 Feature Requests: Suggest new features or improvements
📝 Documentation: Improve documentation and examples
🧪 Testing: Add tests and improve test coverage
🎨 UI/UX: Improve CLI interface and user experience

📜 License

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

🙏 Acknowledgments

Fiber Framework: Fast HTTP framework for Go
Docker: Container platform
JWT: JSON Web Token standard
WebSocket: Real-time communication protocol
Go Community: Amazing ecosystem and libraries

📞 Support

GitHub Issues: https://github.com/sammwyy/runtainer/issues

Built with ❤️ by Sammwy

Runtainer makes container orchestration simple, secure, and scalable.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
api		api
cmd		cmd
internal		internal
pkg		pkg
.air.toml		.air.toml
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
TODO.md		TODO.md
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum

Folders and files

Latest commit

History

Repository files navigation