Docker: a simple workflow for Clojure
Docker enables a consistent approach to building and running Clojure projects along with a range of other services locally (database, cache, streams, etc.), The Clojure project is built from source when starting services (a
watch feature can rebuild on code changes). Heath checks and conditions are set to ensure dependant services start in the correct order.
Running Docker is relatively fast once image overlays (layers) are cached on their first run, so its a viable approach for local system integration testing and acceptance testing, before pushing changes to a remote Continuous Integration service.
A Docker workflow complements a REPL Driven Development workflow, it does not replace it. The main development effort should be more effective via a REPL connected editor with Docker Compose focused on orchestration of services.
Deeper into Docker
Practicalli Engineering Playbook covers Docker and Compose in more detail
- Create a Clojure project, e.g. using Practicalli Project Templates
- Install Docker Desktop & Extensions, e.g. Docker Desktop for Ubuntu
- Create a Dockerfile e.g. multi-stage build and run-time configuration for Clojure
- Compose services together, adding health checks and conditional starts
- REPL driven development, e.g. Practicalli REPL Reloaded Workflow
- (optional) Automatic rebuild of Clojure project when watching for code changes (experimental feature)
Docker getting started tutorial
Follow the Docker getting started tutorial once Docker is installed
Docker desktop provides a convienient way to manage Docker images, containers and volumes. Sign in to Docker Desktop to manage your images on DockerHub.
There is a growing marketplace of extensions that provide very useful tools to extend the capabilities of Docker Desktop. Search within the Docker Desktop extensions or for extensions on Docker Hub.
- Resource Usage monitor resources (cpu, memory, network, disk) used by containers and docker compose systems over time
- Disk Usage optimise use of local disk space by removing unused images, containers and volumes
- Volumes Backup & Share to backup, clone, restore and share Docker volumes easily
- Logs Explorer view all container logs in one place to assist troubleshooting
- Postgres Admin PGAdmin4 open source management tool for Postgres
- Trivy scan local and remote images for security vulnerabilities
- Snyk scan local and remote images for security vulnerabilities
- Ddosify high-performance, open-source and simple load testing tool
Choosing Docker Imagesλ︎
Docker Official Images from Docker Hub are highly recommended. Look for the Docker Official Image tag on the image page.
- Clojure - official Docker Image - built by the Clojure community, provides tools to build Clojure projects (Clojure CLI, Leiningen)
- Eclipse temurin OpenJDK - official Docker image - built by the community - provides the Java run-time
- Amazon Corretto is an OpenJDK distribution by Amazon AWS team, Amazon Corretto can also be installed for the local development environment
- Postgres open-source object-relational database management system
- Redis open-source, networked, in-memory, key-value data store with optional durability
- nginx open source reverse proxy & load balancing for HTTP, HTTPS, SMTP, POP3 & IMAP protocols, HTTP cache and a web server
- mariadb open source relational database by the original developers of MySQL and is much more efficient
Official Docker Image definition
An Official Docker Image means the configuration of that image follows the Docker recommended practices, is well documented and designed for common use cases.
There is no implication at to the correctness of tools, languages or service that image provides, only in the means in which they are provided.
Use Multi-stage Dockerfileλ︎
builder stage and a
final stage used as the run-time. Optionally, the configuration can use a
base stage that defines a common image and configuration which both build and final stages extend.
The builder stage caches dependencies to optimise building Clojure and the run-time stage optimises running the service efficiently and securely.
The uberjar created by the builder image is copied over to the final stage to keep the run-time image as clean and small as possible to minimise resource use.
Docker init feature
docker init is a new (beta) feature to create
compose.yaml files using Docker recommended practices.
compose.yaml file that builds the Clojure project and run services that the Clojure service requires or talks too (database, cache, mock API, etc.). Each service can define a heart beat that can be used as a conditional startup for other services.
compose.yaml new configuration file
compose.yaml is the new configuration file for orchestrating services locally, a simplified and extended version of
build: option for the Clojure service with the path to the multi-stage Dockerfile for the project (typically in the same root directory of the project, although a remote Git repository can also be used)
The Clojure service defines a dependency on a Postgres Database. The dependency has a condition so the Clojure service is only started once the Postgres service is healthy
Clojure and Postgres Composure configuration
ports: # host:container
test: [ "CMD", "pg_isready" ]
Run the services using docker from the root of the project
watch as an experimental feature which can rebuild the Clojure service when a file change is detected. This seems most useful when troubleshooting issues that occur during system integration testing.
x-develop configuration with watch under the Clojure service configuration
Composure x-develop file watch configuration
Start the services and the file watch mode
Save changes to files and a new image for the Clojure service will be built and deployed when ready.
Docker desktop provides lots of tools to support local system integration work before code is sent to a continuous integration service (or as a temporary alternative if that CI service id down)
Practicalli Project Templates include
compose.yaml configurations for Clojure development, kick-starting the use of Docker.
Docker images are a relatively clean way of trying out different services or even different operating systems, e.g. Ubuntu or ArchLinux. Deleting the images removes the whole service without affecting the underlying operating system.
MegaLinter is an excellent example of a docker image that provides a large number of tools that would otherwise need to be installed directly on the operating system.
- Docker Desktop Overview
- Docker Desktop Extensions overview
- Docker Build overview
- Docker Compose Overview