tablejerseys-web/GHCR-SETUP.md

GitHub Container Registry Setup for Slipmatz Web

Overview

The slipmatz-web application is automatically built and published to GitHub Container Registry (GHCR) on every push to main/develop branches.

Container Registry URL

ghcr.io/franknstayn/slipmatz-web:latest

GitHub Actions Workflow

The workflow (.github/workflows/docker-publish.yml) automatically:

1. Builds the Docker image on every push to main or develop
2. Pushes to GitHub Container Registry
3. Tags images with:
   • latest (for main branch)
   • Branch name (e.g., develop)
   • Git SHA (e.g., main-abc1234)
   • Version tags (for tagged releases)

Repository Setup

1. Enable GitHub Actions

• Go to repository Settings → Actions → General
• Ensure "Read and write permissions" is enabled for GITHUB_TOKEN

2. Make Package Public (Optional)

• Go to repository → Packages → slipmatz-web
• Package settings → Change visibility → Public
• (Or keep private if preferred)

Deployment

Pull from Registry (Recommended for Production)

cd crew-infrastructure
docker compose pull slipmatz_web
docker compose up -d slipmatz_web

Build Locally (Development)

Uncomment the build section in docker-compose.yml:

slipmatz_web:
  build:
    context: ../apps/slipmatz-web
    dockerfile: Dockerfile
  # image: ghcr.io/franknstayn/slipmatz-web:latest

Using Specific Versions

Pull specific tag

docker pull ghcr.io/franknstayn/slipmatz-web:develop
docker pull ghcr.io/franknstayn/slipmatz-web:v1.0.0
docker pull ghcr.io/franknstayn/slipmatz-web:main-abc1234

Use in docker-compose.yml

slipmatz_web:
  image: ghcr.io/franknstayn/slipmatz-web:v1.0.0

CI/CD Pipeline

Automatic Builds Trigger On:

• Push to main → builds latest tag
• Push to develop → builds develop tag
• Create tag v* → builds version tags
• Pull request → builds but doesn't push

Workflow Features:

• ✅ Docker layer caching (faster builds)
• ✅ Multi-platform support ready
• ✅ Automatic tagging strategy
• ✅ Build cache optimization

Manual Build and Push

If you need to manually build and push:

# Login to GHCR
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

# Build and tag
cd apps/slipmatz-web
docker build -t ghcr.io/franknstayn/slipmatz-web:latest .

# Push
docker push ghcr.io/franknstayn/slipmatz-web:latest

Troubleshooting

Authentication Error

If you get permission denied when pulling:

# Login with GitHub Personal Access Token
echo $GITHUB_TOKEN | docker login ghcr.io -u franknstayn --password-stdin

Create token at: https://github.com/settings/tokens

• Scope needed: read:packages

Image Not Found

• Check if workflow ran successfully in Actions tab
• Verify package exists at: https://github.com/franknstayn?tab=packages
• Ensure package visibility matches your needs (public/private)

Old Image Cached

docker compose pull slipmatz_web --no-cache
docker compose up -d slipmatz_web

Benefits

✅ Faster Deployments: Pull pre-built images instead of building on server
✅ Version Control: Track and rollback to specific image versions
✅ Consistent Builds: Same image across environments
✅ CI/CD Ready: Automatic builds on code push
✅ Free: GitHub Packages is free for public repos

Next Steps

1. Push code to trigger first build
2. Verify image appears in GitHub Packages
3. Pull and deploy on production server
4. Set up similar workflow for slipmatz-backend