Node configuration

Available since: v4.0.0

This page is the reference for configuring a SurrealDS node that you run yourself. The Kubernetes operator writes this configuration for you. For a step-by-step setup, see Run SurrealDS on your own machines.

The surrealds:// path

A node is a surreal start process whose datastore path starts with surrealds://:

surreal start --bind 0.0.0.0:8000 "surrealds://?config=/opt/surrealdb/etc/node.json"

The path has four forms:

Put the path in quotes in a shell, because ? and & are special characters.

These options can follow the path, for example surrealds://?config=/opt/surrealdb/etc/node.json&versioned=true:

With a configuration file or environment variables, the node takes the rest of its settings from there. Options for a single node with no peers, such as sync and create, have no effect on a node that uses a configuration file.

Configuration sources

Configure a node with a JSON file, or with environment variables. Do not use both: a node that names a file refuses to start if a configuration variable is also set.

An empty variable is an error, and the node does not use the default for it.

Minimal configuration file

A node of a three-node group needs at least this:

{
  "node": {
    "scope": 1,
    "node": 1,
    "zone": "zone-a",
    "storage": { "kind": "disk", "path": "/opt/surrealdb/data/log" },
    "class": { "barrier": true, "cross_zone": true },
    "create": true
  },
  "listen": "0.0.0.0:7400",
  "admin": "0.0.0.0:7401",
  "peers": [
    { "node": 2, "zone": "zone-b", "host": "10.0.0.12", "port": 7400, "server_name": "shale-2", "cert": "/opt/surrealdb/tls/node-2.crt", "admin": "10.0.0.12:7401" },
    { "node": 3, "zone": "zone-c", "host": "10.0.0.13", "port": 7400, "server_name": "shale-3", "cert": "/opt/surrealdb/tls/node-3.crt", "admin": "10.0.0.13:7401" }
  ],
  "tls": {
    "cert": "/opt/surrealdb/tls/node-1.crt",
    "key": "/opt/surrealdb/tls/node-1.key",
    "ca": "/opt/surrealdb/tls/ca.crt"
  },
  "object": {
    "kind": "s3",
    "bucket": "surrealds",
    "prefix": "production",
    "endpoint": "https://s3.example.com",
    "region": "us-east-1"
  }
}

The object store credentials are never in the file. Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY in the node's environment.

node fields

Host fields

The other fields, such as the lease and timeout settings, have defaults that suit most groups. Do not change them unless SurrealDB support asks you to.

Peers

Every node lists every other node of the group. A node does not list itself, and each id appears once.

With SURREALDS_PEERS, write each peer as node:zone:host:port:server_name:cert[:admin_port] and separate peers with commas. This form cannot hold an IPv6 address.

TLS

A node with peers must have TLS. It cannot be turned off.

• •

  All nodes of a group use certificates from one certificate authority.

• •

  The certificate of node <id> must carry the DNS name shale-<id>, and allow both server and client authentication.

• •

  The private key must be a PEM file in PKCS#8 format (-----BEGIN PRIVATE KEY-----).

• •

  Each node needs the certificate files of all its peers. A node trusts a peer by that peer's exact certificate, so a new certificate for a node changes its identity for the rest of the group.

The certificate script in Make the TLS certificates creates files in this format.

Object store

All nodes of a group must use the same store, bucket and prefix. A prefix holds one database: use a new prefix for a new group, and never point two groups at the same prefix.

The store must support conditional writes with the If-Match and If-None-Match request headers. Amazon S3, Cloudflare R2 and MinIO do. If the store does not compare If-Match correctly, the node's first write to the store fails. A store that compares unquoted If-Match values needs "unquoted_if_match": true.

Zone policy

Under both values, the acking witness is never in the same zone as the sequencer. Give each node a different zone label only where the machines do not share a failure, such as one power supply or one network switch.

Commit log barrier

log_sync sets how each commit log write is made durable.

Admin endpoint

The admin endpoint listens on the admin address.

Allow the admin port only from the other nodes and from your monitoring hosts, or set admin_token.

The SurrealDB server on port 8000 also answers GET /health, and its GET /ready includes the licence state.

Ports