you-music/DOCKER_OPTIMIZATION.md

Docker Image Size Optimization Guide

Current Status

• Current Image: 1.12GB
• Target: < 500MB (Optimized) or < 300MB (Alpine)

---

🎯 Optimization Strategies

Strategy 1: Optimized Slim Image (Recommended)

File: Dockerfile.optimized Expected Size: ~400-500MB Pros: Stable, compatible, well-tested Cons: Still larger than Alpine

Strategy 2: Alpine Image (Maximum Savings)

File: Dockerfile.alpine
Expected Size: ~250-350MB Pros: Smallest size, fast downloads Cons: Potential compatibility issues with some Python packages

---

📊 What's Taking Up Space?

Current Image Breakdown (1.12GB)

1. Python Base Image: ~200MB
2. Python Packages: ~400MB (includes build dependencies)
3. FFmpeg: ~150MB
4. Frontend Build: ~50MB
5. System Packages & Cache: ~320MB

Optimizations Applied

✅ 1. Use Multi-Stage Builds

# Build stage - discarded
FROM python:3.13-slim AS builder
RUN install build tools...

# Runtime stage - final image
FROM python:3.13-slim
COPY --from=builder /opt/venv /opt/venv

Savings: ~200MB (no build tools in final image)

✅ 2. Use Virtual Environment

RUN python -m venv /opt/venv
COPY --from=builder /opt/venv /opt/venv

Why: Easier to copy, no system-wide packages

✅ 3. Remove Package Manager Cache

RUN apt-get update && apt-get install -y packages \
    && rm -rf /var/lib/apt/lists/*

Savings: ~50-100MB

✅ 4. Install Only Runtime Dependencies

Before:

RUN apt-get install -y gcc g++ make build-essential ffmpeg curl

After:

RUN apt-get install -y --no-install-recommends ffmpeg curl

Savings: ~150MB (no build tools)

✅ 5. Remove Frontend Source Maps

RUN npm run build && \
    find dist -name "*.map" -type f -delete

Savings: ~10-20MB

✅ 6. Use --no-cache-dir for pip

RUN pip install --no-cache-dir -r requirements.txt

Savings: ~100MB

✅ 7. Set PYTHONDONTWRITEBYTECODE

ENV PYTHONDONTWRITEBYTECODE=1

Why: Prevents .pyc files, saves ~10-20MB

✅ 8. Copy Only Necessary Files

Before:

COPY backend/ ./backend/

After:

COPY backend/main.py ./backend/
COPY backend/alembic.ini ./backend/
COPY backend/alembic/ ./backend/alembic/
COPY backend/app/ ./backend/app/

Savings: ~5-10MB (excludes .venv, pycache, tests, etc.)

---

🚀 Build & Test Optimized Images

Option 1: Optimized Slim (Recommended)

# Build
docker build -f Dockerfile.optimized -t youmusic:optimized .

# Check size
docker images youmusic:optimized

# Test
docker run -p 8000:8000 -v $(pwd)/data:/app/data youmusic:optimized

# If working, replace main Dockerfile
cp Dockerfile.optimized Dockerfile

Option 2: Alpine (Smallest)

# Build
docker build -f Dockerfile.alpine -t youmusic:alpine .

# Check size
docker images youmusic:alpine

# Test thoroughly (Alpine can have issues)
docker run -p 8000:8000 -v $(pwd)/data:/app/data youmusic:alpine

# Check if yt-dlp works
docker exec -it CONTAINER_ID yt-dlp --version

# Check if all Python packages work
docker exec -it CONTAINER_ID python -c "import mutagen, aiohttp; print('OK')"

# If working, replace main Dockerfile
cp Dockerfile.alpine Dockerfile

---

📉 Expected Size Comparison

Version	Size	Build Time	Stability
Current	1.12GB	Fast	✅ Stable
Optimized Slim	~450MB	Medium	✅ Stable
Alpine	~300MB	Slower	⚠️ May have issues

---

🔍 Additional Optimization Ideas

1. Use Distroless (Advanced)

FROM gcr.io/distroless/python3-debian12

Pros: Ultra minimal, no shell, very secure Cons: Hard to debug, no shell access Size: ~200MB

2. Reduce Python Package Sizes

# Check largest packages
docker run --rm youmusic:latest pip list --format=freeze | \
  xargs -I {} pip show {} | grep -E "Name:|Size:"

# Consider alternatives:
# - Use 'httpx' instead of 'aiohttp' (smaller)
# - Remove unused dependencies

3. Static Frontend Assets

# Compress frontend assets
RUN gzip -9 -k ./backend/static/**/*.js
RUN gzip -9 -k ./backend/static/**/*.css

