Starting an ArangoDB cluster or database the easy way

Starting an ArangoDB cluster involves starting various servers withdifferent roles (Agents, DB-Servers & Coordinators).

The ArangoDB Starter is designed to make it easy to start andmaintain an ArangoDB cluster or single server database.

Besides starting and maintaining ArangoDB deployments, the starter also providesvarious commands to create TLS certificates & JWT token secrets to secure yourArangoDB deployment.

ArangoDB is also available asmanaged service (ArangoDB Oasis).

Installation

The ArangoDB starter (arangodb) comes with all current distributions of ArangoDB.

If you want a specific version, download the precompiled binary via theGitHub releases page.

Starting a cluster

An ArangoDB cluster typically involves 3 machines.ArangoDB must be installed on all of them.

Then start the ArangoDB starter of all 3 machines like this:

On host A:

  1. arangodb

This will use port 8528 to wait for colleagues (3 are needed for aresilient Agency). On host B (can be the same as A):

  1. arangodb --starter.join A

This will contact A on port 8528 and register. On host C (can be sameas A or B):

  1. arangodb --starter.join A

This will contact A on port 8528 and register.

From the moment on when 3 have joined, each will fire up an Agent, aCoordinator and a DB-Server and the cluster is up. Ports are shown onthe console, the starter uses the next few ports above the starterport. That is, if one uses port 8528 for the starter, the Coordinatorwill use 8529 (=8528+1), the DB-Server 8530 (=8528+2), and the Agent 8531(=8528+3). You can change the default starter port with the —starter.portoption.

Additional servers can be added in the same way.

If two or more of the arangodb instances run on the same machine,one has to use the —starter.data-dir option to let each use a differentdirectory.

The arangodb program will find the ArangoDB executable (arangod) and theother installation files automatically. If this fails, use the—server.arangod and —server.js-dir options described below.

Running in Docker

You can run arangodb using our ready made docker container.

When using arangodb in a Docker container it will also run allservers in a docker using the arangodb/arangodb:latest docker image.If you wish to run a specific docker image for the servers, specify it usingthe —docker.image argument.

When running in docker it is important to care about the volume mappings onthe container. Typically you will start the executable in docker with the followingcommands.

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

The executable will show the commands needed to run the other instances.

Note that the commands above create a docker volume. If you’re running on Linuxit is also possible to use a host mapped volume. Make sure to map iton /data.

TLS verified Docker services

Oftentimes, one needs to harden Docker services using client certificate and TLS verification. The Docker API allows subsequently onlycertified access. As the ArangoDB starter starts the ArangoDB clusterinstances using this Docker API, it is mandatory that the ArangoDBstarter is deployed with the proper certificates handed to it, so thatthe 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

The TLS verification above applies equally to all below deployment modes.

Using multiple join arguments

It is allowed to use multiple —starter.join arguments.This eases scripting. For example:

On host A:

  1. arangodb --starter.join A,B,C

On host B:

  1. arangodb --starter.join A,B,C

On host C:

  1. arangodb --starter.join A,B,C

This starts a cluster where the starter on host A is chosen to be master during the bootstrap phase.

Note: arangodb —starter.join A,B,C is equal to arangodb —starter.join A —starter.join B —starter.join C.

During the bootstrap phase of the cluster, the starters will all choose the “master” starterbased on list of given starter.join arguments.

The “master” starter is chosen as follows:

  • If there are no starter.join arguments, the starter becomes a master.
  • If there are multiple starter.join arguments, these arguments are sorted. If a starter is the firstin this sorted list, it becomes a starter.
  • In all other cases, the starter becomes a slave.

Note: Once the bootstrap phase is over (all arangod servers have started and are running), the bootstrapphase ends and the starters use the Arango Agency to elect a master for the runtime phase.

Starting a local test cluster

If you want to start a local cluster quickly, use the —starter.local flag.It will start all servers within the context of a single starter process.

  1. arangodb --starter.local

Using the starter this way does not provide resilience and high availability of your cluster!

Note: When you restart the starter, it remembers the original —starter.local flag.

Starting a cluster with datacenter to datacenter synchronization

Datacenter to datacenter replication is only available in theEnterprise Edition,also available as managed service.

Datacenter to datacenter replication (DC2DC) requires a normal ArangoDB cluster in both data centersand one or more (arangosync) syncmasters & syncworkers in both data centers.The starter enables you to run these syncmasters & syncworkers in combination with your normalcluster.

To run a starter with DC2DC support you add the following arguments to the starters command line:

  1. --auth.jwt-secret=<path of file containing JWT secret for communication in local cluster>
  2. --starter.address=<publicly visible address of this machine>
  3. --starter.sync
  4. --server.storage-engine=rocksdb
  5. --sync.master.jwt-secret=<path of file containing JWT secret used for communication between local syncmaster & workers>
  6. --sync.server.keyfile=<path of keyfile containing TLS certificate & key for local syncmaster>
  7. --sync.server.client-cafile=<path of file containing CA certificate for syncmaster client authentication>

Consult arangosync documentation for instructions how to create all certificates & keyfiles.

Starting a single server

If you want to start a single database server, use —starter.mode=single.

  1. arangodb --starter.mode=single

Starting a single server in Docker

If you want to start a single database server running in a docker container,use the normal docker arguments, combined with —starter.mode=single.

  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.mode=single

Starting a resilient single server pair

If you want to start a resilient single database server, use —starter.mode=activefailover.In this mode a 3 machine Agency is started as well as 3 single servers that performasynchronous replication an failover if needed.

  1. arangodb --starter.mode=activefailover --starter.join A,B,C

Run this on machine A, B & C.

Starting a resilient single server pair in Docker

If you want to start a resilient single database server running in docker containers,use the normal docker arguments, combined with —starter.mode=activefailover.

  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.mode=activefailover \
  9.     --starter.join=A,B,C

Run this on machine A, B & C.

The starter will decide on which 2 machines to run a single server instance.To override this decision (only valid while bootstrapping), add a—cluster.start-single=false to the machine where the single serverinstance should NOT be scheduled.

Starting a local test resilient single sever pair

If you want to start a local resilient server pair quickly, use the —starter.local flag.It will start all servers within the context of a single starter process.

  1. arangodb --starter.local --starter.mode=activefailover

Note: When you restart the started, it remembers the original —starter.local flag.

Starting & stopping in detached mode

If you want the starter to detach and run as a background process, use the startcommand. This is typically used by developers running tests only.

  1. arangodb start --starter.local=true [--starter.wait]

This command will make the starter run another starter process in the background(that starts all ArangoDB servers), wait for it’s HTTP API to be available andthen exit. The starter that was started in the background will keep running until you stop it.

The —starter.wait option makes the start command wait until all ArangoDB serverare really up, before ending the master process.

To stop a starter use this command.

  1. arangodb stop

Make sure to match the arguments given to start the starter (—starter.port & —ssl.*).

More information

  • Options contains a list of all commandline options supported by the starter.
  • Security contains instructions of how to create certificates & tokens neededto secure an ArangoDB deployment.