mediacms/UPGRADE_TO_7.3.md

Upgrade Guide: MediaCMS 7.x to 7.3

IMPORTANT: This is a major architectural change. Read this entire guide before upgrading.

---

🎯 Fresh Install (Not Upgrading)?

If you're starting fresh with 7.3, you don't need this guide!

All you need:

# 1. Download docker-compose.yaml
wget https://raw.githubusercontent.com/mediacms-io/mediacms/v7.3/docker-compose.yaml

# 2. Start (creates everything automatically)
docker compose up -d

# 3. Done! Visit http://localhost

Optional: Add customizations

# Create custom/ directory
mkdir -p custom/static/{images,css}

# Download example settings
wget -O custom/local_settings.py.example \
  https://raw.githubusercontent.com/mediacms-io/mediacms/v7.3/custom/local_settings.py.example

# Edit and use
cp custom/local_settings.py.example custom/local_settings.py
nano custom/local_settings.py

# Restart
docker compose restart web

See custom/README.md for customization options.

---

⚠️ Upgrading from 7.x? Continue reading...

What Changed in 7.3

Architecture Changes

• Before: Monolithic container (supervisor + nginx + uwsgi + celery in one)
• After: Microservices (separate nginx, web, celery_beat, celery_short, celery_long containers)

Volume Strategy Changes

• Before: Entire project directory mounted (./:/home/mediacms.io/mediacms/)
• After: Named volumes for data, bind mount only for custom/ directory

Specific Changes

Component	Before (7.x)	After (7.3)
media_files	Bind mount ./media_files	Named volume media_files
static files	Bind mount ./static	Named volume static_files (built into image)
logs	Bind mount ./logs	Named volume logs
postgres_data	../postgres_data	Named volume postgres_data
Custom config	cms/local_settings.py in mounted dir	custom/local_settings.py bind mount
Static collection	Runtime (via entrypoint)	Build time (in Dockerfile)
User	Root with gosu switch	www-data from start

What You Need for 7.3

Minimal deployment - NO CODE REQUIRED:

1. ✅ docker-compose.yaml (download from release or docs)
2. ✅ Docker images (pulled from Docker Hub)
3. ⚠️ custom/ directory (only if you have customizations)

That's it! No git repo, no code checkout needed.

Pre-Upgrade Checklist

1. Backup Everything

# Stop services
docker compose down

# Backup media files
tar -czf backup_media_$(date +%Y%m%d).tar.gz media_files/

# Backup database
docker compose up -d db
docker compose exec db pg_dump -U mediacms mediacms > backup_db_$(date +%Y%m%d).sql
docker compose down

# Backup logs (optional)
tar -czf backup_logs_$(date +%Y%m%d).tar.gz logs/

# Backup local settings if you had them
cp cms/local_settings.py backup_local_settings.py 2>/dev/null || echo "No local_settings.py found"

# Backup current docker-compose.yaml
cp docker-compose.yaml docker-compose.yaml.old

2. Document Current Setup

# Save current docker-compose version
git branch backup-pre-7.3-upgrade

# Document current state
docker compose ps > pre_upgrade_state.txt
docker compose config > pre_upgrade_config.yaml
df -h > pre_upgrade_disk_usage.txt

3. Check Disk Space

You'll need enough space for:

• Existing data (media_files, postgres_data)
• New Docker volumes (will copy data here)
• Database dump

du -sh media_files/ postgres_data/ logs/
df -h .

Upgrade Methods

Method 1: Clean Migration (Recommended)

This method migrates your data to the new volume structure.

Step 1: Get New docker-compose.yaml

Option A: Download from release

# Download docker-compose.yaml for 7.3
wget https://raw.githubusercontent.com/mediacms-io/mediacms/v7.3/docker-compose.yaml

# Or using curl
curl -O https://raw.githubusercontent.com/mediacms-io/mediacms/v7.3/docker-compose.yaml

# Optional: Download HTTPS version
wget https://raw.githubusercontent.com/mediacms-io/mediacms/v7.3/docker-compose-cert.yaml

Option B: Copy from docs/release notes

• Copy the docker-compose.yaml content from release notes
• Save as docker-compose.yaml in your deployment directory

Step 2: Prepare Custom Configuration (if needed)

# Create custom directory structure (only if you need customizations)
mkdir -p custom/static/{images,css}
touch custom/static/{images,css}/.gitkeep

# If you had local_settings.py, create it in custom/
if [ -f backup_local_settings.py ]; then
    # Copy your old settings
    cp backup_local_settings.py custom/local_settings.py
    echo "✓ Migrated local_settings.py"
else
    # Download example template (optional)
    wget -O custom/local_settings.py.example \
      https://raw.githubusercontent.com/mediacms-io/mediacms/v7.3/custom/local_settings.py.example
    echo "Downloaded example template to custom/local_settings.py.example"
fi

# Copy any custom logos/css you had
# (adjust paths as needed for your old setup)
# cp my-old-logo.png custom/static/images/logo_dark.png
# cp my-custom.css custom/static/css/custom.css

Step 3: Start New Stack (Without Data)

# Pull new images
docker compose pull

# Start database first
docker compose up -d db redis

# Wait for DB to be ready
sleep 10

Step 4: Restore Database

# Copy backup into container
docker compose cp backup_db_*.sql db:/tmp/backup.sql

# Restore database
docker compose exec db psql -U mediacms mediacms < /tmp/backup.sql

# Or from host:
cat backup_db_*.sql | docker compose exec -T db psql -U mediacms mediacms

Step 5: Restore Media Files

# Start all services (will create volumes)
docker compose up -d

# Find the volume name
docker volume ls | grep media_files

