mediacms/DOCKER_RESTRUCTURE_SUMMARY.md

MediaCMS Docker Restructure Summary

Overview

This document summarizes the complete Docker architecture restructure for MediaCMS 7.3, eliminating supervisord and implementing modern Docker best practices.

What Was Created

New Files

Dockerfiles

• Dockerfile - Multi-stage Dockerfile with targets (replaced old Dockerfile):

  • build-image - FFmpeg and Bento4 builder
  • base - Python/Django base image
  • web - uWSGI web server
  • worker - Celery worker (standard)
  • worker-full - Celery worker with extra codecs

• Dockerfile.nginx - Vanilla nginx with MediaCMS configs baked in

Docker Compose Files

• docker-compose.yaml - Production deployment (no file mounts) - REPLACED
• docker-compose-cert.yaml - Production with HTTPS (Let's Encrypt) - REPLACED
• docker-compose-dev.yaml - Development with file mounts and hot reload - REPLACED

Scripts

• scripts/entrypoint-web.sh - Web container entrypoint
• scripts/entrypoint-worker.sh - Worker container entrypoint
• scripts/run-migrations.sh - Migration runner script

Configuration

• config/nginx/nginx.conf - Main nginx config (from deploy/docker/)
• config/nginx/site.conf - Virtual host config (from deploy/docker/nginx_http_only.conf)
• config/nginx/uwsgi_params - uWSGI params (from deploy/docker/)
• config/nginx-proxy/client_max_body_size.conf - For nginx-proxy (from deploy/docker/reverse_proxy/)
• config/uwsgi/uwsgi.ini - uWSGI configuration (from deploy/docker/)
• config/imagemagick/policy.xml - ImageMagick policy (from deploy/docker/)

Documentation

• docs/DOCKER_V7.3_MIGRATION.md - Complete migration guide
• Updated docs/admins_docs.md - Sections 4 and 5

Architecture Changes

Before (Old Architecture)

Single Container (supervisord managing multiple processes)
├── nginx (port 80)
├── uwsgi (port 9000)
├── celery beat
├── celery short workers
└── celery long workers

Controlled by ENABLE_* environment variables

After (New Architecture)

Dedicated Containers (one process per container)
├── nginx (port 80) → web:9000
├── web (uwsgi on port 9000)
├── celery_beat
├── celery_short (scalable)
├── celery_long (scalable, optional :full image)
├── migrations (runs on startup)
├── db (PostgreSQL)
└── redis

Volumes:
- static_files (nginx ← web)
- media_files (nginx ← web, workers)
- postgres_data

Key Improvements

1. Removed Components

• ❌ supervisord and all configs in deploy/docker/supervisord/
• ❌ deploy/docker/start.sh
• ❌ deploy/docker/entrypoint.sh
• ❌ All ENABLE_* environment variables

2. Separated Services

• Nginx runs in its own container
• Django/uWSGI in dedicated web container
• Celery workers split by task duration
• Migrations run automatically on every startup

3. Production Ready

• No file mounts in production (immutable images)
• Named volumes for data persistence
• Proper health checks
• Individual service scaling

4. Development Friendly

• Separate -dev compose file with file mounts
• Django debug mode
• Frontend hot reload
• Live code editing

Images to Build

For production, these images need to be built and pushed to Docker Hub:

# Build base and web image
docker build --target web -t mediacms/mediacms:7.3 .

# Build worker image
docker build --target worker -t mediacms/mediacms-worker:7.3 .

# Build worker-full image
docker build --target worker-full -t mediacms/mediacms-worker:7.3-full .

# Build nginx image
docker build -f Dockerfile.nginx -t mediacms/mediacms-nginx:7.3 .

Deployment Options

1. Development

docker compose -f docker-compose-dev.yaml up

• File mounts for live editing
• Django runserver
• Frontend dev server

2. Production (HTTP)

# Rename .new files first
mv docker-compose.yaml.new docker-compose.yaml

docker compose up -d

• Immutable images
• No file mounts
• Port 80

3. Production (HTTPS)

# Rename .new files first
mv docker-compose-cert.yaml.new docker-compose-cert.yaml

# Edit and set your domain/email
docker compose -f docker-compose-cert.yaml up -d

• Automatic Let's Encrypt certificates
• Auto-renewal

Migration Path for Existing Systems

For Production Systems Currently Running

1. Backup first

   docker exec <db_container> pg_dump -U mediacms mediacms > backup.sql
   

2. Update compose file

   • Replace old docker-compose files with new ones
   • Update domain settings in cert file if using HTTPS

3. Pull new images

   docker pull mediacms/mediacms:7.3
   docker pull mediacms/mediacms-worker:7.3
   docker pull mediacms/mediacms-nginx:7.3
   

4. Restart

   docker compose down
   docker compose up -d
   

Breaking Changes

1. No more ENABLE_ variables* - Remove from any custom configs
2. deploy/docker/local_settings.py - Now use environment variables or custom image
3. Service names changed:
   • celery_worker → celery_short + celery_long
   • Added nginx service

Testing Checklist

Before deploying to production, test:

• Migrations run successfully
• Static files served correctly
• Media files served correctly
• Django admin accessible
• Video upload works
• Video transcoding works (celery_long)
• Thumbnail generation works (celery_short)
• HTTPS redirects work (if using cert file)
• Database persistence across restarts
• Media files persistence across restarts

Configuration Examples

Use Full Worker Image

celery_long:
  image: mediacms/mediacms-worker:7.3-full

Set Custom Domain

environment:
  FRONTEND_HOST: 'https://videos.example.com'
  PORTAL_NAME: 'My Video Portal'

Scale Workers

docker compose up -d --scale celery_short=3 --scale celery_long=2

Files to Review Before Finalizing

1. Dockerfile - Review Python/Django/uWSGI configuration
2. config/nginx/site.conf - Review nginx paths and proxy settings
3. docker-compose.yaml - Review volume mounts and service dependencies
4. scripts/run-migrations.sh - Review migration logic

Next Steps

To finalize this restructure:

1. Test locally with docker-compose-dev.yaml
2. Build images and push to Docker Hub
3. Update CI/CD to build new images
4. Test in staging environment
5. Create release notes referencing migration guide

Backup

Old Docker files have been backed up to .docker-backup/ directory.

Rollback Plan

If issues arise, rollback by:

1. Reverting to old docker-compose files
2. Using old image tags
3. Restoring database from backup if needed

Old files are preserved in .docker-backup/ directory.

Support

• Migration Guide: docs/DOCKER_V7.3_MIGRATION.md
• Admin Docs: docs/admins_docs.md (updated sections 4, 5)
• Issues: https://github.com/mediacms-io/mediacms/issues