Spinning up a new Crux node is generally a case of including the relevant Crux dependencies within your project, defining a 'topology' configuration, and then making a call to start-node
with that configuration. This is not a particularly difficult process but it still requires you to dip into Clojure or Java before you can get something running.
We created the crux-build
tool to bypass this process and make getting started much simpler for non-Clojure users.
crux-build
was initially released with Crux in 20.02-1.7.0-alpha
. It offers a small range of 'batteries included' JARs and Docker containers to help you get a basic Crux implementation running, and an easy mechanism to generate your own custom Crux deployment artifacts.
Batteries included - crux-standalone
Available since 20.01-1.7.0-alpha
, on both:
-
GitHub releases, see the
crux-standalone.jar
attached to each release.
This starts up a bare-bones Crux implementation, utilising three Crux modules:
-
crux-core
- required by all nodes. -
crux-cli
- required by allcrux-build
artifacts, used to start up the node and output configuration options to the command line. -
crux-http-server
- each configuration starts an HTTP server (on port 3000 by default).
On the Docker Hub page there is a basic tutorial for getting started with the Crux REST API, and you can find out more in the docs.
crux-standalone
is intended for users to get started with Crux, without requiring any prior Java/Clojure knowledge. It contains an in-memory node that does not persist any data across restarts.
We plan to provide further 'batteries included' implementations in the future (suggestions are welcome!), but let’s now take a look at how to generate custom Crux deployment artifacts.
Roll your own Crux deployment artifacts
Alongside the JARs deployed on the GitHub releases is crux-builder.tar.gz
- using the scripts in this archive, we can customise and build a JAR or a 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.
In this example, let’s add rocksdb
as the KV store, storing the indexes in a folder called 'crux-indexes', and the standalone tx-log/document-store in crux-event-log
.
First, we add crux-rocksdb
as a dependency in deps.edn
.
Then, in crux.edn
, use this new topology:
{:crux.node/topology [crux.standalone/topology
crux.http-server/module
crux.kv.rocksdb/kv-store]
:crux.http-server/port 3000
:crux.kv/db-dir "crux-indexes"
:crux.standalone/event-log-kv-store 'crux.kv.rocksdb/kv
:crux.standalone/event-log-dir "crux-event-log"}
To build the JAR, run the build-uberjar.sh
script.
You can optionally pass an 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
, except with 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, we can 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, we can add rocksdb
as the KV store - first, by adding a dependency on crux-rocksdb
to deps.edn
Default index and event-log directories are already configured within the sample crux.edn
(allowing you to map the Docker directories and give the images persistent storage), we just need to add crux.kv.rocksdb/kv-store
to the :crux.node/topology
list.
{:crux.node/topology [crux.standalone/topology
crux.http-server/module
crux.kv.rocksdb/kv-store]
:crux.http-server/port 3000
:crux.kv/db-dir "/var/lib/crux/db"
:crux.standalone/event-log-kv-store crux.kv.rocksdb/kv
:crux.standalone/event-log-dir "/var/lib/crux/event-log"}
To build your Docker container, run the build-docker.sh
script.
You can optionally pass an IMAGE_NAME
and IMAGE_VERSION
to tag the container with (by default, the custom Docker container is called crux-custom:latest
).
In Summary
This is only scratching the surface of different setups that Crux’s unbundled nature allows - for more information, check out the configuration section of the docs.
Get busy building!
As always, feel free to reach out to us on Zulip, the #crux channel on the Clojurians' Slack or via crux@juxt.pro.