akiel/lens-workbook repository overview

Please start at the Top-Level Lens Repo⁠.

⁠Lens Workbook Service

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

⁠Environment

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.

⁠Develop

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 groups.

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.

⁠License

Copyright © 2015 Alexander Kiel

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