tamizhvendan / startrek

A very simple demonstration of coding a reasonably simple API and UI using Clojure, Donut System, i18n support, error handling, HTMX and tests!

Star Trek Clojure Project

Table of Contents

• 1. Introduction
• 2. Features
  • 2.1. Star Trek
  • 2.2. Engage!
    • 2.2.1. Option 1
    • 2.2.2. Option 2
    • 2.2.3. Option 3
• 3. Interrogating the API
• 4. Logging in via the UI
• 5. License
• 6. Feedback
• 7. Finally!

1. Introduction

This is a very small, yet surprisingly complete, example of using Clojure to serve up a RESTful API and to provide a user interface using Thymeleaf and HTMX. It uses a variety of technologies to demonstrate how this is possible. The project offers a full API CRUD (Create, Read, Update and Delete) experience over some Star Trek starships!

2. Features

• API CRUD Functionality

• Login and view for the UI (Delete and Create/Update coming soon!)

• Exception Handling (both RESTful and for the UI)

• Internationalisation (i18n)

• Swagger API

• Input Validation (using Malli)

• Thymeleaf to render webpages

• HTMX to provide user interaction via the UI.

2.1. Star Trek

This backend is written in Clojure and uses a PostgreSQL database to store a list of starships. The technologies in play include:

• reitit

• next-jdbc

• honeysql

• donut.system

• juxt aero

• flyway database migration

• babashka (for some gentle scripting)

The frontend is rendered using:

• thymeleaf

• htmx

Additionally:

• Uses a dynamic (repl-friendly) reitit dev workflow

• Also includes tests (including transactional rollbacks per test)!

A full list of the technologies that are used can be found in the deps.edn file.

This service also exposes Prometheus metrics AND a JMX endpoint for your enjoyment!

2.2. Engage!

❗	If you want to use the supplied Justfile, you’ll need to have just installed.

There are at least 3 ways to launch this project:

❗	You need to have the database and cache services running first (in a separate terminal). The command to do this, if you have just installed is just up, or if you don’t have just installed, you can do docker compose -f scripts/docker/docker-compose-services.yml up

Now, then for the first option:

2.2.1. Option 1

❗	You need to copy the resources/config/config-example.edn to resources/config/config-local.edn and modify, for example, if you are connecting to your own PostgreSQL instance.

Fire up your repl using:

• clj -M:dev

to load up the dev alias defined in the deps.edn then

• (dev/go)

to start the system.

2.2.2. Option 2

❗	You need to copy the resources/config/config-example.edn to resources/config/config-local.edn and modify, for example, if you are connecting to your own PostgreSQL instance.

• just run-local

or

• bin/build

• bin/run-local

2.2.3. Option 3

❗	You don’t need to copy any config file, as the docker container is configured to use config/config-example.edn, and thus this is the one by the application.

• just run-docker

or

• bin/build

• bin/run-docker

3. Interrogating the API

Once the service is up and running (and listening by default on port 8080), there are a few examples of interrogating the API to pull back some data. The scripts can be found in scripts/bb.

❗	You will need Babashka installed.

To run a script just execute them on the command line, i.e., ./find-all-starships.clj

If you have jet installed, you can convert the EDN response to JSON like so:

./find-all-starships.clj | jet -o json

4. Logging in via the UI

Open up a browser and visit http://localhost:8080/ From that page, click on the login link. The username and password has been pre-filled in for you.

5. License

Find the full unlicense in the UNLICENSE (and LICENSE) file, but here’s a snippet:

This is free and unencumbered software released into the public domain.

Anyone is free to copy, modify, publish, use, compile, sell, or
distribute this software, either in source code form or as a compiled
binary, for any purpose, commercial or non-commercial, and by any
means.

6. Feedback

I welcome feedback. I can usually be found hanging out in the #clojure-uk or #clojure-europe channels on Clojurians Slack. You can also email me if you wish :-)

7. Finally!

Live Long and Prosper!