After the trials and tribulations of my last post, this one was somewhat simpler. The last item on the checklist is "turn on all error messages". In Code That Fits in Your Head the author presents 2 primary ways ... turning warnings into errors and using analysers, such as linters and code formatters.
Since Clojure is a dynamic language it doesn't really have the concept of compilation warnings that can be turned into errors. So while there aren't any errors I could turn on it's generally considered good practice to be warned about,
and remediate, the use of reflection. Reflection is generally a slow process in the JVM, so I want to avoid it when I can. I added the following s-expression to my dev/user.clj file.
(alter-var-root #'*warn-on-reflection* (constantly true))
Now, whenever I'm developing and the JVM needs to perform reflection I'll be warned about it and can add the appropriate type hints to avoid performing reflection. The only slight annoyance here is that it looks like nrepl, which my editor uses, uses reflection and so I get a few warnings when I start my REPL.
The Clojure ecosystem comes with a multitude code formatters and linters. For this project I chose to use cljfmt to format my code and clj-kondo, eastwood and splint for linting. In general, I prefer these to be integrated into my editor to provide the fastest possible feedback loop as well as in my CI/CD pipeline to ensure consistency as my code base evolves.
Code formatting can be a bit of a touchy subject. Some engineers prefer to trade off the consistency of automated code formatting for the freedom to express themselves as they wish. Personally I like to have some sensible defaults and then forget about code formatting. When writing Clojure my editor of choice is Intellij Idea with the Cursive plugin. Cursive has its own opinions on code formatting. They're a bit different to the Clojure style guide, but I've happily working with them for the last few years. Selecting the option to "format on save" and I pretty much never have to think about code formatting.
Even though this seems pretty safe, I do like to have a check in my CI/CD pipelines. While there are several code formatting options, I went with cljfmt simply because it has an option to match the Cursive formatting style. To do this I created a .cljfmt.clj file in the root of the project and added the following
{:function-arguments-indentation :cursive
:sort-ns-references? true}
Since Cursive includes references in alphabetical order when it automatically imports them I added a check for this for those occasions when I have to add references by hand.
To run cljfmt during CI/CD I included it from setup-clojure and ran it in its own step.
...
- name: Install clojure tools
uses: DeLaGuardo/setup-clojure@12.5
with:
...
cljfmt: 0.12.0
...
- name: Check formatting
run: cljfmt check deps.edn src dev infra
...
Again, there are several linters in the Clojure ecosystem and in this case I tend to find it's a case of the more, the merrier. As long as they are decently configurable.
The OG of Clojure linters and it's able to be integrated into my editor using the Clojure Extras plugin.
Unfortunately neither of these linters are able to be integrated into Cursive. The best way I could think to add them to my workflow was to create a script that calls them (as well as clj-kondo and cljfmt) that I could run by hand. I run this script just before every commit I make. I created the script, verify.sh and placed it in the dev folder. Due to the build alias having a :paths key rather than :extra-paths it's not possible to run the Clojure CLI tool over the entire code base in one pass. I broke linting into "application" (including dev) and "infrastructure" linting. clj-kondo and cljfmt are both available as pre-built binaries, which allows them to start up much faster than when they are run by the Clojure CLI. This script assumes they are both available on the users' path.
#!/usr/bin/env bash
set -e
clj-kondo --lint deps.edn src dev infra
clojure -M:dev:linters -m eastwood.lint
clojure -M:dev:linters -m noahtheduke.splint
clojure -M:build:linters -m eastwood.lint
clojure -M:build:linters -m noahtheduke.splint
cljfmt check deps.edn src dev infra
splint did pick up on the fact that restaurant.clj is a single segment namespace. This means that that namespace can't be called by any other Java package. Since I intend (and, yeah, this is likely to come back and bite me) for this only to be used as an application and never as a library I created a splint.edn configuration file in the root of the project and removed the warning.
{naming/single-segment-namespace {:enabled false}}
Having fixed that issue, I configured my CI/CD pipeline in a similar manner to the verify.sh script above.
...
- name: Install clojure tools
uses: DeLaGuardo/setup-clojure@12.5
with:
...
clj-kondo: 2024.08.01
...
- name: Lint application
run: |
clj-kondo --lint deps.edn src dev
clojure -M:dev:test:linters -m eastwood.lint
clojure -M:dev:test:linters -m noahtheduke.splint
- name: Lint infrastructure
run: |
clj-kondo --lint infra
clojure -M:build:linters -m eastwood.lint
clojure -M:build:linters -m noahtheduke.splint
...
Now every change that is pushed to main is linted and checked for correct formatting.
In this post I described the guardrails, linters and code formatter, I put in place to keep my code tidy, idiomatic and to reduce the likelihood of bugs. I also talked about the development time settings I use to keep my code performant.
Next time there'll hopefully be a bit more application development and a little less yak shaving as I'll be building the first vertical slice of the restaurant reservation system. See you then. If you've got comments or questions feel free to reach out via Twitter/X (linked above) or on the Clojurians Slack channel.
Previous: 6 months, 1 line of code
Published: 2024-08-10
Tagged: clojure restaurant
So it's been somewhat longer than I'd hoped. After the first blog post in this series I started on the second item in the checklist, "Automate the build". And that's where I got suited up and blasted off as a fully fledged architecture astronaut.
Everything started off reasonably sensibly. Since I'm using Clojure's deps system to configure my application it made sense to use the tools.build library to build an UberJAR for the service. Because of the simplicity of the application, so far, it was basically a copy-&-paste job of the tools.build example.
The first step was to create a :build alias in my deps.edn file to manage the build.
{...
:aliases {...
:build {:paths ["infra"]
:deps {io.github.clojure/tools.build {:mvn/version "0.9.6"}}
:ns-default build}}}
I like to keep all my infrastructure/configuration away from the rest of my code, so I created an infra directory and I created a build.clj file to house the build code.
restaurant
...
├── infra
│ └── build.clj
...
I then copied the example build namespace from the guide. Including the build number in the file name of the JAR makes life a little more complicated later, so I removed it and tided up the rest of the file.
(ns build
(:require [clojure.tools.build.api :as b]))
(def target-dir "target")
(def class-dir (format "%s/classes" target-dir))
;; delay to defer side effects (artifact downloads)
(def basis (delay (b/create-basis {:project "deps.edn"})))
(defn clean [_]
(b/delete {:path target-dir}))
(defn uber [_]
(clean nil)
(b/copy-dir {:src-dirs ["src"]
:target-dir class-dir})
(b/compile-clj {:basis @basis
:class-dir class-dir})
(b/uber {:class-dir class-dir
:uber-file (format "%s/restaurant.jar" target-dir)
:basis @basis
:main 'restaurant}))
This allowed me to create the UberJAR from either the REPL (as long as it's started with the build alias)
(build/uber nil)
or the command line.
clojure -X:build uber
Both of those commands creates the UberJAR at target/restaurant.jar.
I was now able to run the application UberJAR from the command line
sudo java -jar target/restaurant.jar
and then check that it worked using curl (or your web browser of choice)
$ curl localhost
Hello World!
I had recently come across Large Scale Software Development (and a big trap) by the YouTube channel Code to the Moon that nicely encapsulates the architecture I wanted to use. Essentially, I wanted to architect the service as a stateless monolith that is run behind a load balancer. This allows for fairly straight forward scaling (both horizontally and vertically) and downtimeless deployments, two things that modern software engineering embraces. In my experience this is a suitable architecture for the vast majority of projects to begin with, and for a lot will be all the architecture that will ever be needed.
"All" I wanted was somewhere I could deploy my service that
Because I'm a developer most of the time my ops skills are a gaping chasm of desirability. Could I learn to cobble together something in AWS, GCP or Azure, probably? Could I do something similar in kubernetes (or k8s or whatever it's called), it's probably not beyond me? Did I want to spend a bunch of time doing that? Nope. Would it have been secure, performant or reliable? Highly unlikely. All I wanted was someone to do the hard work of putting all the pieces together and present them on a platter to me. Not too much to ask, I think you'll agree.
My intent is to deploy this service in small increments and very often using some sort of CI/CD tooling, so at the very least the deployments must be automatable. If everything else is as well, that will allow me to build any tooling I might need. I don't want your easy "one button deployment" I want a simple "one call deployment".
Logging has been a wonderful asset over the last few decades, but I really believe that tracing (via OpenTelemetry) and the observability it provides is the future of understanding live systems. I suspect it will supersede most, if not all, use cases for logging (not with the certainty that certain corners of the internet believed Blockchain was the future finance or similar corners that A.I. is the future of everything, but pretty close). OpenTelemetry provides a Java agent that can automatically instrument a JVM application using libraries that it knows about. E.g. it will instrument the Jetty HTTP server because that's widely known enough that the good folk over at the OpenTelemetry project have created automatic instrumentation for it as opposed to the HTTPKit server, which isn't as well known. For me to benefit from this automated tracing I need to be able to start my application with this Java agent.
I'm a firm believer in trunk based development, or at the very least, short lived feature branches. Ideally I was looking for a service that would provide canary releases which would allow me to progressively roll out new versions of my service to increasingly larger percentages of my users. At the very least I wanted somewhere that would not allow me to deploy obviously broken versions of my service.
I'm only a lowly software engineer, this isn't an attempt to make money and I already have plenty of expensive hobbies. I don't need to add cloud computing to that list.
I'm not proud to say it, but in this moment, my Google-fu failed me. Heroku looked promising as it could host the UberJAR, but there was no way that I could find to run the OpenTelemetry javaagent alongside it. Railway probably should have been enough, but the documentation didn't immediately click and somehow I missed fly.io (we'll get back to that one).
So I did what any self-respecting (some might say foolish or naive) software engineer suffering from "not invented here" syndrome would do and spent the next 6 months, off and on, building my deployment process through SSH to a Digital Ocean droplet. Had I not been suffering from said syndrome I could have spent that time learning something useful, like k8s or AWS. Don't get me wrong, I learnt a lot about Docker's API, how to use lispyclouds contajners library and Metosin's sieppari, and programmatically using SSH, but it appears building a PaaS isn't as easy as it first looks. Who knew?
And then fly.io turned up in one of my social media feeds (I suspect it was The Primeagen, but I can't find the video now). It's a PaaS primarily driven through the CLI, it runs Docker containers so I can run a javaagent alongside my service, it's got multiple deployment options and it's cheap. Plus it handles SSL certs, secret management and has GitHub Actions integrations. Tick, tick, tick, tick. Okay, it's got a release option called "Canary" that isn't what I would describe as a canary release, but at least it should be enough to stop me shooting myself in the foot. If I'm reasonably careful.
Since I'm not a Docker expert I decided to steal the expertise of other humans who actually know what they're doing. Practically has some excellent documentation on building Docker images for Clojure applications. Andrey Fadeev has a really useful YouTube video about Docker and Clojure that helped it click for me. In fact, all his videos are great, if you're looking to step up your Clojure game you could do a lot worse than work your way through his back catalogue.
I created a following Dockerfile in the infra directory.
restaurant
...
├── infra
│ └── ...
│ └── Dockerfile
...
The strategy was to use a fully featured base to build the UberJAR and then a very thin base to run service itself.
FROM clojure:temurin-21-alpine AS builder
RUN mkdir -p /build
WORKDIR /build
COPY deps.edn /build/
RUN clojure -P -X:build
COPY ./src /build/src
RUN mkdir -p /build/infra
COPY ./infra/build.clj /build/infra/
RUN clojure -T:build uber
FROM eclipse-temurin:21-jre-alpine AS final
LABEL org.opencontainers.image.source=https://github.com/HughPowell/restaurant
LABEL org.opencontainers.image.description="Restaurant reservation application"
LABEL org.opencontainers.image.licenses="MPL-2.0"
RUN apk add --no-cache \
dumb-init~=1.2.5
ARG UID=10001
RUN adduser \
--disabled-password \
--gecos "" \
--home "/nonexistent" \
--shell "/sbin/nologin" \
--no-create-home \
--uid "${UID}" \
clojure
RUN mkdir -p /service && chown -R clojure. /service
USER clojure
WORKDIR /service
COPY --from=builder --chown=clojure:clojure /build/target/restaurant.jar /service/restaurant.jar
ENTRYPOINT ["/usr/bin/dumb-init", "--"]
CMD ["java", "-jar", "/service/restaurant.jar"]
Since I was defining a license here I also included the text of the license in a LICENSE file at the root of the project. My go to is the Mozilla Public License V2 (MPL-2.0).
Now this is what I call a quick start guide. Install, signup, launch (which generated a local config file in infra/fly.toml), deploy, all from the CLI. Just one small problem. It wouldn't let me (probably quite reasonably) expose port 80 on the docker container, so I decided to update the application to listen on port 3000 and then exposed that port from the Dockerfile. I didn't need to change the port the service ran on, but it meant the added benefit that I could run the UberJAR locally without needing sudo. Once that was fixed up I successfully deployed the service and for good measure I pointed a subdomain of my hughpowell.net domain name to it.
Now all I needed was a way to prevent me shooting myself in the foot as often as possible. Fly.io provides a number of deployment strategies including what they call 'canary'. This boots a single additional machine, waits for it to become healthy and then replaces all the running machines one-by-one. Not how I would describe a canary deployment strategy, but enough for the time being.
To enable this I set up a [deploy] section in my infra/fly.toml file like so
[deploy]
strategy = 'canary'
max_unavailable = 1
wait_timeout = "1m"
With my deployments now configured all I needed was to automate them every time a change was committed to main. I chose GitHub Actions as my CI/CD pipeline orchestrator of choice. No great reason, it's integrated into GitHub, I've used it a couple of times before and it seems as competent as anything else at this scale. Having added my fly.io API token to the FLY_API_TOKEN secret I check out the project, install the flyctl application and deploy the service. I limit the job to 15 minutes because I never want build times to exceed that.
name: Build the Restaurant service
on:
push:
branches:
- main
jobs:
build:
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Setup deployment controller
uses: superfly/flyctl-actions/setup-flyctl@master
- name: Deploy service
run: flyctl deploy --config infra/fly.toml
env:
FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
So, yeah. The last six months has basically boiled down to flyctl deploy --config infra/fly.toml and a lot of learning.
Now that my service is running in production I need a way to check that it's doing everything it should do and nothing it shouldn't. As noted above I wanted to use OpenTelemetry for that. Instrumenting the service locally required downloading the OpenTelemetry Java agent and then starting the UberJAR with the -javaagent:<path-to-OpenTelemetry-agent> flag. You can also pass a similar option to your REPL and you'll get traces while developing. There's a couple of options for interacting with OpenTelemetry locally. You can export the traces to the console or to an observability tool like SigNoz, my current tool of choice, or Digma.
Unfortunately OpenTelemetry hasn't penetrated the entire Java ecosystem (yet!) so I still needed a way to output logs that are being written by the libraries I have and will import. Luckily the OpenTelemetry defines a standard which the Java agent has implemented to facilitate recording logs as spans.
First off I had to deal with the chaos that is Clojure logging infrastructure. To be fair it's mostly Java's fault. Either way, the magic incantations were to add a stack of dependencies
{...
:deps {...
ch.qos.logback/logback-classic {:mvn/version "1.2.3"}
org.slf4j/jcl-over-slf4j {:mvn/version "1.7.30"}
org.slf4j/jul-to-slf4j {:mvn/version "1.7.30"}
org.slf4j/log4j-over-slf4j {:mvn/version "1.7.30"}
org.slf4j/osgi-over-slf4j {:mvn/version "1.7.30"}
org.slf4j/slf4j-api {:mvn/version "1.7.30"}
...
}
...
}
the OpenTelemetry logback appender
{...
:deps {...
io.opentelemetry.instrumentation/opentelemetry-logback-appender-1.0 {:mvn/version "2.6.0-alpha"}
...
}
...
}
and then deregister the console log appender and create an OpenTelemetry one
(ns restaurant
...
(:import (ch.qos.logback.classic Level Logger)
(io.opentelemetry.instrumentation.logback.appender.v1_0 OpenTelemetryAppender)
(org.eclipse.jetty.server Server)
(org.slf4j LoggerFactory))
...)
(defn configure-open-telemetry-logging []
(let [context (LoggerFactory/getILoggerFactory)
^Logger logger (.getLogger context Logger/ROOT_LOGGER_NAME)]
(.detachAppender logger "console")
(let [open-telemetry-appender (doto (OpenTelemetryAppender.)
(.setContext context)
(.setCaptureCodeAttributes true)
(.start))]
(doto logger
(.setLevel Level/INFO)
(.addAppender open-telemetry-appender)))))
...
(defn -main [& _args]
(configure-open-telemetry-logging)
...)
(comment
(configure-open-telemetry-logging)
...
)
It's marginally disconcerting that logging now takes up almost exactly half of the service's code, but to be fair, the rest is just managing the HTTP server.
I added the OpenTelemetry Java agent to my Dockerfile and added the required arguments to attach to the JVM as the service started.
FROM clojure:temurin-21-alpine AS builder
RUN mkdir -p /artifacts
RUN wget -O /artifacts/opentelemetry-javaagent.jar https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v2.6.0/opentelemetry-javaagent.jar
...
FROM eclipse-temurin:21-jre-alpine AS final
...
COPY --from=builder --chown=clojure:clojure /artifacts/opentelemetry-javaagent.jar /service/opentelemetry-javaagent.jar
...
CMD ["java", "-javaagent:/service/opentelemetry-javaagent.jar", "-jar", "/service/restaurant.jar"]
For production traces I like Honeycomb (I'm also a big fan of Honeycomb's CTO Charity Majors, especially her perspectives on observability and socio-technical systems. I highly recommend perusing her blog when you have a chance.) They've got a free plan of 20 million events per month, which is more than enough to get started with. Having signed up I used flyctl to store the sensitive env vars that required my API key
fly secrets set OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=<API key>"
fly secrets set OTEL_EXPORTER_OTLP_METRICS_HEADERS="x-honeycombb-team=<API key>,x-honeycomb-dataset=restaurant"
and configured the rest of the required environment variables in my fly.toml configuration
[env]
OTEL_TRACES_EXPORTER = 'otlp'
OTEL_METRICS_EXPORTER = 'otlp'
OTEL_EXPORTER_OTLP_ENDPOINT = 'https://api.honeycomb.io'
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT = 'https://api.honeycomb.io/v1/traces'
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT = 'https://api.honeycomb.io/v1/metrics'
OTEL_SERVICE_NAME = 'restaurant'
The service was redeployed and logs and traces were being sent to Honeycomb.
The last six months (on and often off) has basically resulted in one line of code, flyctl deploy --config infra/fly.toml. It's pretty humbling, knowing I'm still perfectly capable of barreling headlong into a rabbit hole far enough that the diggers need to be called in.
The restaurant service is now running in production, re-deployed every time a new change is pushed to main and is pushing traces and logs through OpenTelemetry to Honeycomb.
Next time we'll finish off the check-list, "Turn on all the error messages". See you then. Hopefully somewhat sooner than this time.
Next: Guardrails
Previous: Modern software engineering for a small team
Published: 2024-07-27
Tagged: clojure restaurant infrastructure
I'm a software engineer with two decades in the software industry. Over those two decades I've spent most of my time in "brown field" code bases, code bases where I wasn't around when they were first started. I've also been working inside larger ecosystems that provide a lot, if not all, of the surrounding infrastructure (e.g. integration and deployment pipelines, databases, logging, etc.). This means that I rarely spin up new projects, nor do I fully understand the fundamentals that underpin the tooling that is required to support those products. That tooling is abstracted away and my use of it is reduced to an API call or copy, paste and small modification of a config file. This is great for working in that particular ecosystem, but doesn't help me understand what is going on under the hood. While this understanding clearly isn't a requirement to do my job (or I'm doing fantastically well to "faking it until I make it") it's gotten to the point where I really would like to understand what is required and what is going on.
To explore these cracks (or more likely crevasses) in my understanding my plan is to work through a project from scratch using what I believe to be modern software engineering techniques and processes as if I were bootstrapping a new product with a small team. I hope to take the simplest (but not always the easiest) route possible and eschewing certain technologies until their introduction reduces the complexity of the product. For example, I've skirted the edges of more infrastructure focused technology (e.g. Terraform and Kubernetes) and so will start without them and intend to bring them in only if the additional complexity simplifies the product overall.
A lot of my recent thinking about software engineering is underpinned by Accelerate by Nicole Forsgren, Jez Humble and Gene Kim. I expect I will often refer to the capabilities described there during this series of blog posts.
My years at the coal face have also exposed me to many ideas that would like to try, but which I haven't found space to try out in a professional setting. I intend to experiment with them here, as and when appropriate, no doubt making mistakes and hopefully rectifying them in future installments.
Normally when I'm trying out new languages, processes and/or tools I'll build the requisite contacts or todo-list application. The problem with those specific projects is that the vast majority of the code ends up being request and response handling, authentication, database wrangling and the like, and very little actual business logic. While this is fine for experimenting with new languages or tools, modern software engineering is about building software that continuously evolves. That non-business logic scaffolding tends to be the most static part of the application from an engineering perspective, so I'm looking for a product with plenty of business logic that can evolve over time.
I've just started reading Mark Seemann's book Code That Fits in Your Head which apparently includes a restaurant reservation system that he builds throughout the book, starting simply and modifying and adding new features as new use cases present themselves. Exactly the sort of product I'm looking for.
The example application in Code That Fits in Your Head is written in C#. My current tool of choice is Clojure so as I read through each chapter I will build a Clojure application using the requirements defined in that chapter. While the code for this blog series will be in Clojure I hope to explore some wider software engineering thoughts and opinions I have. Hopefully this means this series will be useful to more than just Clojurists.
As an aside, this isn't a beginners guide to Clojure. If you're new to Clojure and need some resources to get started then Practicalli, the Getting Started section of the Clojure website and Clojure for the Brave and True are all excellent starting points.
The first practical advice in Code That Fits in Your Head provides is to use checklists. Having read Atul Gawande's The Checklist Manifesto and agreed with most of it, I'm all on board for this. The book recommends the following checklist for starting a project
A checklist isn't a detailed list of everything that needs to be done, nor is it a list of requirements. It's just a reminder of the high level, important things that need to be done. Nor is it static, checklists are expected to be personalised and evolved over time. To me, this seems like a perfectly reasonable starting point.
Code That Fits in Your Head starts off by creating a web server that simply returns "Hello World!" to every request, so that's where I'll start.
Of the 3 main project management tools available for Clojure, (deps.edn, leiningen and boot) the most I've had experience with recently is deps.edn, so I'll go with that. Sean Corfield's deps-new is one option for generating projects from templates, but in this instance I'm going to do it by hand.
To start with I'll need a minimal directory layout
restaurant/
├── deps.edn
├── src
│ └── restaurant.clj
There are two primary mechanisms for server side applications in Clojure, ring and pedestal. I haven't used pedestal in anger and the ring ecosystem is rich and vibrant so that's the one I'll be working with. With that in mind, I'll add the following to my deps.edn file.
{:paths ["src"]
:deps {org.clojure/clojure {:mvn/version "1.11.1"}
ring/ring-jetty-adapter {:mvn/version "1.11.0"}}}
As mentioned above, the current requirement is for a web server that simply returns "Hello World!" as the response to any requests. The easiest way to do this is as follows
(ns restaurant
(:require [ring.adapter.jetty :as jetty])
(:gen-class))
(defn -main [& _args] (jetty/run-jetty (fn [_] {:status 200 :body "Hello World!"}) {}))
While this code will work in production (once I've built and deployed the service) I can't run it locally as a normal user, either in the REPL or on the command line, because it will attempt to bind to port 80 which normal users cannot do. Assuming I'm not running anything else on port 80, I can escalate my privileges and check that it works. On my linux box that's
$ sudo clojure -M -m restaurant
and I can then access the server using curl (or your command line web client of choice).
$ curl localhost
Hello World!
Although it works, this is a pretty hostile situation for a developer, especially as complexity increases.
Now that I've got something working I check my checklist and the first thing I find is "Use Git". With that in mind I do the following:
.gitignore file and add in any files created by our IDE and anything else that we haven't explicitlycreatedOne of the capabilities outlined in Accelerate is "Trunk-based development". This means either working with very short-lived feature branches or no branches at all. Because I'll be the only person working on this product I intend to go with no branching at all. Once I start deploying to production I'll need some safeguards, but for now I'll commit straight to the trunk in as small commits as make sense.
While the implementation of the server technically works, I tend to follow the mis-quoted aphorism that "code should be as simple as possible, and no simpler". I actually think this code is too simple. It doesn't clean up after itself nor is it developer and REPL friendly. With that in mind I extract out start-server and stop-server functions and gracefully shut down the server when the service is shut down.
(ns restaurant
(:require [ring.adapter.jetty :as jetty])
(:import (org.eclipse.jetty.server Server))
(:gen-class))
(defn start-server
([] (start-server {}))
([config] (jetty/run-jetty (fn [_] {:status 200 :body "Hello World!"}) config)))
(defn stop-server [server]
(.stop ^Server server))
(defn -main [& _args]
(let [server (start-server)]
(.addShutdownHook
(Runtime/getRuntime)
(Thread. ^Runnable (fn [] (stop-server server))))))
(comment
(def server (start-server {:port 3000 :join? false}))
(stop-server server))
By passing in config I can now use the default config for production and modify it simply at development time. Here I run the server on port 3000 and setting :join? to false means the server doesn't block our REPL thread.
Great. I can now start and stop our web server in the REPL, a much friendlier developer experience. The only problem is that when I do start the application/REPL I get the following warning
SLF4J: No SLF4J providers were found.
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See https://www.slf4j.org/codes.html#noProviders for further details.
Looks like our server uses SLF4J for logging, so I should provide a logger implementation. I could use the no-op logger, but I tend to like being informed when stuff goes wrong. With that in mind I use the SLF4J SimpleLogger by adding it to our dependencies
{:paths ["src"]
:deps {org.clojure/clojure {:mvn/version "1.12.0-alpha5"}
org.slf4j/slf4j-simple {:mvn/version "2.0.10"}
ring/ring-jetty-adapter {:mvn/version "1.11.0"}}}
Now when I start the application I no longer get the warning. Once I start the server, however, we get the following log messages
[nREPL-session-aca1af76-ccda-46d5-b745-63e29dc26d52] INFO org.eclipse.jetty.server.Server - jetty-11.0.18; built: 2023-10-27T02:14:36.036Z; git: 5a9a771a9fbcb9d36993630850f612581b78c13f; jvm 21.0.1+12-29
[nREPL-session-aca1af76-ccda-46d5-b745-63e29dc26d52] INFO org.eclipse.jetty.server.handler.ContextHandler - Started o.e.j.s.ServletContextHandler@cc0cd0{/,null,AVAILABLE}
[nREPL-session-aca1af76-ccda-46d5-b745-63e29dc26d52] INFO org.eclipse.jetty.server.AbstractConnector - Started ServerConnector@4ce608d3{HTTP/1.1, (http/1.1)}{0.0.0.0:3000}
[nREPL-session-aca1af76-ccda-46d5-b745-63e29dc26d52] INFO org.eclipse.jetty.server.Server - Started Server@36b520a7{STARTING}[11.0.18,sto=0] @23056ms
While this information can be useful, unless I'm being warned about something I don't want this noise distracting me, and potentially hiding more important information, during development. I still want to know about warnings and errors, so I need to change the minimum logging level to Warn. There's a couple of ways to do that, but my preferred is to do it programmatically.
Clojure has a concept of aliases to add or remove functionality depending on the situation. In this case, when I'm developing I want to set the minimum log level to Warn. I add an alias called dev to deps.edn
{:paths ["src"]
:deps {org.clojure/clojure {:mvn/version "1.12.0-alpha5"}
org.slf4j/slf4j-simple {:mvn/version "2.0.10"}
ring/ring-jetty-adapter {:mvn/version "1.11.0"}}
:aliases {:dev {:extra-paths ["dev"]}}}
and a dev/user.clj file to our project
restaurant/
├── deps.edn
├── dev
│ └── user.clj
├── src
│ └── restaurant.clj
The dev/user.clj file will be loaded when the REPL starts, so I set the minimum log level in there
(ns user
(:import (org.slf4j.simple SimpleLogger)))
(System/setProperty SimpleLogger/DEFAULT_LOG_LEVEL_KEY "Warn")
Now when I start the server from the REPL I no longer get the information log lines, leading to a cleaner development experience.
In this first blog post I talked about why I'm creating this series, how it will (hopefully) demonstrate modern software development techniques and processes and I built a simple, first cut of a web server. The project so far can be found in a GitHub repository. In my next post I'll look at the second item on the checklist, "Automate the build". If you've got comments or questions feel free to reach out via Twitter/X (linked above) or on the Clojurians Slack channel.
Next: 6 months, 1 line of code
Previous: My first blog post
Published: 2024-01-16
Tagged: clojure restaurant