The deployable content host for readingbat.com. This
repo is intentionally thin: the web server, routing, persistence, and challenge
runtime all live in readingbat-core,
which is consumed here as a binary dependency. What lives in this repo is the
content composition and the deployment plumbing around it.
- Top-level
Content.kt— composes the full site - Java and Kotlin content
- Python content
- JDK 25 (the Gradle toolchain will resolve one via foojay if you don't already have it)
- Docker +
buildx(only needed for releases)
All other versions — Gradle, Kotlin, Ktor, plugins — are pinned in
gradle/libs.versions.toml.
./gradlew run # run the app locally
./gradlew build -x test # build without tests
./gradlew buildFatJar # produce build/libs/server.jar
java -jar build/libs/server.jarThe app listens on 8080 (HTTP) by default, with additional ports for JMX and
metrics — see the Dockerfile for the full list.
./gradlew check # full verification (tests + lint)
./gradlew test # tests onlyTests use Kotest StringSpec. Test sources live under
src/test/kotlin/com/readingbat/.
.github/workflows/ci.yml runs on every push and pull
request against master. It builds, tests, and lints on JDK 25 (Temurin) with a
single ./gradlew build — detekt and lintKotlin both attach to check, so
that one command is the same verification you get locally. Its actions are pinned
to commit SHAs, which Dependabot bumps weekly.
.github/workflows/security.yml builds the image
and scans it with Trivy on the same events and weekly, because a
newly published CVE can affect code that hasn't changed. It fails on a HIGH or CRITICAL
vulnerability that has a fix, and make release-check requires it to have passed.
./gradlew lintKotlin detekt # static analysis + style check
./gradlew formatKotlin # apply ktlint fixesProject formatting rules are in .editorconfig. Line endings are
normalized by .gitattributes: text files are stored and checked
out with LF (*.bat is the sole CRLF exception), so gradlew and the machines/
shell scripts stay runnable on Linux and in Docker regardless of your
core.autocrlf setting.
Most common workflows have a make target. Run make help for the full list:
make build # build (no tests)
make tests # full test suite (always reruns the tests)
make lint # lintKotlin + detekt
make format # apply formatting
make uberjar # build the fat jar
make run-uber # run the fat jar
make docker-build # build the image for this machine into local Docker (readingbat:local)
make docker-scan # docker-build, then list the image's CVEs with Docker Scout
make release-check # check the checkout is fit to release (pushes nothing)
make release # gate + test, then push and verify the multi-arch image
make deploy # deploy :latest to Digital Ocean, pulling it again (doctl; checks it is VERSION)
make logs # follow the Digital Ocean app's runtime log (doctl)
make upgrade-wrapper # bump the Gradle wrapper to the catalog-pinned versionThe image is built from eclipse-temurin:25-jdk-alpine, pinned by digest (Dependabot
proposes digest bumps), runs as a non-root readingbat user that can write only to
/app/dumps, and declares a HEALTHCHECK on /ping (on $PORT when set). make release
publishes a multi-arch (linux/amd64,linux/arm64) image to
pambrose/readingbat:{latest,$VERSION}. To check an image before releasing it,
make docker-scan builds one locally (readingbat:local, never pushed) and lists its
CVEs with Docker Scout. That includes the libraries inside server.jar, which a scan of the
base image can't see. CI also scans the built image, with Trivy, so the two can report
different results (see Continuous integration).
The Prometheus JMX exporter agent is vendored in jmx/ and named in the Dockerfile's
ENTRYPOINT. make versions does not see it, so check the
jmx_exporter releases when refreshing
dependencies.
A multi-instance local composition is provided in
docker-compose.yml.
The image sets JAVA_TOOL_OPTIONS to write a heap dump on OutOfMemoryError, into
/app/dumps, and then to exit, so the restart policy replaces a JVM that may have lost a
thread to the OOM rather than leaving it serving traffic. Each composed service gets its own
named volume at /app/dumps. Two reasons it is a named volume rather than a bind mount:
Docker creates a missing bind-mount directory as root while the container runs as uid 1000,
so the JVM could not write the dump, whereas a named volume is initialized from the image's
own /app/dumps and inherits its readingbat ownership. And one volume per service, because
each container is pid 1 in its own namespace, so every dump is named java_pid1.hprof, and
the JVM will not overwrite an existing one — on a shared volume only the first OOM in any of
the three would leave a dump.
Retrieve a dump with the command below. It moves the file off the volume rather than copying
it; a java_pid1.hprof left behind means the next OOM writes no dump at all.
docker run --rm -v readingbat-site_readingbat0-dumps:/dumps -v "$PWD":/out \
alpine mv /dumps/java_pid1.hprof /out/Two things to know. A dump is roughly the size of the live heap, and MaxRAMPercentage=75
allows that to be most of the machine's RAM — keep an eye on disk. And a dump is a copy of
live memory: it contains session secrets, database credentials and user data, so treat the
file itself as a secret. Setting JAVA_TOOL_OPTIONS in docker_env_vars overrides the image
default, since env_file wins over ENV.
- Bump
version=ingradle.properties. - Bump the pinned image tags in
docker-compose.ymlandmachines/content/run.shto the new version. - Move
[Unreleased]entries inCHANGELOG.mdunder the new version and add a highlights entry toRELEASE_NOTES.md. - Merge to
masterand let CI pass, including the Trivy image scan.make release-checklists anything still missing from steps 1–3. make releaseto test, then push and verify the Docker image (it asks first).make deployto deploy it on Digital Ocean (needs an authenticateddoctl). If the release changes a setting, save it in the app first; the runbook indocs/release_notes.mdexplains why.- Cut a GitHub release: tag
X.Y.Z(novprefix), titlevX.Y.Z.
The site can depend on a readingbat-core version that was never published to
Maven Central, as long as it is a tag in readingbat-core:
- In
readingbat-core, check out the tag and runmake publish-local, which puts the version in~/.m2. Gradle looks there forcom.readingbatartifacts after Maven Central. - Point
readingbatingradle/libs.versions.tomlat that version.
CI finds the version missing from Central, builds it from its tag, and tests
the site against that build. make release-check refuses a version that is
neither on Central nor tagged, or that is missing from ~/.m2. The image is
built from your ~/.m2 copy, so publish it from the tag itself.
See CLAUDE.md for repo conventions (version-catalog discipline,
configuration-cache safety, shadowJar duplicate handling, and the gotchas that
the code alone won't teach you) — useful for both humans and AI coding agents.
Apache License 2.0 — see LICENSE.txt.