meiraleal / dacom

A skeleton app built with Datomic, Compojure, and Om

DACOM

The Clojure community is all about libraries that do one thing and do it well, and justifiably so. However, it can be especially useful for newcomers to the community to see a more "horizontal" cross-section of what's out there. To that end, the DACOM (Datomic, Compojure, and Om) stack is a whirlwind tour of what I see as some of the most exciting pieces of the Clojure(Script) ecosystem in one rich webapp. I still have plenty to learn about the world of Clojure, so I welcome feedback and contributions from all.

Of course, this is just one possible combination of technologies and is definitely not a one-size-fits-all stack. However, any feedback on how to better embody Clojure(Script)/Datomic/Compojure/Om/Leiningen "best practices" are especially welcome.

##TLDR Clone this repo and screw around, or you can just do lein new dacom my-app-name. Skip down a ways for detailed instructions on installing/running.

##Overview of Technologies Used This project uses a wide array of Clojure (and non-Clojure) libraries and tools to "glue" everything together and provide some development conveniences, but the main components of the DACOM (rhymes with "datom") stack are:

###Datomic Datomic is a database that provides an entity-attribute-value model of data and can be queried with logic-based expressions (it does the equivalent of "joins" and such for you). Time is also a first-class citizen in Datomic. It stores an immutable collection of facts, each of which includes time as part of the fact, rather than updating anything in-place. Among other benefits, this means that you can grab a given version of the database whenever you want and query (read from) it to your heart's content, knowing that it refers to a single moment in time, and that you get "audit trails" for free. Check out day-of-datomic for a great guide to working with Datomic in Clojure.

###Compojure Compojure is a lightweight abstraction on top of Ring request-handling, which itself is an abstraction on top of Java servlets. Ring is a very streamlined, data-driven library that allows you to define handlers for HTTP requests that can be easily wrapped/extended with a flexible "middleware" model and allows deployment via WARs or standalone, Jetty-based JARs. Compojure adds some additional routing conveniences to let you define the various resources that make up your app kind of like in Ruby on Rails (though a better comparison would be to "micro-frameworks" like Flask or Sinatra).

###Om While Datomic and Compojure are fairly stable, Om is really hot-off-the-press (as of January, 2014). However, it has already garnered a great deal of praise from the internet, which is hardly ever wrong. It is based on Facebook's React library, which, unlike many front-end frameworks, generally limits itself to binding data to the DOM. This fits well with the Clojure philosophy of small libraries and data-orientation. You can read more about why Om's author thinks it's cool here.

##Quickstart with Datomic Free/Starter Datomic has a number of editions, offers a number of language interfaces, and supports a number of storage back-ends, so its documentation can be a little overwhelming. However, you can get started with a basic setup by:

• Getting Datomic (there are a couple of free options—this project is setup to use the "free" version)
• Running bin/transactor config/samples/free-transactor-template.properties on the command line from within the unzipped datomic directory (this works fine as of version 0.9.4384)

##Building and Running Working with this version of the DACOM stack is a little more cumbersome than it ideally should be, mainly due to a lack of front-end-oriented tools in the Leiningen ecosystem. There are a few such tools out there, but they are generally simple shell-based wrappers around NodeJS-based tools, so I have instead simply included some convenience tasks to invoke those tools through Leiningen without additional plugins.

###Prerequisites

• Datomic (any edition)
• Leiningen
• Bower
• Less
• Cerebellum

###Install and Run

• Datomic: With a Datomic transactor up and running with local storage (free/dev protocol—see above), run lein install-db (in the command line) to install the schema and some data
• Compojure: Run lein run-server to run the Ring (and Compojure) server, which provides the web service backend
• Om: Run lein run-client to assemble the static assets, including the Om front-end app and start a static web server

###Debug, Hack, and Play!

• Run lein cljsbuild auto dev to monitor .cljs files for changes and automatically recompile them
• Run lein watch-less to monitor less for changes and recompile
• Run lein repl to start the usual Leiningen/nREPL-based REPL
• Then, if you want to, type (browser-repl) or just (br) into the REPL to start an Austin-based browser REPL session. Once you've done that, refresh the webapp and try typing (js/alert "Hey there!") from the Clojure REPL

###Production-Style Build

• Just run lein dist in the project directory
• Then "deploy" like:

$ cd dist/server
$ echo "{:datomic-uri \"<some-datomic-uri>\" :port 3000}" > config.edn
$ java -jar <project-name>-<version-number>-standalone.jar
$ Started server on port 3000

• Then, for example:

$ cd <project-root>/dist/static && python -m SimpleHTTPServer
$ Serving HTTP on 0.0.0.0 port 8000 ...

• The app will be available on http://localhost:8000