dgvigil-keebs/DOCKER_README.md

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

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:

# Build all keyboards
./build.sh

# Build specific keyboard
./build.sh iris

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

Using Docker directly:

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

docker build --no-cache -t qmk-builder .

Symlinks not working

The entrypoint script automatically sets up symlinks, but you can verify they exist:

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.