# Flamenco Documentation

This directory contains comprehensive documentation for Flamenco development, with a focus on the optimized Docker development environment.

## Docker Development Environment

The Docker environment represents a **168x performance improvement** over the original setup, transforming 60+ minute failing builds into reliable 26-minute successful builds.

### Core Documentation

| Document | Purpose | Audience |
|----------|---------|-----------|
| [DOCKER_BUILD_OPTIMIZATIONS.md](DOCKER_BUILD_OPTIMIZATIONS.md) | Technical details of the optimization process | Developers, DevOps |
| [DOCKER_QUICK_REFERENCE.md](DOCKER_QUICK_REFERENCE.md) | Quick command reference and troubleshooting | Daily development |
| [MODERN_COMPOSE_SETUP.md](MODERN_COMPOSE_SETUP.md) | Modern Docker Compose best practices | Infrastructure setup |
| [Mage-Build-System-Integration.md](Mage-Build-System-Integration.md) | Deep dive into Mage build system architecture | Build system maintainers |

### Quick Start

For immediate Docker development environment setup:

```bash
# Clone and setup
git clone https://projects.blender.org/studio/flamenco.git
cd flamenco
make -f Makefile.docker dev-setup
make -f Makefile.docker dev-start

# Access Flamenco Manager
# Local: http://localhost:9000
# Reverse proxy: https://manager.flamenco.l.supported.systems
```

### Key Achievements

- **168x faster Go module downloads** (21.4s vs 60+ min failure)
- **100% reliable builds** (vs previous 100% failure rate)
- **Complete multi-stage optimization** with intelligent layer caching
- **Production-ready containerization** for all Flamenco components
- **Comprehensive Playwright testing** integration
- **Caddy reverse proxy** with automatic HTTPS

### Architecture Overview

The optimized Docker environment uses:
- **Multi-stage builds** for intelligent layer caching
- **Go module proxy** for reliable dependency downloads  
- **uv** for fast Python package management
- **Alpine Linux** with proper platform compatibility
- **Mage build system** integration
- **caddy-docker-proxy** for reverse proxy automation

### Documentation Structure

This documentation follows engineering best practices:
- **Technical specifications** for implementation details
- **Quick references** for daily development workflows  
- **Troubleshooting guides** for common issues
- **Architecture explanations** for understanding design decisions

## Related Documentation

- **Web project documentation**: `web/project-website/content/development/docker-development/`
- **Configuration design**: `CONFIG_DESIGN.md` (root directory)
- **Project README**: `README.md` (root directory)
- **Changelog**: `CHANGELOG.md` (root directory)

---

*This documentation represents the collective knowledge from transforming Flamenco's Docker environment from a broken state to production-ready reliability.*