ArangoDB Starter - starts ArangoDB clusters & single servers with ease.
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
.vscode Fixes & docs Oct 12, 2017
client Added force option Jul 19, 2018
deps Updated go-certificates & go-driver Aug 21, 2018
docs Doc - Upgrading Starter - Fix download link Jan 16, 2019
examples Added example for running starter+arangosync locally Jul 16, 2018
pkg Using callback from agency and less reads Jul 18, 2018
service Merge pull request #214 from arangodb-helper/feature/jwt-secret-keyfile Jan 17, 2019
test Fix compilation. Dec 4, 2018
tools/release Build linux arm64 executable. Dec 14, 2018
.envrc Extended tests May 5, 2017
.gitignore Fixed excluding arangodb Jan 29, 2018
.travis.yml Fix 3.2 images Jun 22, 2018 Changelog entry. Dec 4, 2018
Dockerfile Changing default base port to 8528 May 5, 2017
LICENSE Added missing LICENSE file May 5, 2017 Update CHANGELOG for another release try. Oct 22, 2018
Makefile Build linux arm64 executable. Dec 14, 2018 Update email address Jun 28, 2018 Updated TODO May 9, 2017
VERSION Updated to 0.13.10+git Dec 4, 2018
auth.go Added "--auth.user" option to auth commands Jun 29, 2018
certificates.go Updated logging component. Added log-2-file support Jun 22, 2018
docker.go Added auto-ID support for docker-ce Jan 22, 2018
help.go Docs: Enterprise Edition hint box and unified use of name (#185) Jul 31, 2018
main.go starter to deploy in tls verified docker service Jan 9, 2019
remove.go Added force option Jul 19, 2018
start.go Added `arangodb upgrade` command Jul 17, 2018
stop.go Added `arangodb upgrade` command Jul 17, 2018
upgrade.go Removed force flag Jul 18, 2018

Starting an ArangoDB cluster or database the easy way

Docker Pulls GoDoc

Downloading Releases

You can download precompiled arangodb binaries via the github releases page.

Note: arangodb is also included in all current distributions of ArangoDB.


If you want to compile arangodb yourselves just do:

go get -u

This will result in a binary at $GOPATH/bin/arangodb.

For more advanced build options, clone this repository and do:

make local

and the executable is in ./bin named after the current OS & architecture (e.g. arangodb-linux-amd64). You can copy the binary anywhere in your PATH. A link to the binary for the local OS & architecture is made to ./arangodb. This program will run on Linux, OSX or Windows.

Note: The standard build uses a docker container to run the build. If docker is not available make local runs the go compiler directly and places the binary directly in the project directory. In this case you need to install the golang package on your system (version 1.7 or higher).

Building docker image

If you want to create the arangodb/arangodb-starter docker container yourselves you can build it using:

make docker

Starting a cluster

Install ArangoDB in the usual way as binary package. Then:

On host A:


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

arangodb --starter.join A

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

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, a coordinator and a dbserver and the cluster is up. Ports are shown on the console, the starter uses the next few ports above the starter port. That is, if one uses port 8528 for the starter, the coordinator will use 8529 (=8528+1), the dbserver 8530 (=8528+2), and the agent 8531 (=8528+3). See below under --starter.port for how to change the starter default port.

Additional servers can be added in the same way.

More usage info

See the ArangoDB Starter Tutorial.



Future plans

  • Allow starter with agent to be removed from cluster
  • Enable cluster to be updated in a controlled manner.

Technical explanation as to what happens

The procedure is essentially that the first instance of arangodb (aka the "master") offers an HTTP service on port 8528 for peers to register. Every instance that registers becomes a slave. As soon as there are cluster-agency-size peers, every instance of arangodb starts up an agent (if it is one of the first 3), a DBserver, and a coordinator. The necessary command line options to link the arangod instances up are generated automatically. The cluster bootstraps and can be used.

Whenever an arangodb instance shuts down, it shuts down the arangod instances under its control as well. When the arangodb is started again, it recalls the old configuration from the setup.json file in its data directory, starts up its arangod instances again (with their data) and they join the cluster.

All network addresses are discovered from the HTTP communication between the arangodb instances. The ports used 8529(/8539/8549) for the coordinator, 8530(/8540/8550) for the DBserver, 8531(/8541/8551) for the agent) need to be free. If more than one instance of an arangodb are started on the same machine, the second will increase all these port numbers by 10 and so on.

In case the executable is running in Docker, it will use the Docker API to retrieve the port number of the Docker host to which the 8528 port number is mapped. The containers started by the executable will all map the port they use to the exact same host port.


Feedback is very welcome in the form of github issues, pull requests or an email to