Menu

Building

crux-build is a module within the crux repo with two key objectives:

  • Providing pre-configured JARs and Docker containers to start a basic implementation of Crux with no prior knowledge required.

  • Providing a mechanism to spin up custom Crux artifacts - with two necessary inputs:

    • A deps.edn file containing the dependencies that the node requires.

    • A crux.edn file, containing the configuration options to start the node with.

Preconfigured Artifacts

crux-in-memory

Crux’s in-memory artifacts start up a basic, in-memory Crux node, with an HTTP server.

They can be downloaded:

Communication with the node is done via the Crux REST API - see the HTTP docs for more information.

Building Artifacts

Alongside the JARs deployed on the GitHub releases is crux-builder.tar.gz - the scripts within this archive can be used to build a custom Crux JAR or Docker container.

Building a JAR (Clojure CLI tooling)

The clj-uberjar folder contains a number of files:

  • a deps.edn file to configure the Maven dependencies required

  • a crux.edn file to configure the node itself

  • a resources/logback.xml to configure logging output

  • a build-uberjar.sh script to build the JAR.

To use rocksdb as the index store, document store and transaction-log store of the node:

  • Add crux-rocksdb as a dependency in deps.edn:

    ...
    juxt/crux-rocksdb {:mvn/version "20.09-1.12.1-beta"}
    ...
  • In crux.edn, override the old topology with the following:

    {:crux/index-store {:kv-store {:crux/module crux.rocksdb/->kv-store, :db-dir "/tmp/crux/indexes"}}
     :crux/document-store {:kv-store {:crux/module crux.rocksdb/->kv-store, :db-dir "/tmp/crux/documents"}}
     :crux/tx-log {:kv-store {:crux/module crux.rocksdb/->kv-store, :db-dir "/tmp/crux/tx-log"}}
     :crux.http-server/server {}}

To build the JAR, run the build-uberjar.sh script. You can optionally pass the environment variable UBERJAR_NAME (for example, crux-rocks.jar) to the script, otherwise the built uberjar will be called crux.jar.

Running the JAR will now start up a similar node to crux-standalone above - with the addition of persistent storage.

Building a JAR (Maven tooling)

Similarly to building a JAR using the Clojure CLI tooling, we can also build an uberjar using Maven. In the mvn-uberjar directory, add dependencies to the pom.xml file, update the crux.edn file as before, and then run build-uberjar.sh to create the uberjar.

Building a Docker Container

In the docker directory, there are a similar set of files to the uberjar examples above, as well as a Dockerfile and a build-docker.sh script.

As with building a JAR, to add rocksdb as the KV store - start by adding a dependency on crux-rocksdb within deps.edn.

Override the topology within crux.edn with the following:

{:crux/index-store {:kv-store {:crux/module crux.rocksdb/->kv-store, :db-dir "/var/lib/crux/indexes"}}
 :crux/document-store {:kv-store {:crux/module crux.rocksdb/->kv-store, :db-dir "/var/lib/crux/documents"}}
 :crux/tx-log {:kv-store {:crux/module crux.rocksdb/->kv-store, :db-dir "/var/lib/crux/tx-log"}}
 :crux.http-server/server {}}

To build your Docker container, run the build-docker.sh script. You can optionally pass the environment variables IMAGE_NAME and IMAGE_VERSION to tag the container with (by default, the custom Docker container is called crux-custom:latest).