Install

To get a running instance of DefraDB, you need to source the defradb executable and start a node. The process is similar to that of any other software, except it's much nicer because it's a binary you really want, and because it was built 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 CLI commands, place the binary in a directory included in your PATH. On UNIX systems, a common choice is to put 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

The DefraDB Explorer is included in pre-compiled binaries but not in manual builds.

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. 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 creates the necessary keys when starting it for the first time, storing them securely in the defradb keyring. The environment variable DEFRA_KEYRING_SECRET holds 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

Verify the local connection to the node by pinging the /health-check HTTP endpoint:

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

An online node responds with "Healthy".