This guide explains the steps I went through to setup my own instance of QMK Configurator. These steps should serve as a general how-to guide and hopefully fill in some gaps for people who may have gotten stuck. Some of the details, specifically adding your own custom keyboard to the configurator, can be approached a few different ways; so the information in that section may be less prescriptive and more for reference.
I did this on a machine running Ubuntu Jammy. I was not able to get this all working locally due to some networking challenges I couldn’t figure out. Due to that issue (and since I wanted to give some people access over the Internet anyways), I hosted my configurator using a cloud service provider. I chose to use Kamatera since they offer a 30 day free trial for 1 server and pricing beyond that was reasonable, but anything similar would work.
As a prerequisite you’ll need to already have Docker and Docker Compose setup. Instructions for installing Docker on Ubuntu (and other distros) can be found on the Docker website. You don’t need Docker Desktop unless you find that useful for managing your containers.
I’d recommend reading through this full post first before trying to follow it step-by-step. I don’t explicity state it in any of the steps but you should try building the containers at various points along the way. The command is:
docker compose build
Clone QMK Web Stack Repo
Clone the qmk_web_stack repo from GitHub.
git clone --recurse-submodules https://github.com/qmk/qmk_web_stack.git
One of the submodules fails to clone so you’ll need to do that manually
cd qmk_web_stack git clone --recurse-submodules https://github.com/qmk/qmk_metrics_aggregator.git
Run this script in the main project directory to update all submodules to their latest.
You’ll receive an error on qmk_metrics_aggregator but you can ignore it.
Configuring the Web Stack
Open docker-compose.yml in a text editor and update the configuration values.
Below is an example where I’ve highlighted the changes for my config.
Note: I couldn’t get the configurator working end-to-end on a local machine, so I ended up using a cloud hosting service. As such, this config assumes that you’re doing the same. You might still be able to get it to work locally.
Double Note: You should probably change to minio secret if you plan to host this online
I was receiving an error with some of the python package dependencies after launching the configurator. To fix that issue, I needed to add a specific version of one additional dependency in requirements.txt
Add a Custom Keyboard
If you’re setting up your own Configurator, it’s likely that the reason for this is to test out your own keyboard firmware. The instructions below will explain how to do that.
It took me a lot of experimenting before I was able to get everything working. I wanted to avoid modifying any of the submodule files but found that some were unavoidable for various reasons.
Note: These instructions explain how to point the configurator to your own keyboard list. So the default list will no longer be available after doing these steps. The steps below are only necessary if that’s your intention.
Custom Keyboard Data
The configurator pulls both the list of keyboard and the individual keyboard info/readme files from keyboards.qmk.fm
There were two ways I could think of to get around this: point these URLs to pull from static files or create a custom API that returns this data. Since I was needing the flexibility to make frequent changes I chose the latter. Files are probably easier, though. In either case, the JSON served up to the configurator needs to mimic the structures that are returned by the real keyboards.qmk.fm
These are the relevent endpoints and the structures to mimic:
(Just a normal readme.md file)
Your JSON files or APIs will need to be accessible following the URL patterns above. So If I wanted to serve up this JSON data from https://snacksthecat.com, I would need to follow the URL pattern:
https://snacksthecat.com/v1/keyboards/<keyboard>/info.json |-------base url-------||----path----||-kb name-||--file--|
Once I had my APIs setup, I added the necessary environment variable to the qmk_configurator Dockerfile so that it gets picked up by the constants declaration file
ENV VITE_API_URL=/api ENV VITE_KEYBOARDS_URL=https://snacksthecat.com
Define a Default Layout
If you were to spin up the configurator at this point, it should load, but with a totally blank layout. The steps below explain how to create a default layout that gets picked up by the configurator when the keyboard first loads.
The default keymaps for the configurator are all located in:
They’re organized by letter, so navigate into the folder with the first letter of your keyboard’s name.
You’ll need to create a new file with a filename that follows this pattern:
Note: If your keyboard name has slashes in it, you’ll need to replace them with underscores. For instance, my default filename was: converter_ibmpc_usb_teensy_default.json
Below is an example of the contents of one of these default layout files (excuse the formatting):
The “layers” node is basically a JSON-ified version of your keymap.c file.
You can read more about the specifics of the default keymap file on the QMK website. It’s the same file that you can download/upload to the configurator to save/load your keymap.
Finally it’s time to build and launch the containers which should bring your configurator online and make everything work end-to-end with all of your changes.
Navigate to the main project directory:
Run the following command to build all of the Docker containers. It will take some minutes.
docker compose build
Hopefully it builds OK. If so, launch all of the containers using the following command:
docker compose up
You’ll want to keep an eye on the log output and make sure that all service workers get launched. If you see some ugly errors, most likely one of these failed to launch and you’ll need to backtrack.
Now you should be able to visit your configurator at: http://<your_url>:5000