Getting started

Install

applies to v0.5.1

LuraDB installs as one Debian package. apt resolves the runtime dependencies, creates the luradb system user, generates an admin API key and enables the systemd service without starting it, so you can review the configuration before LuraDB runs for the first time.

LuraDB needs Linux on amd64 with kernel 6.1 or newer, and systemd if you install the package. On a Windows machine it runs in WSL or in Docker Desktop, see Windows.

What the host needs

Requirement	Why
Linux on amd64	The server is built on `io_uring` and ships for this platform only.
Kernel 6.1 or newer	LuraDB’s `io_uring` rings use `DEFER_TASKRUN`. On an older kernel the service does not start and logs `LuraDB requires Linux kernel 6.1 or newer (io_uring DEFER_TASKRUN)`.
systemd	The package installs and enables a systemd service. Docker and a source build do not need it.
`libc6` 2.34 or newer and `adduser`	The package depends on both; `apt` installs them.

Check the kernel first:

uname -r

Install the Debian package

Download luradb_<version>-1_amd64.deb from the GitHub releases and install it with apt, which resolves the dependencies:

sudo apt install ./luradb_0.5.1-1_amd64.deb

On the first install the package:

creates the system user luradb (no login, no home directory);
writes /etc/luradb/luradb.toml, owned by root:luradb with mode 640, because it contains the admin key;
generates a random admin API key and puts it into that file;
creates /etc/luradb/tls, where you put a certificate if you turn on HTTPS;
enables the service for the next boot, but does not start it.

A notice at the end of the install says where the configuration lives and how to start:

LuraDB is installed but not started.

  Config:  /etc/luradb/luradb.toml
  Data:    /var/lib/luradb
  Start:   sudo systemctl start luradb

Review the config before the first start (bind address, data paths, admin API key).
The service is enabled and starts automatically on the next boot.

The service does not start by itself so that you can look at the configuration first. The first start creates the data files under /var/lib/luradb; where exactly is set by storage.wal_path, storage.sstable_dir and the other keys of [storage] in the configuration reference.

Start the service and read the admin key

sudo systemctl start luradb
systemctl status luradb
journalctl -u luradb -f

The log shows how the cores were split and on which address the server listens. The admin key stays in the configuration file; read it with:

sudo grep api_key /etc/luradb/luradb.toml

api_key = "lura_…"

A key starts with lura_ and is followed by 32 hexadecimal digits. The package generates it once; it stays the same across updates and reinstalls. Every request except /health sends it as a Bearer token. The examples in this handbook read it from a shell variable:

KEY=lura_…   # your admin key from /etc/luradb/luradb.toml

Check that it answers

/health needs no key. A second request with the key shows who you are:

curl -s http://127.0.0.1:3000/health
curl -s http://127.0.0.1:3000/store-api/auth/whoami -H "Authorization: Bearer $KEY"

{
  "domain_count": 1,
  "estimated_memtable_keys": 1,
  "l0_sstable_count": 0,
  "resources": { "disk_state": "ok", "memory_state": "ok", "state": "ok" },
  "shards": [{ "id": 0, "status": "ok" }],
  "status": "ok",
  "uptime_secs": 0,
  "version": "0.5.1",
  "vlog_size_bytes": 0
}

{ "name": "admin", "role": "Admin" }

The shards list has one entry per data shard; the example host has four cores and therefore one shard, see Multicore. Without the key, any other request answers 401 Unauthorized.

By default the server listens on 127.0.0.1:3000, see server.bind_address and server.port. Turning authentication off with auth.enabled is only accepted on a loopback address: with another bind address the start is refused with auth.enabled = false and server.bind_address = '0.0.0.0' is not loopback — enable auth (auth.enabled = true) or bind to loopback (127.0.0.1 / ::1).

Change the configuration

sudoedit /etc/luradb/luradb.toml
sudo systemctl restart luradb

The server reads the file once at start; a change takes effect with a restart. luradb.toml is a dpkg conffile: your changes survive updates, and dpkg asks what to do when your file and the new package version both changed. Every key is explained in the configuration reference.

Run it in Docker

The Docker setup is a way to try LuraDB on any machine; it is not a distribution image. It builds an image from a .deb you provide, so nothing is compiled and the host needs no package install.

Clone the repository and put a luradb_*.deb from the releases into target/debian/:
Terminal window
```
git clone https://github.com/hwein/luradb.git
mkdir -p luradb/target/debian
```
Build the image and start the container:
Terminal window
```
cd luradb/packaging/docker
docker compose up -d
```
When the container is healthy, check it:
Terminal window
```
curl http://localhost:3000/health
```

A container shares the kernel of its host (with Docker Desktop, the kernel of its virtual machine), so that kernel must be 6.1 or newer as well; docker run --rm ubuntu:24.04 uname -r shows it. Docker’s default seccomp profile blocks the io_uring calls LuraDB needs; compose.yaml therefore sets seccomp=unconfined, which is why a plain docker run fails at start.

The container generates the admin key on its first start and prints it once:

docker compose logs luradb | grep "admin api key"

Later starts reuse the key from the etc volume; read it back with docker compose exec luradb grep api_key /etc/luradb/luradb.toml. To use a key of your own, set LURADB_ADMIN_KEY in the container’s environment before the first start. The Swagger UI is on in this setup, and the port is published on 127.0.0.1 only. The service and the container in operation are described in systemd and Docker.

Windows: WSL or Docker Desktop

LuraDB does not run on Windows itself. Two ways put a Linux kernel on a Windows machine, and both meet the kernel requirement:

WSL 2 runs a Linux distribution on a kernel that Microsoft ships with WSL; wsl --version in PowerShell shows its version, and current WSL releases ship 6.6 or newer. Install Ubuntu, open it, and follow Install the Debian package inside it:

wsl --install -d Ubuntu-24.04

Ubuntu’s WSL images start systemd by default; systemctl is-system-running answers running. If it does not, put systemd=true under [boot] in /etc/wsl.conf, then wsl --shutdown in PowerShell and open the distribution again. WSL forwards the port to Windows, so http://localhost:3000/health also answers in a browser or in PowerShell. The distribution, and the service with it, stops a short while after its last terminal closes; opening a terminal starts both again.

Docker Desktop uses WSL 2 as well, so its containers share that kernel; docker info --format '{{.KernelVersion}}' shows it. Follow Run it in Docker in PowerShell or in a WSL terminal, docker compose behaves the same in both.

Build from source

The toolchain is pinned in rust-toolchain.toml; rustup picks it up.

git clone https://github.com/hwein/luradb.git
cd luradb
git checkout v0.5.1
cargo build --release

The binary is target/release/luradb. To build the package, install cargo-deb and dpkg-dev and run cargo deb; the package lands in target/debian/.

Started without --config, the binary reads ./luradb.toml if it exists, otherwise /etc/luradb/luradb.toml, otherwise it runs with built-in defaults. With the defaults, authentication is off, the server listens on 127.0.0.1:3000 and the data files go to the current directory; the log says so:

INFO luradb: No config file found at luradb.toml, using defaults
WARN luradb: auth.enabled is false — the server is unauthenticated. Allowed only because server.bind_address (127.0.0.1) is loopback-only.

Command line

Option	Effect
`--config <path>`	Reads the configuration from this file.
`--migrate-shards <N>`	Changes the number of data shards of the data directory to `N` while the server is stopped, see Upgrading.
`--dump-openapi`	Prints the OpenAPI contract as JSON and exits.