152 lines
4.2 KiB
Markdown
152 lines
4.2 KiB
Markdown
# 🐛 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`](.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:
|
|
```yaml
|
|
image: ghcr.io/aiulian25/soundwave:latest
|
|
```
|
|
|
|
Added commented build option as fallback:
|
|
```yaml
|
|
# build:
|
|
# context: .
|
|
# dockerfile: Dockerfile
|
|
```
|
|
|
|
## 🚀 How to Use
|
|
|
|
### For End Users (After First Push)
|
|
|
|
**Option 1: Pull Pre-built Image** (Recommended)
|
|
```bash
|
|
# 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)
|
|
```bash
|
|
# 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`](.github/workflows/docker-publish.yml) - CI/CD pipeline
|
|
2. ✅ [`docker-compose.yml`](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**:
|
|
```bash
|
|
docker login
|
|
```
|
|
|
|
2. **Build and push**:
|
|
```bash
|
|
cd frontend && npm install && npm run build && cd ..
|
|
docker build -t aiulian25/soundwave:latest .
|
|
docker push aiulian25/soundwave:latest
|
|
```
|
|
|
|
3. **Update docker-compose.yml**:
|
|
```yaml
|
|
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:
|
|
|
|
```bash
|
|
# 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
|