Install

To get a running instance of DefraDB, you need to source the defradb executable and start a node. The process is similar to fetching any other binary, except it's much nicer because it's a binary you really want, and because we have built it with utmost care.

Get DefraDB

There's a few different options to obtain an executable of DefraDB.

Download binaries

Download the executable appropriate to your system.

To be able to run defradb commands, the binary must be located in a directory included in your PATH. On UNIX systems, a common choice is to place defradb in /usr/local/bin.

Build locally

Building DefraDB locally requires Go >= 1.24 and Git.

git clone https://github.com/sourcenetwork/defradb.git
cd defradb
make install

This will produce a defradb binary in your Go workspace. To be able to run defradb commands, ensure $GOPATH/bin is included in your PATH:

export PATH=$PATH:$(go env GOPATH)/bin

note

Although included in pre-compiled binaries, the DefraDB Explorer is not included in manual builds. It is built separately.

tip

The Go compiler requires substantial memory during compilation. Builds with less than 2 GB of available RAM will likely fail with out-of-memory errors.

Tips for building on resource-constrained systems

• For out-of-memory errors, use -p 1 to limit compiler parallelism:

  go build -p 1 ./cmd/defradb

• If /tmp is located on a small filesystem, redirect Go's temp directories to locations with more space:

  export GOTMPDIR=/path/with/space
  export GOCACHE=/path/with/space/go-cache
  export GOMODCACHE=/path/with/space/go-mod

• For extremely constrained environments, you can reduce memory usage by disabling optimizations (produces slower binary):

  go build -p 1 -gcflags="all=-N -l" ./cmd/defradb

Docker container

To run DefraDB in a Docker container, use one of the official images hosted on GitHub. The environment variable DEFRA_KEYRING_SECRET is used to initialize DefraDB's keys, so set it to a value that you will later have access to.

docker run \
  -e DEFRA_KEYRING_SECRET=secret \
  -p 9181:9181 \
  -p 9171:9171 \
  -name defradb \
  ghcr.io/sourcenetwork/defradb:latest \
  start

You don't have to start the database when using a Docker image – you can directly verify the connection.

Start DefraDB

The database provisions necessary keys when starting it for the first time, storing them securely in the defradb keyring. The environment variable DEFRA_KEYRING_SECRET provides the secret to generate keys and unlock the keyring. The variable can also be defined in a .env file located in the working directory, or at a filepath defined by the --secret-file flag.

Generate and store secret into .env file

echo "DEFRA_KEYRING_SECRET=$(openssl rand -base64 32)" > .env

Start the node

defradb start

tip

The keyring secret unlocks the identity and encryption keys for the local node, so you will need to provide it every time you start the node. For more information on keys, and on how to provide your own keys, see Keys setup.

Verify connection

To verify the local connection to the node, ping the /health-check HTTP endpoint:

wget -qO- http://localhost:9181/health-check

An online node responds with "Healthy".