Installation

FrogDB ships as a single frogdb-server binary. FrogDB is pre-release software — no tagged release has published binaries, container images, or packages yet, so every path below builds the binary or image locally from this repository. Pick Docker for the fastest path to a running server, Debian/Ubuntu if you want a systemd-managed install, or build from source if you’re contributing or want full control over the build.

Docker

Note

No FrogDB image has been published to a registry yet (the release pipeline that pushes to docker.io/frogdb/frogdb and ghcr.io runs only on tagged releases). Build the image locally instead — it takes one command once the cross-compilation toolchain is installed.

1. Install the cross-compilation toolchain (once):

   just cross-install

   This installs cargo-zigbuild, used to cross-compile frogdb-server for Linux from any host.

2. Build the image:

   just docker-cross-build

   This cross-compiles a release binary for x86_64-unknown-linux-gnu, then runs docker build against frogdb-server/docker/Dockerfile, tagging the result frogdb:latest.

3. Run it:

   docker run -d --name frogdb \
     -p 6379:6379 \
     -v frogdb-data:/data \
     frogdb:latest

   The image bundles redis-cli (via the Debian redis-tools package), so you can exec into the container to use it, or connect from the host as shown in Verify the install.

Configuration via environment variables (see frogdb-server/docker/Dockerfile for the full list):

docker run -d --name frogdb \
  -p 6379:6379 \
  -v frogdb-data:/data \
  -e FROGDB_SERVER__BIND=0.0.0.0 \
  -e FROGDB_PERSISTENCE__DATA_DIR=/data \
  frogdb:latest

Docker Compose:

services:
  frogdb:
    image: frogdb:latest
    ports:
      - "6379:6379"
    volumes:
      - frogdb-data:/data
    environment:
      FROGDB_SERVER__BIND: "0.0.0.0"
      FROGDB_PERSISTENCE__DATA_DIR: /data
    healthcheck:
      test: ["CMD", "redis-cli", "-p", "6379", "PING"]
      interval: 5s
      retries: 10

volumes:
  frogdb-data:

Debian / Ubuntu

Caution

No .deb package has been published to GitHub Releases yet — the release pipeline’s packaging job runs only on tagged releases and requires nfpm, which isn’t part of this repo’s normal dev toolchain. If you just want a running server, use Docker or Build from Source above/below instead. The steps here build the package locally, the same way the release pipeline does.

1. Build the binaries:

   cargo build --release --bin frogdb-server --bin frogctl --bin frogdb-admin

2. Regenerate the packaging files (nfpm config, default frogdb.toml, systemd unit, install scripts) from the current config source:

   just deb-gen

3. Install nfpm and build the package:

   go install github.com/goreleaser/nfpm/v2/cmd/nfpm@latest
   
   cp target/release/frogdb-server target/release/frogctl target/release/frogdb-admin \
     frogdb-server/ops/deploy/deb/
   
   cd frogdb-server/ops/deploy/deb
   ARCH=$(dpkg --print-architecture)
   VERSION=$(awk -F'"' '/^version:/{print $2}' nfpm.yaml)
   nfpm package \
     --config nfpm.yaml --packager deb \
     --target frogdb-server_${VERSION}_${ARCH}.deb

4. Install and start:

   sudo dpkg -i frogdb-server_*.deb

   The package’s postinstall script creates a frogdb system user, then enables and starts frogdb-server.service automatically. No manual systemctl step is needed, though sudo systemctl status frogdb-server is useful to confirm it.

The package installs:

What	Path
Server binary	/usr/bin/frogdb-server
frogctl (operational CLI)	/usr/bin/frogctl
frogdb-admin CLI	/usr/bin/frogdb-admin
Config file	/etc/frogdb/frogdb.toml
systemd unit	/usr/lib/systemd/system/frogdb-server.service
Data directory	/var/lib/frogdb (data at /var/lib/frogdb/data)
Logs	/var/log/frogdb

Build from Source

1. Install the Rust toolchain. The project pins its toolchain in rust-toolchain.toml (currently {versions.rust_toolchain}); running any cargo command inside the repo with rustup installed fetches that exact version automatically.

2. Install system dependencies. FrogDB needs libclang for bindgen (used by librocksdb-sys) and a C/C++ toolchain to compile RocksDB’s C++ sources; TLS is handled by a pure-Rust rustls stack, so no system OpenSSL is required. See Brewfile / shell.nix at the repo root for the full, current list.

   macOS:

   brew install llvm rocksdb

   llvm provides libclang. The Justfile defaults FROGDB_SYSTEM_ROCKSDB to 1, so the just build recipes below link against this Homebrew RocksDB by default — install it even though Brewfile labels it “optional,” or the default build will fail to find it. macOS builds also need DYLD_LIBRARY_PATH pointed at llvm; the just recipes set this for you automatically.

   Debian/Ubuntu:

   sudo apt install build-essential libclang-dev

   Arch Linux:

   sudo pacman -S base-devel clang

3. Clone and build:

   git clone https://github.com/nathanjordan/frogdb
   cd frogdb
   just release

   just release wraps cargo build --release with the environment variables from step 2 already set. The binary lands at target/release/frogdb-server. Prefer it over a bare cargo build --release so you don’t have to set those variables by hand.

   Tip

   just build recipes default to linking against a Homebrew-installed RocksDB (FROGDB_SYSTEM_ROCKSDB defaults to 1 in the Justfile, with a Homebrew library path) — that’s what step 2’s brew install rocksdb is for on macOS. On Linux, no system RocksDB path has been set up, so build from source instead by setting FROGDB_SYSTEM_ROCKSDB=0:

   FROGDB_SYSTEM_ROCKSDB=0 just release

Verify the install

frogdb-server --version

Start the server (see Quickstart for all the ways to do this), then from another terminal:

redis-cli -p 6379 PING
# PONG

redis-cli ships with Redis; install it via your package manager (e.g. brew install redis, apt install redis-tools) if you don’t already have it. It’s bundled in the Docker image.

Next steps

Quickstart Connect, run commands, enable persistence

Configuration Config surfaces, precedence, and runtime-mutable settings