phundrak.com/.github/workflows/README.md

GitHub Actions Workflows

Docker Image Publishing

The publish-docker.yml workflow automatically builds and publishes Docker images for the backend service using Nix.

Triggers and Tagging Strategy

Event	Condition	Published Tags	Example
Tag push	Tag pushed to main branch	latest + version tag	latest, 1.0.0
Branch push	Push to develop branch	develop	develop
Pull request	PR opened or updated	pr<number>	pr12
Branch push	Push to main (no tag)	latest	latest

Required GitHub Secrets

Configure these secrets in your repository settings (Settings → Secrets and variables → Actions):

Secret Name	Description	Example Value
DOCKER_USERNAME	Username for Docker registry authentication	phundrak (Docker Hub) or phundrak (ghcr.io)
DOCKER_PASSWORD	Password or token for Docker registry	Personal Access Token (PAT) or password
CACHIX_AUTH_TOKEN	(Optional) Token for Cachix caching	Your Cachix auth token

For GitHub Container Registry (ghcr.io)

1. Create a Personal Access Token (PAT):

   • Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
   • Click "Generate new token (classic)"
   • Select scopes: write:packages, read:packages, delete:packages
   • Copy the generated token

2. Add secrets:

   • DOCKER_USERNAME: Your GitHub username
   • DOCKER_PASSWORD: The PAT you just created

For Docker Hub

1. Create an access token:

   • Go to Docker Hub → Account Settings → Security → Access Tokens
   • Click "New Access Token"
   • Set permissions to "Read, Write, Delete"
   • Copy the generated token

2. Add secrets:

   • DOCKER_USERNAME: Your Docker Hub username
   • DOCKER_PASSWORD: The access token you just created

For Custom Registry (e.g., labs.phundrak.com)

1. Obtain credentials from your registry administrator

2. Add secrets:

   • DOCKER_USERNAME: Your registry username
   • DOCKER_PASSWORD: Your registry password or token

Configuring the Docker Registry

The target registry is set via the DOCKER_REGISTRY environment variable in the workflow file. To change it:

1. Edit .github/workflows/publish-docker.yml
2. Modify the env section:

env:
  DOCKER_REGISTRY: ghcr.io  # Change to your registry (e.g., docker.io, labs.phundrak.com)
  IMAGE_NAME: phundrak/phundrak-dot-com-backend

Or set it as a repository variable:

• Go to Settings → Secrets and variables → Actions → Variables tab
• Add DOCKER_REGISTRY with your desired registry URL

Image Naming

Images are published with the name: ${DOCKER_REGISTRY}/${IMAGE_NAME}:${TAG}

For example:

• ghcr.io/phundrak/phundrak-dot-com-backend:latest
• ghcr.io/phundrak/phundrak-dot-com-backend:1.0.0
• ghcr.io/phundrak/phundrak-dot-com-backend:develop
• ghcr.io/phundrak/phundrak-dot-com-backend:pr12

Local Testing

To test the Docker image build locally:

# Build the image with Nix
nix build .#backendDockerLatest

# Load it into Docker
docker load < result

# Run the container
docker run -p 3100:3100 localhost/phundrak/backend-rust:latest

Troubleshooting

Authentication Failures

If you see authentication errors:

1. Verify your DOCKER_USERNAME and DOCKER_PASSWORD secrets are correct
2. For ghcr.io, ensure your PAT has the correct permissions
3. Check that the DOCKER_REGISTRY matches your credentials

Build Failures

If the Nix build fails:

1. Test the build locally first: nix build .#backendDockerLatest
2. Check the GitHub Actions logs for specific error messages
3. Ensure all dependencies in flake.nix are correctly specified

Image Not Appearing in Registry

1. Verify the workflow completed successfully in the Actions tab
2. Check that the registry URL is correct
3. For ghcr.io, images appear at: https://github.com/users/USERNAME/packages/container/IMAGE_NAME
4. Ensure your token has write permissions