# Django Docker Container Manager
[](https://badge.fury.io/py/django-container-manager)
[](https://pypi.org/project/django-container-manager/)
[](https://docs.djangoproject.com/)
[](https://opensource.org/licenses/MIT)
**The most comprehensive Docker container management system for Django.** Execute Django commands inside Docker containers with complete lifecycle tracking, resource monitoring, and multi-platform support. Eliminate the complexity of Celery/RQ while gaining powerful containerized job execution.
Transform your Django application into a container orchestration platform with full observability, automatic resource management, and production-ready security controls.
## Why Choose This Over Celery?
- **🎯 Django-native design**: Built for Django from the ground up, not adapted from generic queuing
- **🐳 Container-first architecture**: Docker containers as first-class execution environments with full isolation
- **📊 Complete observability**: Track every aspect of job execution - logs, metrics, resource usage, timings
- **🔧 Zero infrastructure dependencies**: No Redis, RabbitMQ, or external queue management required
- **🌐 Multi-cloud ready**: Single codebase supports local Docker, remote hosts, Google Cloud Run, AWS Fargate
- **⚡ Production hardened**: Built-in security controls, resource limits, error handling, and monitoring
- **🔍 Real-time visibility**: Django admin integration with live job status and log viewing
## ✨ Key Features
- 🐳 **Multi-executor support**: Docker local/remote, Google Cloud Run, AWS Fargate, Mock executor
- 📊 **Complete lifecycle tracking**: Status monitoring, logs, metrics, and resource usage
- 🎛️ **Django admin integration**: Beautiful web interface with real-time job monitoring
- 🔧 **Background job processor**: Automatic container job execution and management
- 📦 **Environment management**: Template-based environment variables with job-level overrides
- 🔒 **Production security**: TLS support, resource limits, container isolation, and safe execution
- 📈 **Resource monitoring**: Memory and CPU usage tracking with configurable limits
- 🌐 **Cloud-native**: Built for containerized environments and cloud deployment
## 🏗️ Architecture Overview
```mermaid
graph TD
A[Django Management Command] --> B[ContainerJob Model]
B --> C[ExecutorHost Selection]
C --> D[Docker/Cloud Executor]
D --> E[Container Launch]
E --> F[Real-time Monitoring]
F --> G[Log Collection]
G --> H[Resource Tracking]
H --> I[Cleanup & Results]
subgraph "Django Application"
B --> J[Admin Interface]
B --> K[Django ORM]
K --> L[Database Storage]
end
subgraph "Execution Environment"
D --> M[Local Docker]
D --> N[Remote Docker]
D --> O[Cloud Run]
D --> P[AWS Fargate]
end
```
**Core Components:**
- **ContainerJob**: Django model representing a containerized task
- **ExecutorHost**: Defines where containers run (local, remote, cloud)
- **Executors**: Pluggable backends for different container platforms
- **Job Processor**: Background service that manages the job lifecycle
- **Admin Interface**: Web UI for job creation, monitoring, and management
## 🚀 Quick Start
### Prerequisites
- **Docker**: [Install Docker](https://docs.docker.com/get-docker/) and ensure it's running
- **Python 3.8+**: Compatible with Python 3.8, 3.9, 3.10, 3.11, 3.12
- **Django 4.2+**: Compatible with Django 4.2, 5.0, 5.1, 5.2
```bash
# Verify Docker is running
docker --version
docker ps
```
### Installation
```bash
# Install from PyPI
pip install django-container-manager
# Or with uv (recommended)
uv add django-container-manager
```
### 5-Minute Setup
1. **Add to Django settings:**
```python
# settings.py
INSTALLED_APPS = [
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
# ... your other apps
'container_manager', # Add this line
]
```
2. **Run migrations:**
```bash
python manage.py migrate
```
3. **Create superuser and start admin:**
```bash
python manage.py createsuperuser
python manage.py runserver # Visit http://localhost:8000/admin/
```
4. **Start the job processor (required for job execution):**
```bash
# In a separate terminal
python manage.py process_container_jobs
```
### Your First Container Job
Create and run your first containerized task in under 2 minutes:
1. **Set up Docker executor** (via Django shell):
```python
python manage.py shell
from container_manager.models import ExecutorHost
# Create local Docker executor
docker_host = ExecutorHost.objects.create(
name="local-docker",
executor_type="docker",
connection_string="unix:///var/run/docker.sock",
is_active=True
)
```
2. **Create a simple job:**
```python
from container_manager.models import ContainerJob
# Create a "Hello World" container job
job = ContainerJob.objects.create_job(
image="hello-world",
name="My First Container Job",
memory_limit=128, # 128MB
cpu_limit=0.5, # 0.5 CPU cores
timeout_seconds=300
)
print(f"Created job: {job.id}")
```
3. **Monitor execution** (the job processor will automatically pick it up):
```python
# Refresh the job to see updated status
job.refresh_from_db()
print(f"Status: {job.status}")
print(f"Output: {job.clean_output}")
```
**That's it!** Your first container job is running. Visit the Django admin to see real-time status updates and logs.
## 📖 Real-World Usage Examples
### Example 1: Data Processing Pipeline
Run a Python data processing script in an isolated container:
```python
from container_manager.models import ContainerJob
# Process CSV data with pandas
job = ContainerJob.objects.create_job(
image="python:3.11-slim",
command="pip install pandas && python -c \"import pandas as pd; print('Processing complete')\"",
name="Data Processing Job",
memory_limit=1024, # 1GB for data processing
cpu_limit=2.0, # 2 CPU cores
timeout_seconds=1800 # 30 minutes
)
```
### Example 2: Automated Testing
Run tests in a clean container environment:
```python
# Run pytest in isolated environment
test_job = ContainerJob.objects.create_job(
image="python:3.11",
command="/bin/bash -c 'pip install pytest && pytest --verbose'",
name="Test Suite Execution",
environment_vars={
"PYTHONPATH": "/app",
"TEST_ENV": "container",
"PYTEST_ARGS": "--tb=short"
},
memory_limit=512,
cpu_limit=1.0
)
```
### Example 3: Image Processing
Process images with ImageMagick in a containerized environment:
```python
# Image processing pipeline
image_job = ContainerJob.objects.create_job(
image="dpokidov/imagemagick:latest",
command="convert -version && echo 'ImageMagick ready for processing'",
name="Image Processing Pipeline",
memory_limit=2048, # 2GB for image processing
cpu_limit=1.5,
timeout_seconds=3600 # 1 hour
)
```
### Example 4: Database Operations
Run database migrations or data imports:
```python
# Database migration in container
db_job = ContainerJob.objects.create_job(
image="postgres:15",
command="psql --version && echo 'Database operations ready'",
name="Database Migration",
environment_vars={
"POSTGRES_HOST": "db.example.com",
"POSTGRES_DB": "myapp",
"POSTGRES_USER": "admin"
# Note: Use secrets management for passwords in production
},
memory_limit=256,
cpu_limit=0.5
)
```
### Environment Variables
Environment variables can be easily added to templates using a simple text format:
```python
env_template.environment_variables_text = """
# Database configuration
DATABASE_URL=postgresql://user:pass@host:5432/db
DB_POOL_SIZE=10
# API settings
API_KEY=your-secret-key
API_TIMEOUT=30
# Feature flags
DEBUG=false
ENABLE_CACHE=true
"""
```
**Format rules:**
- One variable per line: `KEY=value`
- Comments start with `#` and are ignored
- Values can contain spaces and `=` characters
- Empty lines are ignored
### Advanced Configuration
```python
# settings.py
CONTAINER_MANAGER = {
"AUTO_PULL_IMAGES": True,
"IMMEDIATE_CLEANUP": True,
"MAX_CONCURRENT_JOBS": 10,
"POLL_INTERVAL": 5,
"DEFAULT_MEMORY_LIMIT": 512,
"DEFAULT_CPU_LIMIT": 1.0,
"CLEANUP_HOURS": 24,
}
# Enable executor factory for multi-cloud support
USE_EXECUTOR_FACTORY = True
```
## 🌥️ Multi-Cloud Support
### Google Cloud Run
```python
# Configure Cloud Run executor
host = ExecutorHost.objects.create(
name="gcp-cloud-run",
executor_type="cloudrun",
weight=150,
executor_config={
"project": "my-gcp-project",
"region": "us-central1",
"cpu_limit": "2",
"memory_limit": "2Gi",
}
)
```
### AWS Fargate
```python
# Configure Fargate executor
host = ExecutorHost.objects.create(
name="aws-fargate",
executor_type="fargate",
weight=120,
executor_config={
"cluster": "my-ecs-cluster",
"subnets": ["subnet-12345", "subnet-67890"],
"security_groups": ["sg-abcdef"],
}
)
```
## 🔧 Job Processing & Monitoring
### Starting the Job Processor
The background job processor is essential for job execution:
```bash
# Production: Keep running continuously
python manage.py process_container_jobs
# Development: Run once and exit
python manage.py process_container_jobs --once
# Custom polling: Check for jobs every 10 seconds
python manage.py process_container_jobs --poll-interval=10
```
> **Critical**: Without the job processor running, no containers will be executed. This service manages the complete job lifecycle from container creation to cleanup.
### Real-time Monitoring
Monitor job execution through multiple interfaces:
#### Django Admin Interface
- **Live job status updates** with automatic refresh
- **Real-time log viewing** directly in the browser
- **Resource usage tracking** (memory, CPU, execution time)
- **Bulk operations** for managing multiple jobs
- **Executor host management** and health monitoring
#### Command Line Monitoring
```python
# Check job status programmatically
from container_manager.models import ContainerJob
# View recent jobs
recent_jobs = ContainerJob.objects.filter(
created_at__gte=timezone.now() - timedelta(hours=24)
)
for job in recent_jobs:
print(f"{job.name}: {job.status} ({job.duration})")
```
#### Production Monitoring
```python
# Health check endpoint example
def health_check():
from container_manager.models import ExecutorHost
unhealthy_hosts = []
for host in ExecutorHost.objects.filter(is_active=True):
# Check host health (implement based on your needs)
if not host.is_available():
unhealthy_hosts.append(host.name)
return {
'healthy': len(unhealthy_hosts) == 0,
'unhealthy_hosts': unhealthy_hosts
}
```
## 🔒 Production Security
Built-in security features for production deployment:
- **Resource limits**: Strict memory (max 2GB) and CPU (max 2 cores) constraints
- **Container isolation**: Non-privileged containers with security contexts
- **Network isolation**: Configurable network policies and container networking
- **TLS support**: Secure connections to remote Docker hosts and registries
- **Secret management**: Environment variable masking and secure credential handling
- **Access controls**: Role-based permissions through Django's auth system
### Security Best Practices
```python
# Secure job creation with resource limits
secure_job = ContainerJob.objects.create_job(
image="trusted-registry.company.com/app:latest",
command="python secure_task.py",
memory_limit=512, # Always set memory limits
cpu_limit=1.0, # Always set CPU limits
timeout_seconds=900, # 15-minute timeout
environment_vars={
"LOG_LEVEL": "INFO",
# Never put secrets in environment_vars in code
# Use Django secrets management instead
}
)
```
See the **[Docker Integration Guide](DOCKER.md)** for comprehensive security configuration.
## 🛠️ Development
### Setup Development Environment
```bash
# Clone and setup
git clone https://github.com/samtexas/django-container-manager.git
cd django-container-manager
# Install with uv (recommended)
uv sync --extra dev
# Or with pip
pip install -e ".[dev]"
```
### ⚡ Quick Development Commands
**For vibe coding with Claude Code:**
```bash
# Run tests (fast feedback)
make test
# Quality check (before commits)
make check
# Fix formatting/linting
make fix
# Pre-commit check (fix + test)
make ready
# Test coverage report
make coverage
```
### 🚀 Release Automation
**One-command releases:**
```bash
# Quick patch release (1.0.3 → 1.0.4)
make release-patch
# Minor release (1.0.3 → 1.1.0)
make release-minor
# Major release (1.0.3 → 2.0.0)
make release-major
```
Each release automatically:
- Fixes code formatting
- Runs full test suite
- Bumps version number
- Creates git commit and tag
- Pushes to GitHub
- Creates GitHub release
- Triggers PyPI publication via GitHub Actions
**Security:** Releases use GitHub environment protection for enhanced security and audit logging. See [CLAUDE.md](CLAUDE.md#-pypi-environment-protection) for full details.
### Manual Development Commands
```bash
# Run all tests
uv run python manage.py test
# Run with coverage
uv run coverage run --source=container_manager manage.py test
uv run coverage report
# Format and lint with ruff
uv run ruff format .
uv run ruff check .
# Build package
uv run python -m build
```
**See [VIBE_CODING.md](VIBE_CODING.md) for complete automation reference.**
## 📚 Documentation
### Core Documentation
- **[Docker Integration Guide](DOCKER.md)** - Comprehensive Docker setup, configuration, and best practices
- **[Installation Guide](INSTALL.md)** - Detailed installation instructions for all platforms
- **[API Reference](API.md)** - Complete API documentation and examples
- **[Troubleshooting Guide](TROUBLESHOOTING.md)** - Common issues and solutions
### Development Documentation
- **[Contributing Guide](CONTRIBUTING.md)** - Development setup, testing, and contribution guidelines
- **[Internal Documentation](CLAUDE.md)** - Technical implementation details and development notes
### External Resources
- **PyPI Package**: [django-container-manager](https://pypi.org/project/django-container-manager/)
- **Source Code**: [GitHub Repository](https://github.com/samtexas/django-container-manager)
- **Issue Tracker**: [GitHub Issues](https://github.com/samtexas/django-container-manager/issues)
## 🤖 LLM Agent Guidelines
### Behavioral Constraints
- **DO**: Test every code example in a clean environment before including
- **DO**: Verify all installation commands work on the target system
- **DO**: Keep examples simple and immediately runnable
- **DO**: Link to detailed documentation for complex topics
- **DO NOT**: Include misleading performance claims or unsupported features
- **DO NOT**: Add examples that require external services without clear setup
- **DO NOT**: Promise functionality that doesn't exist or is experimental
- **LIMITS**: README should be scannable in under 5 minutes
### Security Requirements
- **Never include**: Real credentials, API keys, or production URLs in examples
- **Always use**: Placeholder values like `your-registry.com` or `your-project-id`
- **Validate examples**: Ensure no security anti-patterns in code samples
- **Credential guidance**: Direct users to proper credential management documentation
### Safe Operation Patterns
- **Example validation process**:
1. Create clean test environment
2. Follow README instructions exactly as written
3. Verify each step produces expected output
4. Document any prerequisites or assumptions
- **Link validation**: Test all internal and external links for accuracy
- **Version consistency**: Ensure examples match current codebase capabilities
### Error Handling
- **If examples fail**: Update examples, don't ignore failures
- **If installation doesn't work**: Revise instructions, add troubleshooting notes
- **If technical accuracy questioned**: Cross-reference with CLAUDE.md and codebase
- **When unsure**: Ask for clarification rather than guessing
### Validation Requirements
- [ ] All code examples tested in clean environment
- [ ] Installation steps verified on target platforms
- [ ] No credentials or sensitive information in examples
- [ ] All links functional and point to correct resources
- [ ] Technical claims verified against actual codebase capabilities
- [ ] Examples use only documented, stable features
## 🤝 Contributing
Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on:
- Setting up development environment
- Code style and testing requirements
- Submitting pull requests
- Reporting bugs and feature requests
## 📜 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🔗 Links
- **PyPI**: [https://pypi.org/project/django-container-manager/](https://pypi.org/project/django-container-manager/)
- **Source Code**: [https://github.com/samtexas/django-container-manager](https://github.com/samtexas/django-container-manager)
- **Issue Tracker**: [https://github.com/samtexas/django-container-manager/issues](https://github.com/samtexas/django-container-manager/issues)
- **Documentation**: [https://django-container-manager.readthedocs.io/](https://django-container-manager.readthedocs.io/)
---
**For the Django community**
Raw data
{
"_id": null,
"home_page": null,
"name": "django-container-manager",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Sam Texas <dev@simplecto.com>",
"keywords": "aws-fargate, cloud-run, containers, django, docker, job-queue, orchestration, task-runner",
"author": null,
"author_email": "Sam Texas <dev@simplecto.com>",
"download_url": "https://files.pythonhosted.org/packages/79/f6/3a9274931d50fe008ca532645f124ae2e812cf8a792df6479533bc989518/django_container_manager-1.0.14.tar.gz",
"platform": null,
"description": "# Django Docker Container Manager\n\n[](https://badge.fury.io/py/django-container-manager)\n[](https://pypi.org/project/django-container-manager/)\n[](https://docs.djangoproject.com/)\n[](https://opensource.org/licenses/MIT)\n\n**The most comprehensive Docker container management system for Django.** Execute Django commands inside Docker containers with complete lifecycle tracking, resource monitoring, and multi-platform support. Eliminate the complexity of Celery/RQ while gaining powerful containerized job execution.\n\nTransform your Django application into a container orchestration platform with full observability, automatic resource management, and production-ready security controls.\n\n## Why Choose This Over Celery?\n\n- **\ud83c\udfaf Django-native design**: Built for Django from the ground up, not adapted from generic queuing\n- **\ud83d\udc33 Container-first architecture**: Docker containers as first-class execution environments with full isolation\n- **\ud83d\udcca Complete observability**: Track every aspect of job execution - logs, metrics, resource usage, timings\n- **\ud83d\udd27 Zero infrastructure dependencies**: No Redis, RabbitMQ, or external queue management required\n- **\ud83c\udf10 Multi-cloud ready**: Single codebase supports local Docker, remote hosts, Google Cloud Run, AWS Fargate\n- **\u26a1 Production hardened**: Built-in security controls, resource limits, error handling, and monitoring\n- **\ud83d\udd0d Real-time visibility**: Django admin integration with live job status and log viewing\n\n## \u2728 Key Features\n\n- \ud83d\udc33 **Multi-executor support**: Docker local/remote, Google Cloud Run, AWS Fargate, Mock executor\n- \ud83d\udcca **Complete lifecycle tracking**: Status monitoring, logs, metrics, and resource usage\n- \ud83c\udf9b\ufe0f **Django admin integration**: Beautiful web interface with real-time job monitoring\n- \ud83d\udd27 **Background job processor**: Automatic container job execution and management\n- \ud83d\udce6 **Environment management**: Template-based environment variables with job-level overrides\n- \ud83d\udd12 **Production security**: TLS support, resource limits, container isolation, and safe execution\n- \ud83d\udcc8 **Resource monitoring**: Memory and CPU usage tracking with configurable limits\n- \ud83c\udf10 **Cloud-native**: Built for containerized environments and cloud deployment\n\n## \ud83c\udfd7\ufe0f Architecture Overview\n\n```mermaid\ngraph TD\n A[Django Management Command] --> B[ContainerJob Model]\n B --> C[ExecutorHost Selection]\n C --> D[Docker/Cloud Executor]\n D --> E[Container Launch]\n E --> F[Real-time Monitoring]\n F --> G[Log Collection]\n G --> H[Resource Tracking]\n H --> I[Cleanup & Results]\n \n subgraph \"Django Application\"\n B --> J[Admin Interface]\n B --> K[Django ORM]\n K --> L[Database Storage]\n end\n \n subgraph \"Execution Environment\"\n D --> M[Local Docker]\n D --> N[Remote Docker]\n D --> O[Cloud Run]\n D --> P[AWS Fargate]\n end\n```\n\n**Core Components:**\n\n- **ContainerJob**: Django model representing a containerized task\n- **ExecutorHost**: Defines where containers run (local, remote, cloud)\n- **Executors**: Pluggable backends for different container platforms\n- **Job Processor**: Background service that manages the job lifecycle\n- **Admin Interface**: Web UI for job creation, monitoring, and management\n\n## \ud83d\ude80 Quick Start\n\n### Prerequisites\n\n- **Docker**: [Install Docker](https://docs.docker.com/get-docker/) and ensure it's running\n- **Python 3.8+**: Compatible with Python 3.8, 3.9, 3.10, 3.11, 3.12\n- **Django 4.2+**: Compatible with Django 4.2, 5.0, 5.1, 5.2\n\n```bash\n# Verify Docker is running\ndocker --version\ndocker ps\n```\n\n### Installation\n\n```bash\n# Install from PyPI\npip install django-container-manager\n\n# Or with uv (recommended)\nuv add django-container-manager\n```\n\n### 5-Minute Setup\n\n1. **Add to Django settings:**\n\n```python\n# settings.py\nINSTALLED_APPS = [\n 'django.contrib.admin',\n 'django.contrib.auth',\n 'django.contrib.contenttypes',\n 'django.contrib.sessions',\n # ... your other apps\n 'container_manager', # Add this line\n]\n```\n\n2. **Run migrations:**\n\n```bash\npython manage.py migrate\n```\n\n3. **Create superuser and start admin:**\n\n```bash\npython manage.py createsuperuser\npython manage.py runserver # Visit http://localhost:8000/admin/\n```\n\n4. **Start the job processor (required for job execution):**\n\n```bash\n# In a separate terminal\npython manage.py process_container_jobs\n```\n\n### Your First Container Job\n\nCreate and run your first containerized task in under 2 minutes:\n\n1. **Set up Docker executor** (via Django shell):\n\n```python\npython manage.py shell\n\nfrom container_manager.models import ExecutorHost\n\n# Create local Docker executor\ndocker_host = ExecutorHost.objects.create(\n name=\"local-docker\",\n executor_type=\"docker\",\n connection_string=\"unix:///var/run/docker.sock\",\n is_active=True\n)\n```\n\n2. **Create a simple job:**\n\n```python\nfrom container_manager.models import ContainerJob\n\n# Create a \"Hello World\" container job\njob = ContainerJob.objects.create_job(\n image=\"hello-world\",\n name=\"My First Container Job\",\n memory_limit=128, # 128MB\n cpu_limit=0.5, # 0.5 CPU cores\n timeout_seconds=300\n)\n\nprint(f\"Created job: {job.id}\")\n```\n\n3. **Monitor execution** (the job processor will automatically pick it up):\n\n```python\n# Refresh the job to see updated status\njob.refresh_from_db()\nprint(f\"Status: {job.status}\")\nprint(f\"Output: {job.clean_output}\")\n```\n\n**That's it!** Your first container job is running. Visit the Django admin to see real-time status updates and logs.\n\n## \ud83d\udcd6 Real-World Usage Examples\n\n### Example 1: Data Processing Pipeline\n\nRun a Python data processing script in an isolated container:\n\n```python\nfrom container_manager.models import ContainerJob\n\n# Process CSV data with pandas\njob = ContainerJob.objects.create_job(\n image=\"python:3.11-slim\",\n command=\"pip install pandas && python -c \\\"import pandas as pd; print('Processing complete')\\\"\",\n name=\"Data Processing Job\",\n memory_limit=1024, # 1GB for data processing\n cpu_limit=2.0, # 2 CPU cores\n timeout_seconds=1800 # 30 minutes\n)\n```\n\n### Example 2: Automated Testing\n\nRun tests in a clean container environment:\n\n```python\n# Run pytest in isolated environment\ntest_job = ContainerJob.objects.create_job(\n image=\"python:3.11\",\n command=\"/bin/bash -c 'pip install pytest && pytest --verbose'\",\n name=\"Test Suite Execution\",\n environment_vars={\n \"PYTHONPATH\": \"/app\",\n \"TEST_ENV\": \"container\",\n \"PYTEST_ARGS\": \"--tb=short\"\n },\n memory_limit=512,\n cpu_limit=1.0\n)\n```\n\n### Example 3: Image Processing\n\nProcess images with ImageMagick in a containerized environment:\n\n```python\n# Image processing pipeline\nimage_job = ContainerJob.objects.create_job(\n image=\"dpokidov/imagemagick:latest\",\n command=\"convert -version && echo 'ImageMagick ready for processing'\",\n name=\"Image Processing Pipeline\",\n memory_limit=2048, # 2GB for image processing\n cpu_limit=1.5,\n timeout_seconds=3600 # 1 hour\n)\n```\n\n### Example 4: Database Operations\n\nRun database migrations or data imports:\n\n```python\n# Database migration in container\ndb_job = ContainerJob.objects.create_job(\n image=\"postgres:15\",\n command=\"psql --version && echo 'Database operations ready'\",\n name=\"Database Migration\",\n environment_vars={\n \"POSTGRES_HOST\": \"db.example.com\",\n \"POSTGRES_DB\": \"myapp\",\n \"POSTGRES_USER\": \"admin\"\n # Note: Use secrets management for passwords in production\n },\n memory_limit=256,\n cpu_limit=0.5\n)\n```\n\n### Environment Variables\n\nEnvironment variables can be easily added to templates using a simple text format:\n\n```python\nenv_template.environment_variables_text = \"\"\"\n# Database configuration\nDATABASE_URL=postgresql://user:pass@host:5432/db\nDB_POOL_SIZE=10\n\n# API settings \nAPI_KEY=your-secret-key\nAPI_TIMEOUT=30\n\n# Feature flags\nDEBUG=false\nENABLE_CACHE=true\n\"\"\"\n```\n\n**Format rules:**\n- One variable per line: `KEY=value`\n- Comments start with `#` and are ignored\n- Values can contain spaces and `=` characters\n- Empty lines are ignored\n\n### Advanced Configuration\n\n```python\n# settings.py\nCONTAINER_MANAGER = {\n \"AUTO_PULL_IMAGES\": True,\n \"IMMEDIATE_CLEANUP\": True,\n \"MAX_CONCURRENT_JOBS\": 10,\n \"POLL_INTERVAL\": 5,\n \"DEFAULT_MEMORY_LIMIT\": 512,\n \"DEFAULT_CPU_LIMIT\": 1.0,\n \"CLEANUP_HOURS\": 24,\n}\n\n# Enable executor factory for multi-cloud support\nUSE_EXECUTOR_FACTORY = True\n```\n\n## \ud83c\udf25\ufe0f Multi-Cloud Support\n\n### Google Cloud Run\n\n```python\n# Configure Cloud Run executor\nhost = ExecutorHost.objects.create(\n name=\"gcp-cloud-run\",\n executor_type=\"cloudrun\",\n weight=150,\n executor_config={\n \"project\": \"my-gcp-project\",\n \"region\": \"us-central1\",\n \"cpu_limit\": \"2\",\n \"memory_limit\": \"2Gi\",\n }\n)\n```\n\n### AWS Fargate\n\n```python\n# Configure Fargate executor\nhost = ExecutorHost.objects.create(\n name=\"aws-fargate\",\n executor_type=\"fargate\",\n weight=120,\n executor_config={\n \"cluster\": \"my-ecs-cluster\",\n \"subnets\": [\"subnet-12345\", \"subnet-67890\"],\n \"security_groups\": [\"sg-abcdef\"],\n }\n)\n```\n\n## \ud83d\udd27 Job Processing & Monitoring\n\n### Starting the Job Processor\n\nThe background job processor is essential for job execution:\n\n```bash\n# Production: Keep running continuously\npython manage.py process_container_jobs\n\n# Development: Run once and exit\npython manage.py process_container_jobs --once\n\n# Custom polling: Check for jobs every 10 seconds\npython manage.py process_container_jobs --poll-interval=10\n```\n\n> **Critical**: Without the job processor running, no containers will be executed. This service manages the complete job lifecycle from container creation to cleanup.\n\n### Real-time Monitoring\n\nMonitor job execution through multiple interfaces:\n\n#### Django Admin Interface\n- **Live job status updates** with automatic refresh\n- **Real-time log viewing** directly in the browser\n- **Resource usage tracking** (memory, CPU, execution time)\n- **Bulk operations** for managing multiple jobs\n- **Executor host management** and health monitoring\n\n#### Command Line Monitoring\n```python\n# Check job status programmatically\nfrom container_manager.models import ContainerJob\n\n# View recent jobs\nrecent_jobs = ContainerJob.objects.filter(\n created_at__gte=timezone.now() - timedelta(hours=24)\n)\n\nfor job in recent_jobs:\n print(f\"{job.name}: {job.status} ({job.duration})\")\n```\n\n#### Production Monitoring\n```python\n# Health check endpoint example\ndef health_check():\n from container_manager.models import ExecutorHost\n \n unhealthy_hosts = []\n for host in ExecutorHost.objects.filter(is_active=True):\n # Check host health (implement based on your needs)\n if not host.is_available():\n unhealthy_hosts.append(host.name)\n \n return {\n 'healthy': len(unhealthy_hosts) == 0,\n 'unhealthy_hosts': unhealthy_hosts\n }\n```\n\n## \ud83d\udd12 Production Security\n\nBuilt-in security features for production deployment:\n\n- **Resource limits**: Strict memory (max 2GB) and CPU (max 2 cores) constraints\n- **Container isolation**: Non-privileged containers with security contexts\n- **Network isolation**: Configurable network policies and container networking\n- **TLS support**: Secure connections to remote Docker hosts and registries\n- **Secret management**: Environment variable masking and secure credential handling\n- **Access controls**: Role-based permissions through Django's auth system\n\n### Security Best Practices\n\n```python\n# Secure job creation with resource limits\nsecure_job = ContainerJob.objects.create_job(\n image=\"trusted-registry.company.com/app:latest\",\n command=\"python secure_task.py\",\n memory_limit=512, # Always set memory limits\n cpu_limit=1.0, # Always set CPU limits\n timeout_seconds=900, # 15-minute timeout\n environment_vars={\n \"LOG_LEVEL\": \"INFO\",\n # Never put secrets in environment_vars in code\n # Use Django secrets management instead\n }\n)\n```\n\nSee the **[Docker Integration Guide](DOCKER.md)** for comprehensive security configuration.\n\n## \ud83d\udee0\ufe0f Development\n\n### Setup Development Environment\n\n```bash\n# Clone and setup\ngit clone https://github.com/samtexas/django-container-manager.git\ncd django-container-manager\n\n# Install with uv (recommended)\nuv sync --extra dev\n\n# Or with pip\npip install -e \".[dev]\"\n```\n\n### \u26a1 Quick Development Commands\n\n**For vibe coding with Claude Code:**\n\n```bash\n# Run tests (fast feedback)\nmake test\n\n# Quality check (before commits)\nmake check\n\n# Fix formatting/linting\nmake fix\n\n# Pre-commit check (fix + test)\nmake ready\n\n# Test coverage report\nmake coverage\n```\n\n### \ud83d\ude80 Release Automation\n\n**One-command releases:**\n\n```bash\n# Quick patch release (1.0.3 \u2192 1.0.4)\nmake release-patch\n\n# Minor release (1.0.3 \u2192 1.1.0) \nmake release-minor\n\n# Major release (1.0.3 \u2192 2.0.0)\nmake release-major\n```\n\nEach release automatically:\n- Fixes code formatting\n- Runs full test suite \n- Bumps version number\n- Creates git commit and tag\n- Pushes to GitHub\n- Creates GitHub release\n- Triggers PyPI publication via GitHub Actions\n\n**Security:** Releases use GitHub environment protection for enhanced security and audit logging. See [CLAUDE.md](CLAUDE.md#-pypi-environment-protection) for full details.\n\n### Manual Development Commands\n\n```bash\n# Run all tests\nuv run python manage.py test\n\n# Run with coverage\nuv run coverage run --source=container_manager manage.py test\nuv run coverage report\n\n# Format and lint with ruff\nuv run ruff format .\nuv run ruff check .\n\n# Build package\nuv run python -m build\n```\n\n**See [VIBE_CODING.md](VIBE_CODING.md) for complete automation reference.**\n\n## \ud83d\udcda Documentation\n\n### Core Documentation\n\n- **[Docker Integration Guide](DOCKER.md)** - Comprehensive Docker setup, configuration, and best practices\n- **[Installation Guide](INSTALL.md)** - Detailed installation instructions for all platforms\n- **[API Reference](API.md)** - Complete API documentation and examples\n- **[Troubleshooting Guide](TROUBLESHOOTING.md)** - Common issues and solutions\n\n### Development Documentation\n\n- **[Contributing Guide](CONTRIBUTING.md)** - Development setup, testing, and contribution guidelines\n- **[Internal Documentation](CLAUDE.md)** - Technical implementation details and development notes\n\n### External Resources\n\n- **PyPI Package**: [django-container-manager](https://pypi.org/project/django-container-manager/)\n- **Source Code**: [GitHub Repository](https://github.com/samtexas/django-container-manager)\n- **Issue Tracker**: [GitHub Issues](https://github.com/samtexas/django-container-manager/issues)\n\n## \ud83e\udd16 LLM Agent Guidelines\n\n### Behavioral Constraints\n\n- **DO**: Test every code example in a clean environment before including\n- **DO**: Verify all installation commands work on the target system\n- **DO**: Keep examples simple and immediately runnable\n- **DO**: Link to detailed documentation for complex topics\n- **DO NOT**: Include misleading performance claims or unsupported features\n- **DO NOT**: Add examples that require external services without clear setup\n- **DO NOT**: Promise functionality that doesn't exist or is experimental\n- **LIMITS**: README should be scannable in under 5 minutes\n\n### Security Requirements\n\n- **Never include**: Real credentials, API keys, or production URLs in examples\n- **Always use**: Placeholder values like `your-registry.com` or `your-project-id`\n- **Validate examples**: Ensure no security anti-patterns in code samples\n- **Credential guidance**: Direct users to proper credential management documentation\n\n### Safe Operation Patterns\n\n- **Example validation process**:\n 1. Create clean test environment\n 2. Follow README instructions exactly as written\n 3. Verify each step produces expected output\n 4. Document any prerequisites or assumptions\n- **Link validation**: Test all internal and external links for accuracy\n- **Version consistency**: Ensure examples match current codebase capabilities\n\n### Error Handling\n\n- **If examples fail**: Update examples, don't ignore failures\n- **If installation doesn't work**: Revise instructions, add troubleshooting notes\n- **If technical accuracy questioned**: Cross-reference with CLAUDE.md and codebase\n- **When unsure**: Ask for clarification rather than guessing\n\n### Validation Requirements\n\n- [ ] All code examples tested in clean environment\n- [ ] Installation steps verified on target platforms\n- [ ] No credentials or sensitive information in examples\n- [ ] All links functional and point to correct resources\n- [ ] Technical claims verified against actual codebase capabilities\n- [ ] Examples use only documented, stable features\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on:\n\n- Setting up development environment\n- Code style and testing requirements \n- Submitting pull requests\n- Reporting bugs and feature requests\n\n## \ud83d\udcdc License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\udd17 Links\n\n- **PyPI**: [https://pypi.org/project/django-container-manager/](https://pypi.org/project/django-container-manager/)\n- **Source Code**: [https://github.com/samtexas/django-container-manager](https://github.com/samtexas/django-container-manager)\n- **Issue Tracker**: [https://github.com/samtexas/django-container-manager/issues](https://github.com/samtexas/django-container-manager/issues)\n- **Documentation**: [https://django-container-manager.readthedocs.io/](https://django-container-manager.readthedocs.io/)\n\n---\n\n**For the Django community**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Django app for container orchestration with multi-executor support (Docker, Google Cloud Run, AWS Fargate)",
"version": "1.0.14",
"project_urls": {
"Changelog": "https://github.com/heysamtexas/django-container-manager/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/heysamtexas/django-container-manager/tree/main/docs",
"Homepage": "https://github.com/heysamtexas/django-container-manager",
"Issues": "https://github.com/heysamtexas/django-container-manager/issues",
"Repository": "https://github.com/heysamtexas/django-container-manager.git"
},
"split_keywords": [
"aws-fargate",
" cloud-run",
" containers",
" django",
" docker",
" job-queue",
" orchestration",
" task-runner"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e1a1de02134d6289f427b8e37d0a9c74e756d7c5350917d84fa91175cabcec53",
"md5": "98bca2cc0fb26506fe208433d106c199",
"sha256": "5278ab5f0da3747b8d585d13ecd8f47cc784d8c668d66028ec8ae0d13dfc6886"
},
"downloads": -1,
"filename": "django_container_manager-1.0.14-py3-none-any.whl",
"has_sig": false,
"md5_digest": "98bca2cc0fb26506fe208433d106c199",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 105503,
"upload_time": "2025-08-07T20:22:02",
"upload_time_iso_8601": "2025-08-07T20:22:02.301855Z",
"url": "https://files.pythonhosted.org/packages/e1/a1/de02134d6289f427b8e37d0a9c74e756d7c5350917d84fa91175cabcec53/django_container_manager-1.0.14-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "79f63a9274931d50fe008ca532645f124ae2e812cf8a792df6479533bc989518",
"md5": "8b33cc8dfd790e79ce94e7e0aa43b14b",
"sha256": "8eeceb2d77f9041080ca0a3c591a75c29163f5627aeb5c5e787e19b923e7e265"
},
"downloads": -1,
"filename": "django_container_manager-1.0.14.tar.gz",
"has_sig": false,
"md5_digest": "8b33cc8dfd790e79ce94e7e0aa43b14b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 88738,
"upload_time": "2025-08-07T20:22:03",
"upload_time_iso_8601": "2025-08-07T20:22:03.511829Z",
"url": "https://files.pythonhosted.org/packages/79/f6/3a9274931d50fe008ca532645f124ae2e812cf8a792df6479533bc989518/django_container_manager-1.0.14.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-07 20:22:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "heysamtexas",
"github_project": "django-container-manager",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "django-container-manager"
}
JSON
