This project lets any club or organisation run kendo and naginata tournaments at whatever level of digitization fits the venue, from fully printed to fully online. Pick the mode that matches your equipment:
- Offline. No internet required. Runs entirely on printed brackets and score sheets generated as Excel files.
- Partially connected. Internet is available but there are no display screens. Some printed material is still needed for scoreboards and competitors. Keep every shiai-jo in sync either by sharing the Excel file through Google Sheets, or by running the tournament app, with one device per shiai-jo.
- Fully digital. A complete online setup with on-screen scoreboards and mobile result pages. Needs one device per shiai-jo table, a monitor for each court, and network access for competitors. Organisers still print player tags and numbers.
I've been using this application to organise the London Cup since ~2023. It reflects everything I've learned from running real tournaments and the feedback I've received.
For the kendo tournament guidelines this application is based on, see running_a_kendo_tournament.md. Naginata and Engi-kyogi specifics are covered in the Naginata competitions guide.
Full documentation lives on the documentation website. This README is only a quick overview.
The tournament app
The mobile-app command starts the tournament app server: create competitions, import participants, draw pools and brackets, schedule matches across courts, score in real time, and show results on any device (phone, tablet, laptop, or a TV by the court).
Install bracket-creator first. The Docker image starts the server automatically; with a binary install, start it yourself:
bracket-creator mobile-app --folder ./tournament-data
Then open http://localhost:8080 in your browser.
Highlights:
- Admin console (password-protected): competitions, participants, seeding, draws, scheduling, and scoring.
- Public viewer and court displays: real-time schedule, standings, and brackets for spectators, plus big-screen court displays and a transparent overlay for streaming.
- All formats: Knockout, Pools + Knockout, League, and Swiss, for individuals and teams (including kachinuki), plus naginata and Engi-kyogi (kata) competitions.
- Excel export: download the results as a workbook at any point during the event.
Start with these guides on the documentation site:
Excel brackets from the command line
The original core of the project is still there: give it a CSV of participants and it produces fully formatted, print-ready Excel workbooks with pool draws, match schedules, and elimination trees.
# Pools of at least 5 with 3 winners per pool
bracket-creator create-pools -z -p 5 -w 3 -f players.csv -o pools.xlsx
# Straight knockout for teams of 5
bracket-creator create-knockout -t 5 -f teams.csv -o knockout.xlsx
See the docs for the full command references and the input format:
Legacy Web UI
bracket-creator serve starts a browser front-end for the same Excel generators, useful if you prefer a form over CLI flags. It is kept for compatibility; the tournament app above is the recommended way to run an event. See the Legacy Web UI guide.
Install
Docker is the recommended way to run bracket-creator on every platform. Homebrew is the other main option, shown below. Linux packages (.deb, .rpm, .apk), pre-compiled binaries, other methods, and upgrade notes are covered in the install guide.
Pull and run the tournament app image; tournament state lives in the mounted folder:
mkdir -p tournament-data
docker run -p 8080:8080 -v "$PWD/tournament-data:/tournament-data" \
ghcr.io/gitrgoliveira/bracket-creator-mobile:latest
On Linux, also make the folder writable by the container's non-root user before the first run: sudo chown 65534 tournament-data. (Docker Desktop on macOS/Windows handles this automatically.)
Then open http://localhost:8080.
Three image variants are published: bracket-creator-mobile (tournament app), bracket-creator-mobile-pdf (tournament app plus LibreOffice for PDF export), and bracket-creator (the legacy Excel-generator web UI). See the hosting guide for deployment details.
brew tap gitrgoliveira/tap
brew trust gitrgoliveira/tap
brew install bracket-creator
brew trust marks the tap as trusted, which Homebrew requires before installing from a third-party tap. Update later with brew upgrade bracket-creator. The formula (in the gitrgoliveira/homebrew-tap repository) builds from source, so it needs a C toolchain (the Xcode Command Line Tools on macOS or build-essential on Linux) and network access for Go module downloads.
The single binary bundles every subcommand, including bracket-creator serve (web UI) and bracket-creator mobile-app (tournament app).
Contribute to this repository
This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. We appreciate your contribution. Please refer to our contributing guidelines for further information.
License
Copyright © 2023–2026 Ricardo Oliveira <oliveira.rg [at] gmail.com>
This is an independent project created and maintained by Ricardo Oliveira in a
personal capacity: in his own time and on his own equipment. It is not
affiliated with, endorsed by, or owned by any employer, and Ricardo Oliveira is
the sole copyright holder.
This Source Code Form is subject to the terms of the Mozilla Public License,
v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain
one at https://mozilla.org/MPL/2.0/. The full license text is in
LICENSE.
