etsy-finance-tracker/GITHUB_CONTAINER_REGISTRY.md

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

brew install --cask docker

2. Clone Repository (Config Files Only)

git clone https://github.com/dlawler489/etsy-finance-tracker.git
cd etsy-finance-tracker

3. Setup Data Directory

mkdir -p data/{csv,pdf,spreadsheets}
# Copy your business files to data directories

4. Deploy Using Pre-built Image

# 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

# 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:

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

# Use latest main branch
docker-compose -f docker-compose.ghcr.yml up -d

Production Deployment

# 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

# 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

# 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

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

Version Conflicts

# 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

# 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