TypeDB Configuration

You can configure a TypeDB server via two means: a YAML config file or command line options. Command line options override values defined in the config file.

For a full list of configurable properties run:

typedb server --help

This page lists & explains the available options.

General CLI arguments

General, non-configuration arguments available on the CLI.

General CLI arguments

--config <path-to-file>

Specify a custom configuration file

--help

-h

Show help message.

--version

-V

Print version information and exit.

Configuration file

By default, TypeDB looks for a config.yml file in the same folder as the TypeDB server executable (i.e., /server/config.yml). This path can be overridden using the CLI argument: --config <path-to-your-config>.

Command line overrides

When using the command line to override a specific option, all CLI arguments must:

  • start with the double dash prefix --,

  • be separated from their value (if any) either by an equals sign (--arg=val) or a whitespace (--arg val).

e.g., --server.listen-address=0.0.0.0:1730

Configuration options

Server

The server section of the configuration contains network and encryption options. For example, a server can be booted up to listen on 0.0.0.0:1730 by using this command:

typedb server --server.listen-address=0.0.0.0:1730

Listen vs. advertise addresses

Each public network endpoint has two addresses:

  • The listen address is what the server binds to locally — the interface and port where it accepts connections.

  • The advertise address is what the server reports back to clients (and, in clustered deployments, to peer servers). Clients use the advertise address to connect if it is presented.

When the server is reached directly, both can be the same. When the server sits behind a NAT, reverse proxy, or load balancer, the listen address is the local bind (often 0.0.0.0:<port>) and the advertise address is the externally-reachable host:port that clients should dial.

If advertise-address is omitted, the server does not report back any address to gRPC/HTTP connections. Then, the clients must not depend on the server’s information, using the initial connection address for further communication.

Multi-node environments must use advertise addresses for efficient failover logic execution on the client side.

Server

server.listen-address

Server gRPC listen host and port — the address the server binds to. Default value: 0.0.0.0:1729.
Alias (deprecated): server.address. Specifying both server.listen-address and server.address is rejected.

server.advertise-address

Server gRPC advertise host and port — the address shared with clients. Required when the listen and advertise addresses differ (e.g., behind a proxy or NAT).

server.http.enabled

Enable/disable HTTP endpoint. Default value: true.

server.http.listen-address

HTTP listen host and port — the address the server binds to. Cannot be the same as server.listen-address. Default value: 0.0.0.0:8000.
Alias (deprecated): server.http.address. Specifying both server.http.listen-address and server.http.address is rejected.

server.http.advertise-address

HTTP advertise URL shared with clients (include the scheme, e.g. http://127.0.0.1:8000 or https://typedb.example.com). Required when the listen and advertise addresses differ. Default value: derived from server.http.listen-address.

server.authentication.token-expiration-seconds

The amount of seconds generated authentication tokens will remain valid, specified in seconds. Default value: 14400 (4 hours).

Admin endpoint

TypeDB exposes a separate admin gRPC endpoint, bound to localhost only, used by the bundled typedb admin CLI tool to inspect and manage a running server (see TypeDB Admin Tool).

Server admin

server.admin.enabled

Enable/disable the localhost-only admin endpoint. Default value: true.

server.admin.port

Port for the admin endpoint on 127.0.0.1. Default value: 1728.

Encryption

Configure the TLS certificate & private-key to be used for inflight encryption.

Server encryption

server.encryption.enabled

Enable in-flight encryption. Do not specify this argument to leave it disabled.

server.encryption.certificate

Encryption certificate in PEM format. Must be supplied if encryption is enabled.

server.encryption.certificate-key

Encryption certificate key. Must be supplied if encryption is enabled.

server.encryption.ca-certificate

Encryption CA in PEM format. (Optional)

Storage

The storage section of the configuration contains the storage layer options.

For production use, it is recommended that the storage.data-directory is set to a path outside the $TYPEDB_HOME (directory with TypeDB server files). This helps to make the process of upgrading TypeDB easier.

Storage

storage.data-directory

Path to the user data directory. Defaults to within the server distribution under server/data.

Diagnostics

TypeDB optionally reports anonymous diagnostics to guide the development and optimisation of TypeDB. This data includes unexpected errors and occasional system status updates for number and size of databases, as well as numbers of transactions and queries executed per hour.

To see what information is being reported, enable and access the monitoring Web page of the server (e.g. localhost:4104/diagnostics?format=json).

See Diagnostics monitoring endpoint for the full list of Prometheus metrics exposed and how to scrape them.

Diagnostics

diagnostics.reporting.metrics

Enable usage metrics reporting by setting a boolean flag. Default value: true.

diagnostics.reporting.errors

Enable critical error reporting by setting a boolean flag. Default value: true.

diagnostics.monitoring.enable

Enable a diagnostics monitoring HTTP endpoint by setting a boolean flag. Default value: true.

diagnostics.monitoring.port

Port on which to expose the diagnostics monitoring endpoint. Default value: 4104.

Logging

You can configure the directory that TypeDB uses for server logs.

Logging

logging.directory

Path to the server logs directory. Defaults to within the server distribution under server/logs.

Host machine configuration

This section describes recommended changes to the host OS.

Open file limit

To support large data volumes, it is important to check the open file limit the operating system imposes. Some Unix distributions default to 1024 open file descriptors. This can be checked with the following command:

ulimit -n

We recommend this is increased to at least 50 000.