# GitHub Container Registry Deployment Guide

This guide shows how to deploy the Etsy Finance Tracker using pre-built images from GitHub Container Registry (GHCR).

## Benefits of Using GHCR

✅ **Automatic Builds**: Images built automatically on every commit  
✅ **Multi-Platform**: Supports both Intel and Apple Silicon Macs  
✅ **Fast Deployment**: No need to build locally, just pull and run  
✅ **Version Control**: Tagged images for each release  
✅ **Free for Public Repos**: No additional cost  

## How It Works

1. **GitHub Actions** automatically builds Docker images when you push code
2. **Images are pushed** to GitHub Container Registry (`ghcr.io`)
3. **Your Mac Mini** pulls the pre-built image and runs it
4. **Updates** are as simple as pulling the latest image

## Available Images

The following images are automatically built and published:

- `ghcr.io/dlawler489/etsy-finance-tracker:main` - Latest development
- `ghcr.io/dlawler489/etsy-finance-tracker:v1.0.0` - Tagged releases
- `ghcr.io/dlawler489/etsy-finance-tracker:sha-abc123` - Specific commits

## Mac Mini Deployment (Using GHCR)

### 1. Install Docker Desktop
```bash
brew install --cask docker
```

### 2. Clone Repository (Config Files Only)
```bash
git clone https://github.com/dlawler489/etsy-finance-tracker.git
cd etsy-finance-tracker
```

### 3. Setup Data Directory
```bash
mkdir -p data/{csv,pdf,spreadsheets}
# Copy your business files to data directories
```

### 4. Deploy Using Pre-built Image
```bash
# Option 1: Use GitHub Container Registry (recommended)
docker-compose -f docker-compose.ghcr.yml up -d

# Option 2: Traditional local build (slower)
docker-compose up --build -d
```

### 5. Access Application
- **Web Interface**: http://localhost:3000
- **Health Check**: http://localhost:3000/health

## Management Commands

### Update to Latest Version
```bash
# Pull latest image and restart
docker-compose -f docker-compose.ghcr.yml pull
docker-compose -f docker-compose.ghcr.yml up -d
```

### Use Specific Version
Edit `docker-compose.ghcr.yml` and change the image tag:
```yaml
etsy-tracker:
  image: ghcr.io/dlawler489/etsy-finance-tracker:v1.0.0  # Use specific version
```

### View Available Versions
Visit: https://github.com/dlawler489/etsy-finance-tracker/pkgs/container/etsy-finance-tracker

## GitHub Actions Workflow

The automated build process:

1. **Triggered by**: Push to main branch, tags, or pull requests
2. **Builds**: React client and Node.js server
3. **Creates**: Multi-platform Docker image (Intel + Apple Silicon)
4. **Publishes**: To GitHub Container Registry
5. **Artifacts**: Creates deployment files for easy setup

## Image Layers and Optimization

The Docker image includes:
- **Alpine Linux**: Minimal, secure base image
- **Node.js Runtime**: Latest LTS version
- **Built Application**: Pre-compiled React + API server
- **Security**: Non-root user, proper signal handling
- **Health Checks**: Built-in monitoring endpoints

## Deployment Strategies

### Development Deployment
```bash
# Use latest main branch
docker-compose -f docker-compose.ghcr.yml up -d
```

### Production Deployment
```bash
# Use specific tagged version
# Edit docker-compose.ghcr.yml to use version tag like :v1.0.0
docker-compose -f docker-compose.ghcr.yml up -d
```

### Rollback Strategy
```bash
# Switch back to previous version in docker-compose.ghcr.yml
docker-compose -f docker-compose.ghcr.yml pull
docker-compose -f docker-compose.ghcr.yml up -d
```

## Monitoring and Logs

```bash
# View all logs
docker-compose -f docker-compose.ghcr.yml logs -f

# View specific service logs
docker-compose -f docker-compose.ghcr.yml logs -f etsy-tracker
docker-compose -f docker-compose.ghcr.yml logs -f nginx

# Check container status
docker-compose -f docker-compose.ghcr.yml ps
```

## Advantages Over Local Build

| Aspect | Local Build | GHCR Deployment |
|--------|-------------|-----------------|
| **Setup Time** | 5-10 minutes | 1-2 minutes |
| **Build Required** | Yes, every time | No, pre-built |
| **Consistency** | May vary by machine | Identical everywhere |
| **Updates** | Rebuild required | Just pull & restart |
| **Platform Support** | Single architecture | Multi-platform |
| **Network Usage** | Downloads dependencies | Downloads image once |

## Troubleshooting

### Image Pull Issues
```bash
# Login to GitHub Container Registry (if private)
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin
```

### Version Conflicts
```bash
# Clean up and restart
docker-compose -f docker-compose.ghcr.yml down
docker system prune -f
docker-compose -f docker-compose.ghcr.yml up -d
```

### Check Available Images
```bash
# List all available tags
curl -s https://api.github.com/users/dlawler489/packages/container/etsy-finance-tracker/versions
```

## Security Notes

- Images are built in GitHub's secure environment
- No sensitive data included in images
- Your local `data/` directory remains private
- Images are scanned for vulnerabilities automatically
- Only public repository images are accessible without authentication