Deploy ArangoDB

Deploy and Host ArangoDB on Railway

ArangoDB is a multi-model database: documents, graphs and key-value pairs live in one storage engine, queried with one language, AQL. A single query can filter JSON documents, walk a graph several hops deep and join the two results — work that otherwise needs a document store and a separate graph database wired together in application code. Teams use it for knowledge graphs, recommendation engines, fraud detection and permission models.

This template lets you deploy ArangoDB on Railway as a real cluster, not a single container. Eight services come up pre-wired: agent1, agent2 and agent3 form the RAFT agency holding cluster configuration, dbserver1 and dbserver2 store the shards and replicate to each other, coordinator1 and coordinator2 answer AQL queries and serve the web interface, and a Caddy gateway puts one public HTTPS URL in front of both coordinators. Each ArangoDB service has its own volume; only the gateway is reachable from the internet, and it needs authentication.

Getting Started with ArangoDB on Railway

Deploying creates the whole cluster at once: the agency elects a leader, the DB-Servers register with it, then the first coordinator bootstraps the system collections. Expect a minute or two before the public URL answers. The gateway domain serves the ArangoDB web interface login. Sign in as root with the password from ARANGODB_DEFAULT_ROOT_PASSWORD, readable on the coordinator1 service. The database applies it during bootstrap, so root never exists without a password and there is no shipped default to change.

After login you pick a database; start with _system. Open Nodes to confirm the cluster is whole — two Coordinators, two DB-Servers and three Agents, all green, one agent leading. Then create a database from Databases, add a collection, and run AQL under Queries. A good first check is a small edge collection and a named graph under Graphs, then a traversal: that exercises a coordinator, both DB-Servers and the agency in one request. Add users under Users before pointing an app at the cluster.

About Hosting ArangoDB

Self-hosting ArangoDB makes sense when your data is graph-shaped but your workload is not purely graph — a catalogue with recommendation edges, permissions layered over user documents, a supply chain where both parts and routes are queried. It also keeps the data in your own infrastructure.

Key capabilities:

• AQL, one declarative language across documents, graphs and key-value access, with joins and multi-hop traversals in a single statement
• Named graphs with a visual browser, shortest-path, k-paths and pattern matching
• ArangoSearch, full-text search and BM25/TF-IDF ranking in the same engine
• Sharding with synchronous replication and automatic failover
• Official drivers for JavaScript, Java, Python, Go, PHP, Rust and .NET

The cluster splits into three roles. The agency is a small RAFT-replicated store holding the cluster plan — which shard lives where, which server is healthy. Three agents give it a quorum, so one can be redeployed without stopping writes. DB-Servers hold the shards; at a replication factor of two every shard has a leader on one and a follower on the other, and a failure promotes the follower. Coordinators hold no data — they parse AQL, fan work to the DB-Servers and merge results, so two behind the gateway spread load and survive a redeploy.

Why Deploy ArangoDB on Railway

Railway handles the parts of a database cluster that are usually manual work:

• Private networking between all seven ArangoDB services, no ports exposed publicly
• A persistent volume per node, so shards and the agency survive restarts
• One managed HTTPS domain on the gateway, certificates included
• Health checks on the coordinators and DB-Servers, plus automatic restarts

Common Use Cases

• Knowledge graphs and RAG backends — keep documents and the relationships between entities in one place, then traverse from a match to its neighbours
• Recommendation engines — model users, items and interactions as a graph and answer "customers who bought this also bought" in a few lines of AQL
• Fraud and risk analysis — find rings of related accounts by walking shared devices, addresses or payment methods several hops out from a suspect record

Dependencies for ArangoDB

• arangodb:3.12 — the official image, used by all seven cluster services. Each one's role is set by its start command.
• caddy:2-alpine — the gateway, load balancing across both coordinators and serving /healthz.

Environment Variables Reference

Deployment Dependencies

• Source: github.com/arangodb/arangodb
• Image: hub.docker.com/_/arangodb
• Documentation: docs.arangodb.com

Hardware Requirements for Self-Hosting ArangoDB

Per service. Agents and coordinators are light; DB-Servers hold the data.

ArangoDB sizes its caches and query memory limits from the machine it detects, so in a container it must be told the real limit. This template reads that from the cgroup at startup and passes it through ARANGODB_OVERRIDE_DETECTED_TOTAL_MEMORY and ARANGODB_OVERRIDE_DETECTED_NUMBER_OF_CORES, so resizing a service retunes it.

Self-Hosting ArangoDB with Docker

A single node is enough to try AQL locally. This starts one on port 8529:

docker run -d --name arangodb -p 8529:8529 \
  -e ARANGO_ROOT_PASSWORD=changeme \
  -v arangodb_data:/var/lib/arangodb3 \
  arangodb:3.12

Open http://localhost:8529 and sign in as root. In the cluster shape this template deploys, each process takes its role from flags. An agent looks like this:

arangod --agency.activate true --agency.size 3 \
  --agency.endpoint tcp://agent1:8531 \
  --agency.endpoint tcp://agent2:8531 \
  --agency.endpoint tcp://agent3:8531 \
  --agency.my-address tcp://agent1:8531 \
  --server.endpoint tcp://[::]:8531 \
  --server.jwt-secret-keyfile /secrets/jwt \
  --database.directory /var/lib/arangodb3/agent

DB-Servers and coordinators take --cluster.my-role PRIMARY or COORDINATOR, with --cluster.agency-endpoint pointing at the same three agents.

Is ArangoDB Free to Self-Host?

ArangoDB is source-available. Version 3.12 ships under the Business Source License 1.1, and the prepackaged builds fall under the ArangoDB Community License: free for internal production use, clusters included, capped at a 100 GiB dataset and three clusters. Offering ArangoDB itself as a service needs a commercial licence, and from 3.12.5 the community build carries the full Enterprise feature set. There is no licence fee for this template — on Railway you pay for the compute, memory and storage the eight services use.

FAQ

What is ArangoDB? A source-available, multi-model database storing documents, graphs and key-value data in one engine, queried with AQL, its declarative query language.

What does this Railway template deploy? A complete ArangoDB cluster: a three-node agency, two DB-Servers with synchronous replication, two coordinators, and a Caddy gateway load balancing the public HTTPS URL across both.

Why does the template include three agent services? The agency is RAFT-based and needs an odd number of members to hold a majority. Three lets one be redeployed while the cluster keeps accepting writes; a single agent makes every restart an outage.

Why are there two DB-Servers instead of one? ArangoDB creates its system collections with a replication factor of two, so a second DB-Server is required for the cluster to finish bootstrapping. It also gives every shard a follower, so losing a node loses no data.

How do I connect an application to self-hosted ArangoDB? Point any official driver at the gateway's HTTPS domain with the root credentials, or a user you create in the web interface. From another Railway service in the same project, use coordinator1.railway.internal:8529 to keep traffic off the public internet.

How do I add more capacity to self-hosted ArangoDB? Raise CPU, memory or volume size on the DB-Servers from the Railway dashboard. To add a DB-Server, duplicate one with the same variables and a new ARANGO_MY_ADDRESS; it registers with the agency at startup and ArangoDB rebalances shards onto it.