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 {/* #get-defradb */}

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

### Download binaries {/* #binaries */}

[Download the executable](https://github.com/sourcenetwork/defradb/releases) 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 {/* #build */}

Building DefraDB locally requires [Go](https://golang.org/) >= 1.24 and Git.

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

This will produce a `defradb` binary in your [Go workspace](https://go.dev/wiki/SettingGOPATH). To be able to run `defradb` commands, ensure `$GOPATH/bin` is included in your `PATH`:

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

:::note
The [DefraDB Explorer](https://github.com/sourcenetwork/defradb-explorer) is included in [pre-compiled binaries](#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 {/* #docker */}

To run DefraDB in a Docker container, use one of the [official images](https://ghcr.io/sourcenetwork/defradb).
The environment variable `DEFRA_KEYRING_SECRET` is used to initialize [DefraDB's keys](/references/keys.md), so set it to a value that you will later have access to.

```shell
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](#verify-connection).

## Start DefraDB {/* #start */}

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.

```shell title="Generate and store secret into .env file"
echo "DEFRA_KEYRING_SECRET=$(openssl rand -base64 32)" > .env
```

```shell title="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](/references/keys.md).
:::

## Verify connection {/* #verify-connection */}

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

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

An online node responds with `"Healthy"`.