ci-actions/docker-build/README.md

# docker-build

Build and push Docker images with S3 caching and optional Nix cache support.

## Features

- **S3 build cache**: Uses your self-hosted S3 (SeaweedFS) for fast layer caching
- **Nix cache integration**: Automatically configures Attic cache for Dockerfiles using Nix
- **Auto-tagging**: Smart tagging based on branches, PRs, and semver tags
- **Multi-registry support**: Works with Forgejo Docker registry or any other

## Usage

### Basic example

```yaml
name: Build Docker Image
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: https://git.toph.so/toph/ci-actions/docker-build@main
        with:
          dockerfile: ./Dockerfile
          image-name: git.toph.so/${{ gitea.repository }}
          registry-password: ${{ secrets.GITEA_TOKEN }}
```

### With Nix cache support

For Dockerfiles that use Nix/Lix (e.g., `FROM ghcr.io/lix-project/lix`):

```yaml
- uses: https://git.toph.so/toph/ci-actions/docker-build@main
  with:
    dockerfile: ./Dockerfile.nix
    image-name: git.toph.so/${{ gitea.repository }}/nix
    registry-password: ${{ secrets.GITEA_TOKEN }}
    enable-nix-cache: 'true'
```

### Multiple images from one repo

```yaml
jobs:
  build-web:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: https://git.toph.so/toph/ci-actions/docker-build@main
        with:
          dockerfile: ./deploy/Dockerfile
          image-name: git.toph.so/${{ gitea.repository }}
          registry-password: ${{ secrets.GITEA_TOKEN }}

  build-worker:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: https://git.toph.so/toph/ci-actions/docker-build@main
        with:
          dockerfile: ./deploy/Dockerfile.worker
          image-name: git.toph.so/${{ gitea.repository }}/worker
          registry-password: ${{ secrets.GITEA_TOKEN }}
```

### Custom tags

```yaml
- uses: https://git.toph.so/toph/ci-actions/docker-build@main
  with:
    dockerfile: ./Dockerfile
    image-name: git.toph.so/myorg/myapp
    registry-password: ${{ secrets.GITEA_TOKEN }}
    tags: |
      git.toph.so/myorg/myapp:latest
      git.toph.so/myorg/myapp:v1.0.0
      git.toph.so/myorg/myapp:stable
```

## Inputs

| Input | Required | Default | Description |
|-------|----------|---------|-------------|
| `dockerfile` | ✅ | - | Path to Dockerfile |
| `image-name` | ✅ | - | Full image name (e.g., `git.toph.so/user/repo`) |
| `registry-password` | ✅ | - | Registry password/token |
| `context` | ❌ | `.` | Build context path |
| `registry` | ❌ | `git.toph.so` | Docker registry |
| `registry-username` | ❌ | `${{ gitea.actor }}` | Registry username |
| `push` | ❌ | `true` | Push image to registry |
| `tags` | ❌ | auto-generated | Custom tags (newline-separated) |
| `s3-cache-bucket` | ❌ | `docker-cache` | S3 bucket for build cache |
| `s3-endpoint` | ❌ | `https://s3.toph.so` | S3 endpoint URL |
| `enable-nix-cache` | ❌ | `false` | Configure Nix binary cache |
| `attic-endpoint` | ❌ | `https://cache.toph.so` | Attic/Nix cache endpoint |

## Auto-generated tags

When `tags` input is not provided, tags are auto-generated based on the event:

| Event | Generated tags |
|-------|----------------|
| Push to `main` | `main`, `<short-sha>` |
| Push tag `v1.2.3` | `1.2.3`, `1.2`, `1`, `latest`, `<short-sha>` |
| Pull request #42 | `pr-42`, `<short-sha>` |

## S3 Cache

The action uses your self-hosted S3 (SeaweedFS) for Docker build cache layers, which:
- Speeds up builds by reusing unchanged layers
- Works across different runners and workflow runs
- Automatically managed by Docker Buildx

**No additional setup required** — the cache is automatically used if S3 is accessible.

## Nix Cache Integration

When `enable-nix-cache: 'true'`, the action configures:
- `cache.nixos.org` (official Nix cache)
- `cache.toph.so/ci` (your CI cache, 90d retention)
- `cache.toph.so/toph` (your trusted cache, 180d retention)

This allows Dockerfiles using Nix to fetch pre-built derivations instead of rebuilding from source.

## Prerequisites

**For all builds:**
- S3 service running at `s3.toph.so` (SeaweedFS)
- `GITEA_TOKEN` secret configured (auto-available in Forgejo Actions)

**For Nix-enabled builds:**
- Attic cache service running at `cache.toph.so`

## Examples

See the main [ci-actions README](../README.md) for infrastructure setup details.