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

```yaml
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:

```bash
# 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