Support Server

Create file (or append to): ~/.gradle/gradle.properties, the following:

triplea_github_username=CHANGE_ME
triplea_github_access.token=CHANGE_ME

Tech Overview

• Java 25
• Quarkus (http server)
• Junit5 (unit tests)
• assertj (unit tests)
• JDBI (no ORM, JDBI instead)
• Postgres (database layer)
• Docker & Docker Compose
• gradle (build tool)
• just (developer build commands)

Development

If working on shared code between triplea and support-server, see: just build-with-libs. Warning: First make sure that the local triplea project can build cleanly.

• Run just for list of full commands
• just check will verify formatting and run all tests (unit+integ); just format fixes formatting

Integration Tests

These are tests that run against a live database. They use @QuarkusTest, which starts the Quarkus application in-process - no separately managed server is needed. Quarkus Dev Services automatically starts a disposable Postgres container (via Testcontainers) and runs Flyway migrations, so there is no manual database setup step.

Run the tests with:

./gradlew check

Or use just check, the same command CI runs.

Deployment

Output Artifacts

'Application' Docker image for running the support-server application. Flyway database migrations are bundled into the application and run automatically on startup.

Database migrations

Every migration must be backward compatible with the previous release's code. Rolling back redeploys the previous image against the already-migrated database, and that release must still start and work (Flyway is configured to ignore the newer, unknown migrations rather than fail). In practice:

• Migrations are additive: new tables, new nullable or defaulted columns, new indexes.
• Drop or rename a column or table only in the release after the code stops using it.

CI/CD

On merge to main:

• builds a new docker image & publishes the new image to Github Packages

See:

• .github/workflows/main.yml

Map Indexing Overview

Maps are stored, one each, as a repository in the github organization: triplea-maps

The server keeps a database of all maps. For each map, we store the following data:

(1) repository URL. EG: https://github.com/triplea-maps/test-map

The server gets the list of all repositories from github's web API, so we can automatically get this list from github.

(2) map name. Read from the 'map.yml' file in the repository, 'map_name' attribute.

EG: https://github.com/triplea-maps/test-map/blob/master/map.yml

(3) preview image URL. We simply assume this file is named 'preview.png'

(4) description. We assume this data will be contained in a file 'description.html'

EG: https://github.com/triplea-maps/test-map/blob/master/description.html

(5) version. The server can store a version number for each map starting at 'one'. The server can also obtain from github the last time a repository was updated. Whenever this 'last updated' timestamp updates, we can update the version number of the map. So this is fully automated.

(6) download size. Whenever a map repository changes, the server can actually physically downoad the map file and determine the size. The download size is stored in database, and can be returned as part of the 'list-maps' payload to clients.

Maps System Design

Key Classes

• MapIndexer: fetches all the data of a given map, creates a MapIndexingResult
• MapIndexingResult: represents all desired data of a parsed map, eg: map name, download size, description
• MapIndexDao: upserts MapIndexingResult into database