Deployment & Configuration

tip

For the full list of configuration settings, see Reference -> Configuration.

Root directory

DefraDB's root directory is located at ~/.defradb/ on UNIX and at %USERPROFILE%\.defradb​ on Windows. Among other things, it contains the data, keys, and configuration file. To specify a different path for the root directory, use the CLI option --rootdir when starting the instance.

Set up Access Control Policies

To restrict what different users are allowed to do, set up appropriate document access control policies.

Ports

DefraDB uses two ports:

1. HTTP API port (default 9181). Customizable via the CLI option --url or the config setting api.address when starting the instance.
2. P2P port (default 9171). Customizable via the CLI option --p2paddr or the config setting net.p2paddresses when starting the instance.

Start DefraDB listening on ports 9172 and 9182

defradb start --url localhost:9182 --p2paddr /ip4/127.0.0.1/tcp/9172

External port binding

By default, the HTTP API and P2P network use localhost. To expose the ports externally, specify the addresses in the config or command line parameters:

defradb start --p2paddr /ip4/0.0.0.0/tcp/9171 --url 0.0.0.0:9181

Secure the HTTP API with TLS

The HTTP API is exposed unencrypted by default, but you can configure it to use TLS.

DefraDB will automatically start with TLS if a valid key pair is found at paths ~/.defradb/certs/server.crt and ~/.defradb/certs/server.key. To enable TLS with keys located in custom paths, start the instance providing their paths with the flags --pubkeypath and --privkeypath:

Enable TLS for HTTP API with custom key paths

defradb start --pubkeypath ~/.defradb/certs/pubkey.crt --privkeypath ~/.defradb/certs/privkey.key

generate a self-signed certificate

mkdir -p ~/.defradb/certs
openssl ecparam -genkey -name secp384r1 -out ~/.defradb/certs/server.key
openssl req -new -x509 -sha256 -key ~/.defradb/certs/server.key -out ~/.defradb/certs/server.crt -days 365

TLS and CLI commands

The defradb CLI commands don't support connection to instances with TLS enabled.

Set up peer-to-peer synchronization

By default, DefraDB starts with its P2P features active. For information on how to set up P2P, see Synchronize documents across multiple nodes.

disable p2p

Disable P2P on an instance by starting it with the --no-p2p flag.

defradb start --no-p2p

Support Cross-Origin Resource Sharing (CORS)

Because DefraDB doesn't have any allowed origins set by default, you may face a Cross-Origin Resource Sharing (CORS) error when accessing DefraDB through a frontend interface. Specify allowed origins when starting the database:

defradb start --allowed-origins=https://yourdomain.com

For frontend apps running on localhost, allowed origins must include the application's port:

defradb start --allowed-origins=http://localhost:3000

tip

The catch-all * is also a valid origin.

Telemetry

DefraDB has no telemetry reporting by default. To enable OpenTelemetry in DefraDB you must build the binary with the telemetry tag set. To configure the HTTP exporters, use the environment variables described in the metric exporter documentation and trace exporter documentation.