Using the ArangoDB Starter

This section describes how to start a Cluster using the tool Starter(the arangodb binary program).

As a precondition you should create a secret to activate authentication. The Starter provides a handyfunctionality to generate such a file:

  1. arangodb create jwt-secret --secret=arangodb.secret

Set appropriate privilege on the generated secret file, e.g. on Linux:

  1. chmod 400 arangodb.secret

Local Tests

If you only want a local test Cluster, you can run a single Starter with the —starter.local argument. It will start a 3 “machine” Cluster on your local PC:

  1. arangodb --starter.local --starter.data-dir=./localdata --auth.jwt-secret=/etc/arangodb.secret

Please adapt the path to your secret file accordingly.

Note: a local Cluster is intended only for test purposes since a failure of a single PC will bring down the entire Cluster.

Multiple Machines

If you want to start a Cluster using the Starter, you need to copy the secret file to every machineand start the Cluster using the following command:

  1. arangodb --server.storage-engine=rocksdb --auth.jwt-secret=/etc/arangodb.secret --starter.data-dir=./data --starter.join A,B,C

Please adapt the path to your secret file accordingly.

Run the above command on machine A, B & C.

Once all the processes started by the Starter are up and running, and joined theCluster (this may take a while depending on your system), the Starter will informyou where to connect the Cluster from a Browser, shell or your program.

For a full list of options of the Starter please refer to thissection.

Using the ArangoDB Starter in Docker

The Starter can also be used to launch Clusters based on Docker containers:

  1. export IP=<IP of docker host>
  2. docker volume create arangodb
  3. docker run -it --name=adb --rm -p 8528:8528 \
  4.     -v arangodb:/data \
  5.     -v /var/run/docker.sock:/var/run/docker.sock \
  6.     arangodb/arangodb-starter \
  7.     --starter.address=$IP \
  8.     --starter.join=A,B,C

Run the above command on machine A, B & C.

If you use an ArangoDB version of 3.4 or above and use the EnterpriseEdition Docker image, you have to set the license key in an environmentvariable by adding this option to the above docker command:

  1.     -e ARANGO_LICENSE_KEY=<thekey>

You can get a free evaluation license key by visiting:

www.arangodb.com/download-arangodb-enterprise/

Then replace <thekey> above with the actual license key. The startwill then hand on the license key to the Docker containers it launchesfor ArangoDB.

TLS verified Docker services

Oftentimes, one needs to harden Docker services using client certificate and TLS verification. The Docker API allows subsequently only certified access.As the ArangoDB starter starts the ArangoDB cluster instances using this Docker API, it is mandatory that the ArangoDB starter is deployed with the proper certificateshanded to it, so that the above command is modified as follows:

  1. export IP=<IP of docker host>
  2. export DOCKER_CERT_PATH=/path/to/certificate
  3. docker volume create arangodb
  4. docker run -it --name=adb --rm -p 8528:8528 \
  5.     -v arangodb:/data \
  6.     -v /var/run/docker.sock:/var/run/docker.sock \
  7.     -v $DOCKER_CERT_PATH:$DOCKER_CERT_PATH \
  8.     -e DOCKER_TLS_VERIFY=1 \
  9.     -e DOCKER_CERT_PATH=$DOCKER_CERT_PATH \
  10.     arangodb/arangodb-starter \
  11.     --starter.address=$IP \
  12.     --starter.join=A,B,C

Note that the environment variables DOCKER_TLS_VERIFY and DOCKER_CERT_PATH as well as the additional mountpoint containing the certificate have been added above. directory. The assignment of DOCKER_CERT_PATH is optional, in which case it is mandatory that the certificates are stored in $HOME/.docker. Sothe command would then be as follows

  1. export IP=<IP of docker host>
  2. docker volume create arangodb
  3. docker run -it --name=adb --rm -p 8528:8528 \
  4.     -v arangodb:/data \
  5.     -v /var/run/docker.sock:/var/run/docker.sock \
  6.     -v /path/to/cert:/root/.docker \
  7.     -e DOCKER_TLS_VERIFY=1 \
  8.     arangodb/arangodb-starter \
  9.     --starter.address=$IP \
  10.     --starter.join=A,B,C

Under the Hood

The first arangodb you ran will become the master of your Starter_setup, the other arangodb instances will become the _slaves of your Starter_setup. Please do not confuse the terms _master and slave above with the master/slavetechnology of ArangoDB. The terms above refers to the Starter setup.

The Starter__master determines which ArangoDB server processes to launch on whichStarter__slave, and how they should communicate.

It will then launch the server processes and monitor them. Once it has detectedthat the setup is complete you will get the prompt.

The Starter__master will save the setup for subsequent starts.