ArangoDB v3.8 reached End of Life (EOL) and is no longer supported.
This documentation is outdated. Please see the most recent version at docs.arangodb.com
Using the ArangoDB Starter
This section describes how to start an Active Failover setup the tool Starter (the arangodb binary program).
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
Local Tests
If you want to start a local Active Failover setup quickly, use the --starter.local
option of the Starter. This will start all servers within the context of a single
starter process:
arangodb --starter.local --starter.mode=activefailover --starter.data-dir=./localdata --auth.jwt-secret=/etc/arangodb.secret --agents.agency.supervision-grace-period=30
Please adapt the path to your secret file accordingly.
Note that to avoid unnecessary failovers, it may make sense to increase the value
for the startup option --agents.agency.supervision-grace-period
to a value
beyond 30 seconds.
Note: When you restart the Starter, it remembers the original --starter.local
flag.
Multiple Machines
If you want to start an Active Failover setup using the Starter, you need to copy the
secret file to every machine and use the --starter.mode=activefailover
option of the
Starter. A 3 “machine” Agency is started as well as 3 single servers,
that perform asynchronous replication and failover:
arangodb --starter.mode=activefailover --starter.data-dir=./data --auth.jwt-secret=/etc/arangodb.secret --agents.agency.supervision-grace-period=30 --starter.join A,B,C
Please adapt the path to your secret file accordingly.
Note that to avoid unnecessary failovers, it may make sense to increase the value
for the startup option --agents.agency.supervision-grace-period
to a value
beyond 30 seconds.
Run the above command on machine A, B & C.
Once all the processes started by the Starter are up and running, and joined the Active Failover setup (this may take a while depending on your system), the Starter will inform you where to connect the Active Failover from a Browser, shell or your program.
For a full list of options of the Starter please refer to this section.
Using the ArangoDB Starter in Docker
The Starter can also be used to launch an Active Failover setup based on Docker
containers. To do this, you can use the normal Docker arguments, combined with
--starter.mode=activefailover
:
export IP=<IP of docker host>
docker volume create arangodb
docker run -it --name=adb --rm -p 8528:8528 \
-v arangodb:/data \
-v /var/run/docker.sock:/var/run/docker.sock \
arangodb/arangodb-starter \
--agents.agency.supervision-grace-period=30 \
--starter.address=$IP \
--starter.mode=activefailover \
--starter.join=A,B,C
Run the above command on machine A, B & C.
Note that to avoid unnecessary failovers, it may make sense to increase the value
for the startup option --agents.agency.supervision-grace-period
to a value
beyond 30 seconds.
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 server
instance should not be started.
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 docker
command:
-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 start
will then hand on the license key to the Docker containers it launches
for 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 certificates handed to it, so that the above command is modified as follows:
export IP=<IP of docker host>
export DOCKER_TLS_VERIFY=1
export DOCKER_CERT_PATH=/path/to/certificate
docker volume create arangodb
docker run -it --name=adb --rm -p 8528:8528 \
-v arangodb:/data \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /path/to/certificate:/path/to/certificate
arangodb/arangodb-starter \
--agents.agency.supervision-grace-period=30 \
--starter.address=$IP \
--starter.mode=activefailover \
--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
. So
the command would then be as follows
export IP=<IP of docker host>
docker volume create arangodb
docker run -it --name=adb --rm -p 8528:8528 \
-v arangodb:/data \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /path/to/cert:/root/.docker \
-e DOCKER_TLS_VERIFY=1 \
arangodb/arangodb-starter \
--agents.agency.supervision-grace-period=30 \
--starter.address=$IP \
--starter.mode=activefailover \
--starter.join=A,B,C