Public | Automated Build

Last pushed: 2 years ago
Short Description
A workbook storage service for Lens.
Full Description

Please start at the Top-Level Lens Repo.

Lens Workbook Service

The workbook storage service of Lens system which is one of several backend


Lens workbook is a 12 Factor App and uses the following environment vars:

  • PORT - the port to listen on
  • DB_URI - the Datomic database URI
  • TOKEN_INTROSPECTION_URI - the OAuth2 token inspection URI to use
  • CONTEXT_PATH - an optional context path under which the workbook service runs. Has to be empty for root context or start with a slash but not ending with a slash.
  • DATOMIC_EDITION - one of free or pro with a default of free

Usage with Leiningen

Either set your environment according the above mentioned vars or create a .lein-env file containing a map like this one:

{:db-uri "datomic:free://..."
 :token-introspection-uri "http://..."
 :port 5000
 :context-path "/"}

To start the service with leiningen, run the following command

lein with-profile production,datomic-free trampoline run

Usage through Docker Container

You have to start a database volume container, a database container and a
workbook container linking them all together:

docker run --name lens-workbook-db-vol akiel/lens-workbook:latest-db-data
docker run -d --volumes-from lens-workbook-db-vol -e ALT_HOST=lens-workbook-db --name lens-workbook-db akiel/lens-workbook:latest-db
docker run -d -p 8080:80 --link lens-workbook-db:db --name lens-workbook akiel/lens-workbook

After starting all containers, a curl http://localhost:8080 should show the
service document of Lens Workbook.


Running a REPL will load the user namespace. Use (startup) to start the server
and (reset) to reload after code changes.

If you use Intellij IDEA with Cursive, you can add a Datomic stub JAR
to your project dependencies as described here. The stub will provide
signatures and documentation for the Datomic API functions. I can't add the
stub dependency to the project.clj file because it is currently not available on
Clojars. I opened an issue here.

The Concept behind Workbooks

Workbooks are collections of queries. Queries are the heart of Lens. Because
many projects will need more than one query to answer there particular question,
workbooks offer the right granularity to be the key thing to manage.

Workbooks are versioned. Versions form a history which is annotated by
automatically created comments. Each action on a workbook performed by the user
leads to a new version. There is no such thing as a save button. Each user
action is pushed to the server immediately forming version after version.
Workbook versions are immutable. It is always possible to go back to an
arbitrary version.

It is possible to create a duplicate of a workbook. A duplicate shares the
version history with its original workbook. One can still go back to older
versions on a duplicate. The difference is that the original one stays on the
version which was current as the duplicate was created. After creating a
duplicate one has effectively two strings of versions available which are
independent from each other.

Workbooks have names. Names are not versioned. If one creates a workbook, one
gives it a name. If one duplicates a workbook one should give the duplicate a
different name to help to separate both the original one and the duplicate. If
one creates a duplicate of a workbook and gives it another name, the name will
not revert to the name of the original workbook if one goes back to older
versions. Apart from that, one can still change the name of a workbook.

Workbooks can have snapshots. A snapshot points to a specific version of a
workbook and is itself immutable. Snapshots are like named versions of a
workbook. One can revert a workbook to a specific snapshot. One can also create
a new workbook based on a snapshot of an existing one. Besides there name,
snapshots have a message were one can describe the status of or the reason why
the snapshot was created.

Every user has a collection of private workbooks. Public workbooks on the other
hand are organized in groups. Groups have members. Each member can view, create
and edit workbooks. Workbooks can be moved from private to groups and between

Workbooks itself have also members.

Prepare Datomic Transactor

The Lens Workbook Service uses shortid to generate workbook ids. Because
the ids are generated inside a Datomic transaction, the transactor needs the
shortid jar file in its classpath. You can download the jar file from the
shortid releases on GitHub and place them in the lib directory of your
Datomic installation.


Copyright © 2015 Alexander Kiel

Distributed under the Eclipse Public License, the same as Clojure.

Docker Pull Command
Source Repository