LioranDB TypeScript Series #2: Run LioranDB Locally with Docker and TypeScript

LioranDB TypeScript Series #2: Run LioranDB Locally with Docker and TypeScript

LioranDB TypeScript Series: Build with a developer-first document database powered by Rust and designed for TypeScript.

In Part 1, we looked at what LioranDB V2 is.

Now let’s actually run it.

By the end of this tutorial you’ll have:

• LioranDB running locally
• persistent database storage
• the official CLI installed
• the bootstrap password rotated
• a TypeScript application connected to the database

1. Start LioranDB

Make sure Docker is installed, then run:

docker run -d \
  --name liorandb \
  -p 27018:27018 \
  -p 27019:27019 \
  -p 27201:27201 \
  -v ldb-data:/var/lib/liorandb/data \
  liorandb/liorandb:pre-alpha

Enter fullscreen mode Exit fullscreen mode

LioranDB exposes three important ports:

Port Purpose 27018 HTTP API / driver 27019 gRPC 27201 Metrics

The ldb-data Docker volume keeps your database files outside the container lifecycle.

2. Find the bootstrap credentials

Check the server logs:

docker logs liorandb

Enter fullscreen mode Exit fullscreen mode

On the initial bootstrap you’ll receive an administrator account and temporary password.

It will look similar to:

liorandb-bootstrap:
username=admin
temporary_password=<generated-password>

Enter fullscreen mode Exit fullscreen mode

Treat this password as temporary.

3. Install the official CLI

npm install -g @liorandb/[email protected]

Enter fullscreen mode Exit fullscreen mode

You can now authenticate:

printf '%s' 'YOUR_TEMPORARY_PASSWORD' |
liorandb login admin --password-stdin

Enter fullscreen mode Exit fullscreen mode

Then rotate the bootstrap password:

liorandb change-password --password "YOUR_NEW_STRONG_PASSWORD"

Enter fullscreen mode Exit fullscreen mode

4. Install the TypeScript driver

Inside your Node.js project:

npm install @liorandb/[email protected]

Enter fullscreen mode Exit fullscreen mode

Create an environment variable containing your connection URI:

URI=liorandb://admin:[email protected]:27018/default

Enter fullscreen mode Exit fullscreen mode

If your password contains reserved URI characters such as @, #, %, / or :, URL-encode it before putting it inside the connection string.

5. Write your first document

import { LioranDBClient } from "@liorandb/driver";
import { config } from "dotenv";

config();

const client = await LioranDBClient.connect(process.env.URI!);

try {
  const db = client.db("default");
  const users = db.collection("users");

  const inserted = await users.insertOne({
    email: "[email protected]",
    active: true,
    age: 18,
  });

  const found = await users.findOne({
    email: "[email protected]",
  });

  console.log({
    insertedId: inserted.insertedId,
    found,
  });
} finally {
  await client.close();
}

Enter fullscreen mode Exit fullscreen mode

And that’s it.

You now have:

TypeScript application
        ↓
@liorandb/driver
        ↓
LioranDB HTTP API
        ↓
Rust database engine
        ↓
Persistent storage

Enter fullscreen mode Exit fullscreen mode

Docker Compose alternative

If you don’t want to maintain a long docker run command:

services:
  liorandb:
    image: liorandb/liorandb:pre-alpha
    container_name: liorandb
    restart: unless-stopped
    cpus: 2.0
    mem_limit: 3.5g

    ports:
      - "27018:27018"
      - "27019:27019"
      - "27201:27201"

    volumes:
      - ldb-data:/var/lib/liorandb/data

volumes:
  ldb-data:

Enter fullscreen mode Exit fullscreen mode

Start it with:

docker compose up -d

Enter fullscreen mode Exit fullscreen mode

Where to go next

You have a running database and a working TypeScript connection.

Next we’ll look at what that connection URI actually means, how transport selection works and how to correctly manage LioranDBClient.

Documentation: https://docs.liorandb.com
Solo Quickstart: https://docs.liorandb.com/docs/getting-started/solo
Website: https://liorandb.com
Creator: https://github.com/UltronTheAI

Previous: Part 1 → Meet LioranDB V2
Next: Part 3 → Connection Strings, Client Options & Lifecycle