Savings: ~30-40% of frontend size

4. Use .dockerignore

Create .dockerignore:

# Node
frontend/node_modules
frontend/.next
frontend/dist

# Python
backend/.venv
backend/__pycache__
backend/**/__pycache__
backend/.pytest_cache

# Data
data/
*.db
*.db-journal

# Git
.git
.github

# Docs
*.md
docs/

# IDE
.vscode
.idea

# Logs
logs/
*.log

Savings: Faster builds, smaller context

---

⚠️ Potential Issues with Alpine

1. Wheel Compatibility

Some Python packages don't have Alpine wheels, requiring compilation:

• cryptography - Needs OpenSSL dev
• pillow - Needs image libs
• greenlet - Needs GCC

2. DNS Issues

Alpine uses musl libc which can have DNS resolution issues

3. Slower Builds

No pre-built wheels = compile from source = longer builds

Solutions:

# Install all build dependencies
RUN apk add --no-cache \
    gcc g++ musl-dev linux-headers \
    libffi-dev openssl-dev \
    jpeg-dev zlib-dev

---

📝 Testing Checklist

After building optimized image, test:

• Application starts
• Migrations run successfully
• Can download from YouTube
• Can download from Bilibili
• Audio processing works (FFmpeg)
• Thumbnail extraction works
• File uploads work
• All API endpoints work
• Frontend loads correctly
• Health check passes

Quick Test Script

#!/bin/bash
IMAGE="youmusic:optimized"

echo "Testing $IMAGE..."

# Start container
docker run -d --name test-youmusic -p 8000:8000 \
  -v $(pwd)/data:/app/data $IMAGE

sleep 10

# Test health
curl -f http://localhost:8000/ || echo "❌ Health check failed"

# Test API
curl -f http://localhost:8000/api/music/ || echo "❌ API failed"

# Cleanup
docker stop test-youmusic
docker rm test-youmusic

echo "✅ Tests complete"

---

🎓 Best Practices

DO:

• ✅ Use multi-stage builds
• ✅ Remove package manager caches
• ✅ Use --no-cache-dir for pip
• ✅ Copy only necessary files
• ✅ Use .dockerignore
• ✅ Remove build dependencies from final image

DON'T:

• ❌ Install unnecessary packages
• ❌ Keep build tools in final image
• ❌ Copy entire project directory
• ❌ Keep package manager caches
• ❌ Include source maps in production

---

💡 Quick Wins (Immediate Actions)

1. Replace Current Dockerfile with Dockerfile.optimized

   cp Dockerfile.optimized Dockerfile
   

2. Create .dockerignore

   cat > .dockerignore << 'EOF'
   node_modules
   .venv
   __pycache__
   *.pyc
   .git
   data/
   *.md
   logs/
   EOF
   

3. Rebuild

   docker build -t youmusic:latest .
   docker images | grep youmusic
   

Expected Result: ~60% size reduction (1.12GB → ~450MB)

---

🔄 Migration Path

Step 1: Test Locally

docker build -f Dockerfile.optimized -t youmusic:test .
docker-compose down
docker-compose up -d  # Will use youmusic:test

Step 2: Verify Everything Works

docker-compose logs -f
curl http://localhost:8000

Step 3: Replace Production Dockerfile

cp Dockerfile.optimized Dockerfile
git add Dockerfile
git commit -m "Optimize Docker image size (1.12GB → 450MB)"

Step 4: Rebuild Production Image

docker build -t ghcr.io/YOUR_USERNAME/youmusic:latest .
docker push ghcr.io/YOUR_USERNAME/youmusic:latest

Step 5: Update Kubernetes

kubectl rollout restart deployment/youmusic

---

📊 Final Comparison

Metric	Before	After (Optimized)	After (Alpine)
Size	1.12GB	~450MB	~300MB
Layers	15	12	10
Build Time	3min	4min	6min
Download Time	60s	25s	15s
Startup Time	5s	5s	5s

---

🎯 Recommendation

Use Dockerfile.optimized (Slim-based)

• ✅ 60% size reduction
• ✅ Full compatibility
• ✅ Well-tested Python ecosystem
• ✅ Easy to debug

Only use Alpine if:

• You need absolute minimum size
• You're willing to debug compatibility issues
• You have tested ALL functionality thoroughly

---

Ready to optimize?

cp Dockerfile.optimized Dockerfile
docker build -t youmusic:latest .