Dave Vigil
11e12ea8d5
Some checks failed
Compile my Keebs / lint-and-compile (push) Failing after 1s
Build QMK Firmware with Docker / build (draculad, draculad) (push) Has been cancelled
Build QMK Firmware with Docker / build (iris, keebio/iris/rev8) (push) Has been cancelled
Build QMK Firmware with Docker / build (scottogame, handwired/scottokeebs/scottogame) (push) Has been cancelled
Build QMK Firmware with Docker / build (sweep, ferris/sweep) (push) Has been cancelled
Build QMK Firmware with Docker / build (swoop, bluebell/swoop) (push) Has been cancelled
Build QMK Firmware with Docker / release (push) Has been cancelled
101 lines
2.7 KiB
Markdown
101 lines
2.7 KiB
Markdown
# 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. |