Getting started

This chapter says what OpenPairings is, how to install and start it, and how the program is laid out. The other chapters follow the order in which an arbiter works: set up the tournament, enter the players, pair a round, enter the results, print, report.

What the program does#

OpenPairings runs a chess tournament from its set-up to the report for the rating office:

• It pairs Swiss tournaments (FIDE Dutch system, C.04.3), Swiss team tournaments (C.04.6), round robins (Berger tables, C.05) and Keizer tournaments.
• It keeps the players, the results, the byes and the standings, with the tie-breaks of FIDE's C.07.
• It prints the lists an arbiter needs (pairings, standings, result cards, cross tables, player cards, place cards).
• It reads and writes the FIDE report file (TRF26, TRF16), and reads SWAR files.
• It can publish a tournament to a public results site (OpenResults) so that players and spectators follow the event on their phones.

Two ways to run it#

On your own computer (the desktop build). A single person uses the program on one computer. There is no log-in: the program starts, opens your web browser on http://localhost:4000 and you are signed in as the owner of that computer. Your tournaments are stored on that computer. The program can only be reached from that computer, never from the network.

On a server (the online build). The program runs on a server and you reach it through a web address. Everyone has an account, every tournament belongs to its owner, and the owner can invite other arbiters to share it (see Accounts, sharing and hand-off).

Everything described in this manual works in both. The differences are mentioned where they matter: log-in and accounts exist only online; the update notice, the data folder and the "local view" of the live page belong to the desktop build.

Installing the desktop build#

Download the release for your system from the project's release page.

Windows. The .msi file is the recommended download. It shows an installer with a welcome page, the licence, and the choice between installing for yourself only (no administrator needed) or for everybody on the computer. The Setup.exe next to it installs for yourself at once, without questions. After installing, start OpenPairings from the Start menu. A small window opens and your browser follows; closing that small window stops the program.

Linux. Download the portable archive and unzip it. Run ./openpairings.sh (the file must be made executable once: chmod +x openpairings.sh). The program opens your browser.

macOS. Download openpairings_app_macos_aarch64.zip for a Mac with an Apple chip (M1 and later; macOS 11 or newer), or openpairings_app_macos_x86_64.zip for a Mac with an Intel processor (macOS 10.13 or newer), open it, and drag OpenPairings into Applications. The app is not yet signed by Apple, so the first time macOS refuses to open it: open System Settings, Privacy & Security, scroll down and click Open Anyway beside the message about OpenPairings (on macOS 14 or older: right-click the app and choose Open). After that it opens like any other app, with an icon in the Dock (right-click it and choose Options, Keep in Dock to keep it there). A small window says that OpenPairings is running and your browser follows. You can close that window: OpenPairings keeps running, and clicking its Dock icon brings the window back. Stop OpenPairings in the window, or quitting the app (Cmd-Q, or Quit on the Dock icon), stops the program; your tournaments stay saved. To update, quit it, download the new zip and replace the app in Applications.

No Java and no database server are needed. The Swiss pairing engine (Ainalrami) is part of the program (see Pairing a round).

Where your data is#

The tournaments are one database file in a folder of your user account:

• Windows: %LOCALAPPDATA%\OpenPairingsData; backups in %LOCALAPPDATA%\OpenPairingsBackups.
• macOS: ~/Library/Application Support/OpenPairings.
• Linux: ~/.local/share/OpenPairings.

The program writes a backup of its data about once a day (see "Backups" in Accounts, sharing and hand-off).

Updates#

A desktop copy checks, on start and every few hours, whether a newer release exists, and shows a notice at the top of the page.

On a per-user Windows installation the notice has an Install and restart button; on the other installations it links to the release page. The check can be switched off on the Connections page.

Details: what the program is doing#

When something seems slow or odd and you want to say what, click Details in the small window (Windows) or on the Mac (a window of its own opens). On Windows the window grows downwards and shows the program's own output (the end of launcher.log, refreshed every second) and a few numbers about the running program: version, how long it has run, how busy the processor is, memory, and how long the database takes to answer. Copy puts the numbers and the last 200 lines of the log on the clipboard, ready to paste into a mail; Open log folder shows the file itself. On the Mac the log is logs/server.log in the data folder. The numbers read "—" until the program has started.

On Linux the same is a command in the folder you unzipped: ./openpairings.sh details refreshes every two seconds (press q to stop), ./openpairings.sh details --once prints it once, for pasting.

The first start#

Open the program. The first page is Tournaments: the list of your tournaments (empty at first), with New tournament and the import buttons.

On a phone-width screen the list becomes one card per tournament, with the status on its own line and the More menu in the corner; on a wider screen it is a table.

The bar at the top of every page has:

• Tournaments - the list of your tournaments. Inside a tournament this first tab reads Home instead and leads to the same list.
• Tools - the public arbiter tools (norm reports from uploaded files).
• Changelog - what changed in each release.
• Help - this manual. Inside a tournament it opens at the chapter that matches the page you are on.
• The colour accent, the language picker (English and Dutch) and the theme (System, Light, Dark, Slate, Paper, Board, Tom W, High Contrast, and any theme packs installed - see Custom themes).
• The account menu, with Settings (online), Features and Log out (online), and the version number.

