soundwave/docs/DOCKER_IMAGE_FIX.md

🐛 Docker Image Pull Issue - Fixed

Problem Identified

The deployment was failing on new machines because:

1. ❌ No image published - The Docker image aiulian25/soundwave:latest was never pushed to Docker Hub
2. ❌ No CI/CD pipeline - No automated builds to GitHub Container Registry
3. ❌ No fallback option - Users couldn't build locally if pull failed

Solutions Implemented

1. GitHub Actions Workflow (Automated)

Created .github/workflows/docker-publish.yml:

• ✅ Automatically builds Docker image on push to main/master
• ✅ Publishes to GitHub Container Registry (ghcr.io)
• ✅ Supports multi-platform (amd64, arm64)
• ✅ Creates versioned tags for releases
• ✅ Uses GitHub Actions cache for faster builds

2. Updated docker-compose.yml

Changed image source from Docker Hub to GitHub Container Registry:

image: ghcr.io/aiulian25/soundwave:latest

Added commented build option as fallback:

# build:
#   context: .
#   dockerfile: Dockerfile

🚀 How to Use

For End Users (After First Push)

Option 1: Pull Pre-built Image (Recommended)

# Clone repository
git clone https://github.com/aiulian25/soundwave.git
cd soundwave

# Start services (will pull from ghcr.io)
docker compose up -d

Option 2: Build Locally (If pull fails or for development)

# Clone repository
git clone https://github.com/aiulian25/soundwave.git
cd soundwave

# Build frontend first
cd frontend
npm install
npm run build
cd ..

# Build and start with Docker
docker compose up -d --build

For Repository Owner (First Time Setup)

1. Push to GitHub - Push this repository to GitHub
2. Enable Package Publishing:
   • Go to repository Settings → Actions → General
   • Under "Workflow permissions", select "Read and write permissions"
   • Check "Allow GitHub Actions to create and approve pull requests"
3. Trigger First Build:
   • Push to main branch, or
   • Go to Actions → "Build and Publish Docker Image" → Run workflow

The image will be published to: ghcr.io/yourusername/soundwave:latest

Making the Image Public

By default, GitHub Container Registry images are private. To make it public:

1. Go to your GitHub profile → Packages
2. Click on soundwave package
3. Click "Package settings"
4. Scroll to "Danger Zone"
5. Click "Change visibility" → "Public"

📝 Deployment Files Updated

1. ✅ .github/workflows/docker-publish.yml - CI/CD pipeline
2. ✅ docker-compose.yml - Updated image reference
3. ✅ This troubleshooting guide

🔄 Updating the Image

After pushing code changes:

1. GitHub Actions automatically builds new image
2. Users pull latest with: docker compose pull && docker compose up -d

🛠️ Alternative: Docker Hub

If you prefer Docker Hub over GitHub Container Registry:

1. Login to Docker Hub:

   docker login
   

2. Build and push:

   cd frontend && npm install && npm run build && cd ..
   docker build -t aiulian25/soundwave:latest .
   docker push aiulian25/soundwave:latest
   

3. Update docker-compose.yml:

   image: aiulian25/soundwave:latest
   

4. Add to GitHub Secrets (for automation):

   • Repository Settings → Secrets → Actions
   • Add DOCKERHUB_USERNAME and DOCKERHUB_TOKEN
   • Update workflow to use Docker Hub

📋 Quick Reference

Current Image Location: ghcr.io/aiulian25/soundwave:latest
Build Context: Root directory (includes frontend/dist)
Platforms Supported: linux/amd64, linux/arm64
Auto-build: On push to main/master branch

✅ Verification

After setup, verify the image is available:

# Check if image exists (after first GitHub Actions run)
docker pull ghcr.io/aiulian25/soundwave:latest

# Or check GitHub Packages
# Visit: https://github.com/yourusername?tab=packages

🎯 Benefits

1. Zero-config for users - Just docker compose up -d
2. Automatic updates - CI/CD builds on every push
3. Multi-platform - Works on Intel and ARM (Apple Silicon, Raspberry Pi)
4. Version tags - Can pin to specific versions
5. Fallback option - Can build locally if needed