Skip to content

About

ReadingBat Website

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

ReadingBat Site

CI Kotlin JDK Ktor Gradle License GitHub release Docker Pulls Docker Image Size Last commit

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.

Site Content

Code Content Repos

Requirements

  • 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.

Build and run

./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.jar

The app listens on 8080 (HTTP) by default, with additional ports for JMX and metrics — see the Dockerfile for the full list.

Test

./gradlew check              # full verification (tests + lint)
./gradlew test               # tests only

Tests use Kotest StringSpec. Test sources live under src/test/kotlin/com/readingbat/.

Continuous integration

.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.

Lint and format

./gradlew lintKotlin detekt  # static analysis + style check
./gradlew formatKotlin       # apply ktlint fixes

Project 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.

Makefile shortcuts

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 version

Docker

The 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.

Releasing and deploying

  1. Bump version= in gradle.properties.
  2. Bump the pinned image tags in docker-compose.yml and machines/content/run.sh to the new version.
  3. Move [Unreleased] entries in CHANGELOG.md under the new version and add a highlights entry to RELEASE_NOTES.md.
  4. Merge to master and let CI pass, including the Trivy image scan. make release-check lists anything still missing from steps 1–3.
  5. make release to test, then push and verify the Docker image (it asks first).
  6. make deploy to deploy it on Digital Ocean (needs an authenticated doctl). If the release changes a setting, save it in the app first; the runbook in docs/release_notes.md explains why.
  7. Cut a GitHub release: tag X.Y.Z (no v prefix), title vX.Y.Z.

A readingbat-core that isn't on Maven Central

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:

  1. In readingbat-core, check out the tag and run make publish-local, which puts the version in ~/.m2. Gradle looks there for com.readingbat artifacts after Maven Central.
  2. Point readingbat in gradle/libs.versions.toml at 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.

Project conventions

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.

License

Apache License 2.0 — see LICENSE.txt.

About

ReadingBat Website

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages