Køa

A simple web app built with Clojure

Motivation

This project is an opportunity to experiment with technologies that have interested me for a long time, in particular Clojure/Nix/Emacs. I see it as a bit of a testing ground for how to set up software projects in the way I would like to do it.

Setup

Nix

First, install the Nix package manager. Then, enable Flakes. You can do this by adding the following to ~/.config/nix/nix.conf or /etc/nix/nix.conf:

experimental-features = nix-command flakes

Nix will be managing dependencies for our project.

Direnv

For an extra enjoyable development experience, install direnv. This allows us to automatically load the nix flake packages simply by cd'ing into the project directory. To begin using it, run the following in this project directory:

direnv allow

Make sure to also install the shell hook for your appropriate shell.

This tells direnv that this directory is safe, and that it should pull the required packages. This should for example pull in clojure to your PATH.

Secrets

Secrets for this project are saved in secrets.yaml, and encrypted with sops. These are then loaded as environment variables by .direnv. This means that this project assumes that you are developing with nix + direnv to work properly.

Further, to edit secrets, you can run sops secrets.yaml. This will open an unencrypted view of your secrets in your terminal editor.

Datomic

This project uses Datomic as its database. I have not found a way to configure this with nix, as it is a global thing.

In order to use Datomic, you have to create the file ~/.datomic/local.edn with the following content:

{:storage-dir "~/.datomic/db/"}

This tells datomic to use that path to save the database. This can be any absolute path.

Emacs

The star of the development show here is Emacs. I have configured emacs to use clojure-mode, cider and direnv-mode. This means that opening the project in emacs will load the direnv, as it does on the shell. Anecdote: During setting this up, I was reminded that Clojure+Cider was the reason I started using Emacs way back, probably 2019 or so. I never really ended up experimenting too much with Clojure then, but I have gone full circle.

Development

To develop with the REPL in emacs, run

M-x cider-jack-in

After a moment, a repl should load up. Then, in src/core.clj, execute

M-x cider-load-buffer ;; or directly with C-c C-k

This should load all the needed dependencies. To start the server, evaluate the following in the REPL:

(repl/start-server! app)

The web app should now be served at localhost:8887.

Happy hacking!

References

https://clojure-doc.org/articles/tutorials/basic_web_development/ https://casey.link/blog/datomic-pro-flake/