# QMK Firmware Docker Build Environment

This repository includes a custom Docker setup for building QMK firmware in CI/CD environments.

## Files

- `Dockerfile` - Custom Docker image for QMK firmware builds
- `.dockerignore` - Excludes unnecessary files from Docker build context
- `build.sh` - Convenience script for building firmware locally
- `.github/workflows/docker-build.yml` - GitHub Actions workflow using the custom Docker image

## Features

- Based on Ubuntu 22.04 for stability
- Includes ARM and AVR toolchains
- Pre-installed QMK CLI and dependencies
- Automatic symlink setup for your keymaps
- Optimized for your specific keyboard configurations

## Local Usage

### Building the Docker Image

```bash
docker build --load -t qmk-builder .
```

**Note:** The `--load` flag is required to make the image available locally with newer Docker versions.

### Building Firmware

#### Using the build script:
```bash
# Build all keyboards
./build.sh

# Build specific keyboard
./build.sh iris

# Build with custom user
./build.sh iris myuser
```

#### Using Docker directly:
```bash
# Build all keyboards
docker run --rm \
  -v "$(pwd):/workspace" \
  -w /workspace \
  -e USER=dgvigil \
  qmk-builder \
  bash -c "cd /qmk_firmware && qmk compile -kb keebio/iris/rev8 -km dgvigil"
```

## CI/CD Usage

The `.github/workflows/docker-build.yml` workflow demonstrates how to use this Docker setup in GitHub Actions:

1. Builds the Docker image
2. Builds each keyboard in parallel
3. Uploads firmware artifacts
4. Creates releases on main branch pushes

## Supported Keyboards

- `draculad` → `draculad`
- `iris` → `keebio/iris/rev8`
- `scottogame` → `handwired/scottokeebs/scottogame`
- `sweep` → `ferris/sweep`
- `swoop` → `bluebell/swoop`

## Environment Variables

- `USER` - The QMK user name (defaults to `dgvigil`)
- `QMK_HOME` - Path to QMK firmware (set to `/qmk_firmware`)

## Differences from qmkfm/qmk_cli

This custom Dockerfile provides:

1. **Faster builds** - Pre-installed toolchains and dependencies
2. **Better integration** - Automatic symlink setup for your keymaps
3. **Consistent environment** - Same setup across local and CI builds
4. **Optimized for your workflow** - Tailored to your specific keyboard configurations

## Troubleshooting

### Build fails with toolchain errors
Make sure the Docker image is built with the latest QMK firmware:
```bash
docker build --no-cache -t qmk-builder .
```

### Symlinks not working
The entrypoint script automatically sets up symlinks, but you can verify they exist:
```bash
docker run --rm -v "$(pwd):/workspace" qmk-builder ls -la /qmk_firmware/keyboards/keebio/iris/keymaps/
```

### Missing firmware files
Check that the build completed successfully and look for `.hex` and `.uf2` files in the QMK firmware directory.