{"id":28573642,"url":"https://github.com/qmk/qmk_web_stack","last_synced_at":"2026-03-11T05:31:46.571Z","repository":{"id":86541551,"uuid":"163227056","full_name":"qmk/qmk_web_stack","owner":"qmk","description":null,"archived":false,"fork":false,"pushed_at":"2024-06-15T00:17:37.000Z","size":29,"stargazers_count":16,"open_issues_count":0,"forks_count":26,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-10-09T06:23:41.468Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qmk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"open_collective":"qmk-firmware"}},"created_at":"2018-12-26T23:57:29.000Z","updated_at":"2025-05-02T23:58:00.000Z","dependencies_parsed_at":null,"dependency_job_id":"dacdda4d-a62f-49a1-8aac-d93f08f12f5b","html_url":"https://github.com/qmk/qmk_web_stack","commit_stats":{"total_commits":23,"total_committers":7,"mean_commits":"3.2857142857142856","dds":0.6086956521739131,"last_synced_commit":"432af1196c61b89d6109af766a8af7d0e2bf2a20"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/qmk/qmk_web_stack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qmk%2Fqmk_web_stack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qmk%2Fqmk_web_stack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qmk%2Fqmk_web_stack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qmk%2Fqmk_web_stack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qmk","download_url":"https://codeload.github.com/qmk/qmk_web_stack/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qmk%2Fqmk_web_stack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30372170,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T21:41:54.280Z","status":"online","status_checked_at":"2026-03-11T02:00:07.027Z","response_time":84,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-10T21:18:50.914Z","updated_at":"2026-03-11T05:31:46.539Z","avatar_url":"https://github.com/qmk.png","language":"Shell","funding_links":["https://opencollective.com/qmk-firmware"],"categories":[],"sub_categories":[],"readme":"# QMK Web Stack\n\nThis is a container repository that makes developing against the QMK web services (Configurator, API, and the Compiler) easier.\n\n## Getting Started\n\nWe use Docker Compose to start and run the services required for QMK Configurator. Setting up a dev environment is a pretty simple process.\n\n1. Install and run [Docker](https://www.docker.com/).\n2. Clone this repository:\n   ```sh\n   git clone --recurse-submodules https://github.com/qmk/qmk_web_stack\n   cd qmk_web_stack\n   ```\n3. Fix the submodules (checks out each one to `master` or `main`):\n   ```sh\n   ./fix-submodules.sh\n   ```\n3. Build and start the Docker containers:\n   ```sh\n   docker-compose build\n   docker-compose up\n   ```\n4. Populate the database:\n   ```sh\n   ./populate_api.sh\n   ```\n5. Visit your local configurator: \u003chttp://localhost:5000/\u003e\n\n## Working With Your Environment\n\nYou are now ready to develop on your local environment. There are some things you can do outside the normal Docker Compose workflow that are helpful when developing features.\n\n### Running Tests\n\nThere are some functional tests for the `qmk_compiler` code. You can run them with the provided script:\n\n```sh\n./run_tests.sh\n```\n\nIf you want to run a subset of tests you can pass the fully resolved name to the test. Usually this is in the format `\u003ctest_module\u003e.\u003ctest_function_name\u003e`. For example you could pass in `test_qmk_compiler.test_0010_keyboard_list` to run only that test.\n\nYou should be aware that `test_qmk_compiler.test_0000_checkout_qmk_skip_cache` and `test_qmk_compiler.test_9999_teardown` are always run because some of the tests depend on them.\n\nExample:\n\n```sh\n./run_tests.sh test_qmk_compiler.test_0010_keyboard_list\n```\n\n### Controlling Which Git Repositories Are Used\n\nThe QMK API will clone and update `qmk_firmware` as needed. By default this means the `master` branch of \u003chttps://github.com/qmk/qmk_firmware\u003e. You can set environment variables for `qmk_compiler` and `qmk_api` inside `docker-compose.yml` to change this default. If you want to change the git branch for all repositories at once (`qmk_firmware`, `chibios`, `chibios-contrib`, `lufa`, `vusb`) you can set `GIT_BRANCH`. Otherwise you can change the branch on a repo-by-repo basis. You must set the git URL for all repos individually.\n\nThe default environment variables are:\n\n| Variable                     | Default                                   |\n|------------------------------|-------------------------------------------|\n| `QMK_FIRMWARE_PATH`          | `qmk_firmware`                            |\n| `QMK_GIT_BRANCH`             | `master`                                  |\n| `QMK_GIT_URL`                | `https://github.com/qmk/qmk_firmware.git` |\n| `CHIBIOS_GIT_BRANCH`         | `master`                                  |\n| `CHIBIOS_GIT_URL`            | `https://github.com/qmk/ChibiOS`          |\n| `CHIBIOS_CONTRIB_GIT_BRANCH` | `master`                                  |\n| `CHIBIOS_CONTRIB_GIT_URL`    | `https://github.com/qmk/ChibiOS-Contrib`  |\n| `MCUX_SDK_GIT_BRANCH`        | `main`                                    |\n| `MCUX_SDK_GIT_URL`           | `https://github.com/qmk/mcux-sdk`         |\n| `PICOSDK_GIT_BRANCH`         | `master`                                  |\n| `PICOSDK_GIT_URL`            | `https://github.com/qmk/pico-sdk`         |\n| `PRINTF_GIT_BRANCH`          | `master`                                  |\n| `PRINTF_GIT_URL`             | `https://github.com/qmk/printf`           |\n| `LUFA_GIT_BRANCH`            | `master`                                  |\n| `LUFA_GIT_URL`               | `https://github.com/qmk/lufa`             |\n| `VUSB_GIT_BRANCH`            | `master`                                  |\n| `VUSB_GIT_URL`               | `https://github.com/qmk/v-usb`            |\n\n### Populating the API\n\nOne of the key features of the API is the parsing of `qmk_firmware` to build a database about QMK keyboards and keymaps. There are two ways to start this process:\n\n1. `populate_api.sh`: This script will run the update process directly, bypassing the normal infrastructure.\n2. `trigger_update.sh`: This script triggers an update using the same pathway as `qmk_bot`- it sets a flag in redis which is acted upon by `qmk_api_tasks`.\n\nNormally you will want to use method #1. If you need to test method #2 you will also need to start the `qmk_api_tasks` service, which is not started by default.\n\n### Using and Testing the Discord Bot\n\nQMK API uses Discord's webhook API to send messages to `#configurator_log` in our server. If you'd like to use this with your own server you will need to configure a webhook and set that URL here. By default this feature is disabled.\n\n| Variable                      | Default               |\n|-------------------------------|-----------------------|\n| `DISCORD_WEBHOOK_URL`         | *unset*               |\n| `DISCORD_WEBHOOK_INFO_URL`    | `DISCORD_WEBHOOK_URL` |\n| `DISCORD_WEBHOOK_WARNING_URL` | `DISCORD_WEBHOOK_URL` |\n| `DISCORD_WEBHOOK_ERROR_URL`   | `DISCORD_WEBHOOK_URL` |\n\n### API Tasks\n\nThe `qmk_api_tasks` service serves two roles: it continually tests keyboards to ensure they're compatible with Configurator, and it handles routine maintenance such as `qmk_firmware` updates and S3 cleanup. You typically will not need to run this service except for specific purposes, such as working on `qmk_api_tasks` itself or exercising the backend infrastructure.\n\nTo start `qmk_api_tasks`, use the `run_qmk_api_tasks.sh` script:\n\n```sh\n./run_qmk_api_tasks.sh\n```\n\n### Storage Access\n\nWhen running a local copy of Configurator, you'll likely be unable to download firmware or source due to internal Docker hostnames.\n\nThe MinIO web interface is made available at \u003chttp://localhost:9001/\u003e, and for now can be used to manually access the resulting files. You'll need to cross-reference the Configurator's job ID in the build log with the equivalent prefix in the `qmk-api` bucket.\n\nYou can log into MinIO with the `minio` container's root user and password as specified in the `docker-compose.yml` file.\n\n### Storage Cleanup\n\nIf you need to manually clean your S3 storage you can use the `cleanup_storage.sh` script:\n\n```sh\n./cleanup_storage.sh\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqmk%2Fqmk_web_stack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqmk%2Fqmk_web_stack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqmk%2Fqmk_web_stack/lists"}