code.golf: the Go site that runs submitted programs in per-language containers

What the repository is: the engine behind a public leaderboard

The README opens with one line of purpose: this is the repository behind the website and community at code.golf. The project is described as a game designed to let you show off your code-fu by solving problems in the least number of characters. That framing matters for how the code is organised, because the site is not a general purpose sandbox. It is a scoring system, and the scoring system is the product. The repository is written in Go with a TypeScript front end, and the top level directory listing shows the shape of it: hole/ for the challenges, langs/ and latest-langs for the language definitions, golfer/ for accounts, session/, oauth/, routes/, views/, db/ and sql/ for persistence, and a discord/ directory for the community integration. The licence is MIT and there are no GitHub releases, so the deployment story is the repository plus the containers rather than a versioned binary.

Local setup in seven steps, and step two is a certificate

The quickstart lists the dependencies first, which are Docker, Docker Compose, Go, make, mkcert, and npm. The second step is the one people miss: make cert installs a local certificate authority, and the output in the README shows mkcert creating a certificate valid for localhost, writing the certificate to ./localhost.pem and the key to ./localhost-key.pem, and installing the CA into the system trust store and the browser trust store. That is because the site is served over HTTPS on port 443, so without a trusted local certificate the browser refuses the connection. The Makefile shows what the cert target does, calling mkcert with the install flag for localhost and then making the key readable. The remaining steps are npm install for the packages, make dev to bring the site up, an optional go run of a utility to load information from the code.golf database, and finally opening https://localhost. There is also a local login shortcut, a callback URL with a username parameter that lets you sign in as an arbitrary user, which the README says can show data fetched in the previous step.

$ make cert
$ npm install
$ make dev
$ go run utils/update_sql_from_api.go

Docker Compose is the runtime, and the Makefile hides the file layout

The Makefile exports two environment variables that tell the reader how the compose setup is organised: COMPOSE_PATH_SEPARATOR is set to a colon and COMPOSE_FILE is set to docker/core.yml:docker/dev.yml, so the development stack is the core compose file layered with the dev one. The dev target touches docker/.env, removes any existing containers with docker compose rm -f, and then runs docker compose up --build. The database is part of that stack, since the db-dev target runs a psql session inside it with docker compose exec db psql -U postgres code-golf, and the db-diff target compares a dump from the live server with a dump from the local container, using pg_dump with the restrict-key option on both sides. The database itself is PostgreSQL, and the Go dependency list carries the lib/pq driver and the vinovest/sqlx wrapper, with DATA-DOG's go-sqlmock for mocking queries in tests.

The arm64 problem: some languages run, the rest need rebuilding

The README has a section dedicated to arm64 and aarch64 machines such as Apple Silicon, and it is the most practically useful part of the document. The options offered are to attempt QEMU emulation, which Docker Desktop supports but which may be slower, or to accept the default, where make dev builds the docker images with arm64 architecture. From there comes the catch. Some languages can run the example code without rebuilding individual docker containers, and the list names AWK, Bash, Berry, Lua, Perl, PHP, Python, Raku, Ruby, sed, SQL and Wren. For everything else you need to build locally, and the command given is ./build-langs --no-push C Go JavaScript. If you skip that, the README shows the failure you will get, an assertion that Unable to open /proc/sys/vm/mmap_min_addr, followed by a trace or breakpoint trap signal. That error is cryptic, and the section exists because it is common enough to be worth documenting before you lose an afternoon to it.

The TypeScript front end is transpiled by esbuild, not bundled by a framework

The js/ directory holds the TypeScript files, which are transpiled by esbuild into JavaScript files for serving, and .tsx files can additionally use JSX. The package.json is a manifest of what the front end actually needs, and the list of CodeMirror packages is a good map of the languages the site can display. There is a mode for C++, Go, Java, JavaScript, PHP, Python, Rust and SQL, legacy modes, the Exercism modes for Gleam and Wren with the Wren one pinned to a specific git commit, and dedicated modes for Brainfuck, Elixir, Golfscript, J, Janet, jq, K, Knight and Prolog, plus a Zig mode, the Vim mode from Replit, and the one-dark theme. Other dependencies reveal the app's shape: golden-layout for the pane system, chart.js with the luxon adapter for the statistics graphs, mathjax for rendering, diff for comparing solutions, lz-string for compressing state, and style-mod for the theme switching.

Scoring, ranking and the style rules the URLs follow

The Style section of the README is short and it is where the site's conventions are written down, which is the kind of thing you need before changing anything. URL slugs are consistently abbreviated, with cheevos, langs and stats given as examples, while page titles are not abbreviated, with Achievements, Languages and Statistics given as the counter-example. Paginated URLs carry a trailing number, but only on pages after the first, so /rankings/medals/overall/all/all/all is the first page and /rankings/medals/overall/all/all/all/2 is the second. The go.mod dependency list explains the machinery behind the rankings: agnivade/levenshtein for string distance, the oddg hungarian-algorithm package for assignment problems, which is how you would solve a matching problem like which submissions belong in which slot, and shurcooL/graphql for the GraphQL API, with a validator link in the README to check the API definition.

Tests, linting and the ancillary Raku scripts

There are two test levels and a note that changes the meaning of the second one. The unit tests run with make test, and the end to end tests run with make e2e, but the README warns that any changes to the languages need to be re-built with build-langs before the end to end tests will pick up the changes. In other words, the language images are build artefacts that the test suite does not rebuild for you, and a language change that is not rebuilt will simply not be tested. The Makefile also has an e2e-iterate target for rerunning after a small change, with a comment explaining that logs are not shown automatically on failure because that makes the test results harder to read and the target is not used by CI. Linting is a single make lint command that lints the TypeScript code and then the Go code, and the README adds the ESLint configuration for Visual Studio Code, with eslint.validate set for typescript and typescriptreact and the ESLint extension as the default formatter. A separate Hacking section notes that some ancillary scripts are written in Raku and need a recent Raku install with Zef used to install the dependencies.

Vagrant as the shortcut past the dependency list

The Vagrant section exists so that you can skip the dependency list. With Vagrant and VirtualBox installed, one command creates a virtual machine with Docker, Docker Compose, Go, Raku and the zef dependencies, and npm all preinstalled, forwarding port 443 so the site is reachable over HTTPS. The setup requires checking out a dedicated branch, utils/vagrant-bootstrap, with the command shown being a git config change for core.autocrlf followed by a checkout of that branch and vagrant up. Certificate installation then needs a small decision: the README says to run make cert outside the virtual machine if possible, because that installs the certificate in your browser, and gives the alternative of running the command in a virtual machine shell with vagrant ssh and then installing the certificates manually. The rest mirrors the quickstart, with the site brought up by running make dev through vagrant ssh.

Editorial conclusion

The code.golf repository suits a developer who wants to run a code golf leaderboard locally, contribute a language implementation, or study how a site scores and ranks golfed solutions, and who is comfortable with Docker Compose, a local certificate authority and PostgreSQL. It is the wrong tool for a team that needs a general purpose code execution sandbox, because the container images are built per language with a bespoke build-langs script, and a poor fit for a machine that cannot run Docker at all. Before you start, read the arm64 section of the README, because on Apple Silicon the default builds are arm64 and several languages run without rebuilding while the rest need ./build-langs, and remember that changes to the language definitions are invisible to the end to end tests until build-langs has been run.

Frequently asked questions

Official sources

1. code-golf/code-golf on GitHub
2. Issues
3. License: MIT
4. Project website
5. README