Using the ArangoDB Starter
This section describes how to start a Cluster using the Starter
As a precondition you should create a secret to activate authentication. The Starter provides a handy functionality to generate such a file:
arangodb create jwt-secret --secret=arangodb.secret
Set appropriate privilege on the generated secret file, e.g. on Linux:
chmod 400 arangodb.secret
Also see Security for instructions of how to create certificates and tokens needed to secure an ArangoDB deployment.
Local test cluster
If you want to start a local test cluster quickly, you can run a single
Starter with the
--starter.local argument. It starts a 3 “machine” cluster
on your local computer within the context of a single starter process:
arangodb --starter.local --starter.data-dir=./localdata --auth.jwt-secret=/etc/arangodb.secret
Please adapt the path to your secret file accordingly.
A local cluster is intended for test purposes only. It does not provide resilience and high availability!
When you restart the Starter, it remembers the original
An ArangoDB cluster typically involves three machines. ArangoDB must be installed on all of them.
You need to copy the secret file to every machine. Then run the ArangoDB Starter like this on host A (adapt the path to your secret file accordingly):
arangodb --auth.jwt-secret=/etc/arangodb.secret --starter.data-dir=./data
This uses port 8528 to wait for other Starters and the nodes they manage. Three Agent nodes are needed for a resilient Agency, which is the default number, and the Starters wait for Agent nodes to form the Agency.
Run the following command on host B and C (replace
A with the host name or
IP address of the host):
arangodb --auth.jwt-secret=/etc/arangodb.secret --starter.data-dir=./data --starter.join A
--server.join option is for pointing a Starter to an existing Starter.
If you run Starters on ports other than the default (
8528) using the
--starter.port option, then you need to append the port to the address
The latter two Starters contact the Starter on host A on port 8528 and register themselves. From the moment on when three have joined, each fires up an Agent, a Coordinator, and a DB-Server.
Once all the processes started by the Starter are up and running, and joined the cluster (this may take a while depending on your system), the Starter informs you where to connect to the cluster from a browser, shell, or program.
Additional servers can be added in the same way. For example, on host D, you run
the above command pointing to the Starter that runs on
A (or on
long as they are connected to
A). This adds another DB-Server and Coordinator,
but no fourth Agent, as the default Agency size (
is already reached. To only add a DB-Server, use
To only add a Coordinator, use
You can also set both
false for the first three Starters to only create the Agency. This lets you
run the Agents on specific machines. Later, you can add the DB-Servers and
Coordinators to the cluster using other machines.
The Starter uses the next few ports above the Starter port for the cluster nodes.
That is, if you use port 8528 for the Starter, the Coordinator uses 8529
(=8528+1), the DB-Server 8530 (=8528+2), and the Agent 8531 (=8528+3).
You can change the default Starter port with the
If two or more of the
arangodb instances run on the same machine,
you have to use the
--starter.data-dir option to let each use a different
The Starter tries to find the ArangoDB executable (
arangod) and the
other installation files automatically. If this fails, use the
--server.js-dir options to manually point it to them.
For a full list of options of the Starter, see the Starter options.
Using multiple join arguments
It is allowed to use multiple
This eases scripting. For example, you can run a command like below on hosts
A, B, and C (replace
C with the host names):
arangodb ... --starter.join A,B,C
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 all choose the leader
Starter (“master”) based on the list of the given
The leader Starter is chosen as follows:
- If there are no
--starter.joinarguments, the Starter becomes the leader.
- If there are multiple
--starter.joinarguments, these arguments are sorted. If a Starter is the first in this sorted list, it becomes the leader.
- In all other cases, the Starter becomes a follower.
Note: Once the bootstrap phase is over (all
arangod processes have started and
are running), the bootstrap phase ends and the Starters use the ArangoDB Agency
to elect a leader for the runtime phase.
Using the ArangoDB Starter in Docker
The Starter can also be used to launch clusters based on ArangoDB Docker containers.
If you use
arangodb in a Docker container, it runs all servers in a Docker
arangodb/arangodb:latest Docker image by default. If you wish to run
a specific Docker image for the servers, specify it using the
If you use Docker, it is important to care about the volume mappings on the container. Typically, you start the executable in Docker with the following commands:
export IP=<IP of docker host> docker volume create arangodb1 docker run -it --name=adb1 --rm -p 8528:8528 \ -v arangodb1:/data \ -v /var/run/docker.sock:/var/run/docker.sock \ arangodb/arangodb-starter \ --starter.address=$IP
If you are running on Linux, it is also possible to use a host-mapped volume
instead of creating a Docker volume. Make sure to map it to
To run the other instances, adjust the volume and container names and
additionally specify the join address of the first instance (replace
the respective number and
A with the host address):
export IP=<IP of docker host> docker volume create arangodbN docker run -it --name=adbN --rm -p 8528:8528 \ -v arangodbN:/data \ -v /var/run/docker.sock:/var/run/docker.sock \ arangodb/arangodb-starter \ --starter.address=$IP \ --starter.join A
If you use the Enterprise Edition Docker image, you have to set the license key
in an environment variable by adding this option to the above
<the-key> with the actual license key):
The Starter hands the license key to the Docker containers it launches for ArangoDB.
You can get a free evaluation license key by visiting:
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 certificates handed to it, so that the above command is modified as follows:
export IP=<IP of docker host> export DOCKER_CERT_PATH=/path/to/certificate docker volume create arangodbN docker run -it --name=adbN --rm -p 8528:8528 \ -v arangodbN:/data \ -v /var/run/docker.sock:/var/run/docker.sock \ -v $DOCKER_CERT_PATH:$DOCKER_CERT_PATH \ -e DOCKER_TLS_VERIFY=1 \ -e DOCKER_CERT_PATH=$DOCKER_CERT_PATH \ arangodb/arangodb-starter \ --starter.address=$IP
Note that the environment variables
as well as the additional mountpoint containing the certificate have been added above.
The assignment of
DOCKER_CERT_PATH is optional, in which case it
is mandatory that the certificates are stored in
the command would then be as follows:
export IP=<IP of docker host> docker volume create arangodbN docker run -it --name=adbN --rm -p 8528:8528 \ -v arangodbN:/data \ -v /var/run/docker.sock:/var/run/docker.sock \ -v /path/to/cert:/root/.docker \ -e DOCKER_TLS_VERIFY=1 \ arangodb/arangodb-starter \ --starter.address=$IP
Under the Hood
arangodb you run becomes the leader of your Starter setup
(also called master), the other
arangodb instances become the
followers of your Starter setup. This is not to be confused with the
Leader/Follower replication of ArangoDB. The terms above refer to the Starter setup.
The Starter leader determines which ArangoDB server processes to launch on which Starter follower, and how they should communicate.
It then launches the server processes and monitors them. Once it has detected that the setup is complete, you get the prompt.
The Starter leader saves the setup for subsequent starts.