# Copy media files to volume
# Method A: Using a temporary container
docker run --rm \
  -v $(pwd)/media_files:/source:ro \
  -v mediacms_media_files:/dest \
  alpine sh -c "cp -av /source/* /dest/"

# Method B: Using existing container
docker compose exec web sh -c "exit"  # Ensure web is running
# Then copy from host
tar -C media_files -cf - . | docker compose exec -T web tar -C /home/mediacms.io/mediacms/media_files -xf -

Step 6: Verify and Test

# Check logs
docker compose logs -f web

# Verify media files are accessible
docker compose exec web ls -la /home/mediacms.io/mediacms/media_files/

# Check database connection
docker compose exec web python manage.py dbshell

# Access the site
curl http://localhost

# Check admin panel
# Visit http://localhost/admin

Method 2: In-Place Migration with Symlinks (Advanced)

Warning: This is more complex but avoids data copying.

Step 1: Keep Old Data Locations

# Modify docker-compose.yaml to mount old locations temporarily
# Add to appropriate services:
volumes:
  - ./media_files:/home/mediacms.io/mediacms/media_files
  - ./logs:/home/mediacms.io/mediacms/logs
  # Instead of named volumes

Step 2: Gradually Migrate

After confirming everything works:

1. Copy data to named volumes
2. Remove bind mounts
3. Switch to named volumes

Method 3: Fresh Install (If Possible)

If your MediaCMS instance is new or test:

# Backup what you need
# ...

# Clean slate
docker compose down -v
rm -rf media_files/ logs/ static/

# Fresh start
docker compose up -d

Post-Upgrade Steps

1. Verify Everything Works

# Check all services are running
docker compose ps

# Should see: migrations (exited 0), web, nginx, celery_beat, celery_short, celery_long, db, redis

# Check logs for errors
docker compose logs web
docker compose logs nginx

# Test upload functionality
# Test video encoding (check celery_long logs)
# Test frontend

2. Verify Media Files

# Check media files are accessible
docker compose exec web ls -lh /home/mediacms.io/mediacms/media_files/

# Check file counts match
# Old: ls media_files/ | wc -l
# New: docker compose exec web sh -c "ls /home/mediacms.io/mediacms/media_files/ | wc -l"

3. Verify Database

# Check users
docker compose exec db psql -U mediacms mediacms -c "SELECT count(*) FROM users_user;"

# Check videos
docker compose exec db psql -U mediacms mediacms -c "SELECT count(*) FROM files_media;"

4. Update Backups

# Update your backup scripts for new volume locations
# Use: make backup-db (if Makefile target exists)
# Or: docker compose exec db pg_dump ...

Rollback Procedure

If something goes wrong:

Quick Rollback

# Stop new version
docker compose down

# Restore old docker-compose file
mv docker-compose.yaml.old docker-compose.yaml

# Pull old images (if you had old image tags documented)
docker compose pull

# Start old version
docker compose up -d

Full Rollback with Data Restore

# Stop everything
docker compose down -v

# Restore old docker-compose
mv docker-compose.yaml.old docker-compose.yaml

# Restore backups
tar -xzf backup_media_*.tar.gz -C ./media_files
cat backup_db_*.sql | docker compose exec -T db psql -U mediacms mediacms

# Start old version
docker compose up -d

Common Issues & Solutions

Issue: "Volume not found"

Solution: Volumes are created with project name prefix. Check:

docker volume ls
# Look for: mediacms_media_files, mediacms_static_files, etc.

Issue: "Permission denied" on media files

Solution: Files must be owned by www-data (UID 33)

docker compose exec web chown -R www-data:www-data /home/mediacms.io/mediacms/media_files

Issue: Static files not loading

Solution: Rebuild image (collectstatic runs at build time)

docker compose down
docker compose build --no-cache web
docker compose up -d

Issue: Database connection refused

Solution: Check database is healthy

docker compose logs db
docker compose exec db pg_isready -U mediacms

Issue: Custom settings not loading

Solution: Check custom/local_settings.py exists and syntax

docker compose exec web cat /home/mediacms.io/mediacms/custom/local_settings.py
docker compose exec web python -m py_compile /home/mediacms.io/mediacms/custom/local_settings.py

Performance Considerations

New Volume Performance

Named volumes are typically faster than bind mounts:

• Before: Filesystem overhead on host
• After: Direct container filesystem (better I/O)

Monitoring Volume Usage

# Check volume sizes
docker system df -v

# Check specific volume
docker volume inspect mediacms_media_files

New Backup Strategy

With named volumes, backups change:

# Database backup
docker compose exec db pg_dump -U mediacms mediacms > backup.sql

# Media files backup
docker run --rm \
  -v mediacms_media_files:/data:ro \
  -v $(pwd):/backup \
  alpine tar czf /backup/media_backup_$(date +%Y%m%d).tar.gz -C /data .

Or use the Makefile:

make backup-db

Getting Help

If you encounter issues:

1. Check logs: docker compose logs <service>
2. Check GitHub Issues: Search for similar problems
3. Rollback: Use the rollback procedure above
4. Report: Open an issue with:
   • Your docker-compose.yaml
   • Output of docker compose ps
   • Relevant logs
   • Steps to reproduce

Summary of Benefits

After upgrading to 7.3:

✅ Better separation of concerns - each service has one job ✅ Easier scaling - scale web/workers independently ✅ Better security - containers run as www-data, not root ✅ Faster deployments - static files built into image ✅ Cleaner customization - dedicated custom/ directory ✅ Easier SSL setup - docker-compose-cert.yaml overlay ✅ Better volume management - named volumes instead of bind mounts

Timeline Recommendation

• Small instance (<100 videos): 30-60 minutes
• Medium instance (100-1000 videos): 1-3 hours
• Large instance (>1000 videos): Plan for several hours

Schedule during low-traffic period!