Inside a tournament the bar shows the tournament's own tabs:

Connections (the rating lists, backups, publishing address) appears in the bar on the Tournaments page, for the administrator of the installation. On a desktop build that is always you.

A first tournament in short#

1. Tournaments, New tournament: name, pairing system, rounds, place, start date, rate of play. Create tournament.
2. Settings, Dates: enter a date for every round (no round can be paired until every round has a date).
3. Settings, Tie-breaks and Tournament: check the tie-breaks and the officials.
4. Players: add the players (search the FIDE list or type them in).
5. Pairings: Pair round 1.
6. Enter the results on the Pairings page. When every board has a result, On to round N opens the next round: pair it.
7. Standings, Print whenever needed.
8. After the last round: Settings, Export, send the TRF file to the rating office (see Sending to FIDE).

The following chapters explain each step in full.

Language#

The page around the manual, and the whole program, is available in English and Dutch (picker in the top bar; online, the choice follows your account). This manual exists in English and Dutch and follows the language you pick.

Keyboard and accessibility#

Every action is a button or a link and can be reached with the keyboard. Result entry is designed for the keyboard (see Results): click the result field of the first board, then type 1 for a win for White,

walk through the other values. The player grid has its own key controls (see Players and rating lists): Ctrl+I adds a player, the arrow keys move between the cells, Space or

The program follows the colour scheme you choose: System follows the computer's light or dark setting, and the theme picker also offers Light, Dark, Slate, Paper, Board, Tom W (royal blue with a sky-blue accent) and High Contrast, followed by any theme packs that are installed. The live page has a high-contrast mode of its own.

Custom themes#

Themes beyond the built-in ones come as theme packs: a folder with a stylesheet in it. None is installed by default. An installed pack appears in the theme picker after the built-in themes, with its colours beside its name; choose it like any other theme. If the pack is removed later, whoever had chosen it is quietly put back on System.

Where packs go#

On the desktop build, in a folder called themes inside the data folder (see Where your data is), one folder per pack:

• Windows: %LOCALAPPDATA%\OpenPairingsData\themes
• macOS: ~/Library/Application Support/OpenPairings/themes
• Linux: ~/.local/share/OpenPairings/themes

Create the themes folder if it is not there. The program reads it when a page opens, so a new pack shows up on the next page without a restart.

Online, you cannot install a pack yourself: the server reads its packs from a folder its operator chooses (PAIRINGS_THEMES_DIR). Ask the operator.

What a pack contains#

A folder named after the pack's id (lowercase letters, digits and dashes), holding:

• theme.json - id (the folder's name), name (as shown in the picker; at most 40 characters), optionally name_nl (the Dutch name), author, version, dark (true when the text on the pack's surfaces is light, so the program draws its own marks for a dark background) and swatch (three or four colours as #rrggbb, the preview in the picker), and optionally users: a list of email addresses. Then the pack exists for those accounts only; anyone not on the list, or not signed in, does not see it in the picker and cannot choose it.
• theme.css - the stylesheet, at most 200 KB.
• optionally fonts/, with fonts as .woff2 files (at most 1 MB each, names of lowercase letters, digits, - and _), and a licence or read-me file.

A theme is mostly a set of colour tokens in a block [data-theme="<id>"] { ... }. The tokens are: --bg (the page), --surface (cards), --surface-alt (striped rows), --surface-hover, --border, --text, --text-soft, --accent, --accent-hover, --accent-soft, --accent-ink (text on the accent), --accent-lift, --danger, --danger-hover, --danger-ink, --success, --success-soft, --warn, --warn-soft, --info, --info-soft, --shadow, --scrim (behind a dialog), --radius, and the sign-in panel's --hero-a, --hero-b, --hero-c, --hero-ink and --hero-pole. A token the pack leaves out keeps the Light theme's value. A pack may also set its own accent colours with [data-accent="blue"]:where([data-theme="<id>"]) { ... }.

What a pack may not do#

The program refuses a pack, and says why under the themes in the picker, if its stylesheet:

• uses @import, or any other @-rule than @font-face, @keyframes, @media and @supports;
• refers to any address other than its own fonts/<name>.woff2 with url(), or uses image-set() and the like;
• contains expression(, javascript:, behavior: or -moz-binding;
• has a rule that does not start from [data-theme="<id>"] (also allowed: :root[data-theme="<id>"], html[data-theme="<id>"], and the accent form above), nests one rule inside another, or uses a backslash outside a string.

The stylesheet and fonts are served by the program itself; a pack cannot load anything from elsewhere.

Checking a pack#

From a copy of the program's source, mix pairings.theme_check PATH runs the same safety check and then measures the pack's colours against the contrast rules the built-in themes are held to, in every accent colour, and lists every pair of colours that is too hard to read. A pack that fails this check still loads; it is just hard on the eyes of whoever has to use it.