# docker-build-nix

Build and push Docker/OCI images generated by Nix flakes, with Attic cache integration.

## Features

- **Reproducible builds**: Uses Nix flakes for bit-for-bit identical images
- **Attic caching**: Pushes build artifacts to your Attic cache for faster subsequent builds
- **Nix store optimization**: Leverages Nix's existing binary caches (nixos.org + your Attic)
- **Smaller images**: Nix `dockerTools.buildLayeredImage` creates optimized layers

## Usage

### Basic example

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

jobs:
  build:
    runs-on: nix  # Requires runner with Nix
    steps:
      - uses: actions/checkout@v4

      - uses: https://git.toph.so/toph/ci-actions/docker-build-nix@main
        with:
          flake-output: .#dojo-image
          image-name: toph/dojo
          registry-password: ${{ secrets.GITEA_TOKEN }}
        env:
          ATTIC_TOKEN: ${{ secrets.ATTIC_TOKEN }}
```

### Multiple images

```yaml
jobs:
  build-web:
    runs-on: nix
    steps:
      - uses: actions/checkout@v4
      - uses: https://git.toph.so/toph/ci-actions/docker-build-nix@main
        with:
          flake-output: .#dojo-image
          image-name: toph/dojo
          image-tag: main
          registry-password: ${{ secrets.GITEA_TOKEN }}
        env:
          ATTIC_TOKEN: ${{ secrets.ATTIC_TOKEN }}

  build-agent:
    runs-on: nix
    steps:
      - uses: actions/checkout@v4
      - uses: https://git.toph.so/toph/ci-actions/docker-build-nix@main
        with:
          flake-output: .#agent-image
          image-name: toph/dojo/agent
          image-tag: main
          registry-password: ${{ secrets.GITEA_TOKEN }}
        env:
          ATTIC_TOKEN: ${{ secrets.ATTIC_TOKEN }}
```

## Inputs

| Input | Required | Default | Description |
|-------|----------|---------|-------------|
| `flake-output` | ✅ | - | Nix flake output (e.g., `.#dojo-image`) |
| `image-name` | ✅ | - | Target image name (e.g., `user/repo`) |
| `registry-password` | ✅ | - | Registry password/token |
| `image-tag` | ❌ | `main` | Image tag |
| `registry` | ❌ | `git.toph.so` | Docker registry |
| `registry-username` | ❌ | `${{ gitea.actor }}` | Registry username |
| `cache-name` | ❌ | `ci` | Attic cache name |
| `attic-endpoint` | ❌ | `https://cache.toph.so` | Attic endpoint |

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `ATTIC_TOKEN` | Optional | Attic token for pushing to cache. If not set, skips cache push. |

## How It Works

1. **Build with Nix**: Runs `nix build <flake-output>` which uses Nix caching
2. **Push to Attic**: Uploads the entire build closure to your Attic cache
3. **Load to Docker**: Loads the OCI tarball into local Docker daemon
4. **Tag & Push**: Tags and pushes to your Docker registry

## Example Flake

Your `flake.nix` should export image outputs:

```nix
{
  outputs = { self, nixpkgs }:
    let
      pkgs = import nixpkgs { system = "x86_64-linux"; };
    in
    {
      packages.x86_64-linux = {
        # Your app
        default = pkgs.callPackage ./package.nix { };

        # OCI image
        dojo-image = pkgs.dockerTools.buildLayeredImage {
          name = "dojo";
          tag = "latest";
          contents = [ self.packages.x86_64-linux.default ];
          config = {
            Cmd = [ "${self.packages.x86_64-linux.default}/bin/dojo" ];
          };
        };
      };
    };
}
```

## Prerequisites

- **Nix runner**: Runner with `nix` label using `docker://registry.toph.so/nix-runner:latest`
- **Attic cache**: Optional but recommended for caching (`cache.toph.so`)
- **ATTIC_TOKEN**: Set in Forgejo secrets if you want cache push
- **GITEA_TOKEN**: Auto-available in Forgejo Actions

## Comparison with docker-build

| Feature | docker-build | docker-build-nix |
|---------|-------------|------------------|
| Build method | Docker | Nix |
| Reproducibility | Layer-dependent | Byte-for-byte |
| Caching | S3 layers | Attic derivations |
| Image size | Larger | Optimized |
| Runner | Any | Requires Nix |

## See Also

- [docker-build](../docker-build/) - Traditional Docker builds with S3 cache
- [push-nix-cache](../push-nix-cache/) - Push arbitrary Nix paths to Attic