Ladybug Explorer

Browser-based user interface for the Ladybug graph database.

Get started

Ladybug Explorer is a web application that is launched from a deployed Docker image. Please refer to the Docker documentation for details on how to install and use Docker.

Below we show two different ways to launch Ladybug Explorer. Each of these options make Ladybug Explorer accessible on http://localhost:8000. If the launching is successful, you should see the logs similar to the following in your shell:

Access mode: READ_WRITE
Version of Ladybug: v0.12.2
Deployed server started on port: 8000

Option 1: Using an existing database

To access an existing Ladybug database, you can mount its path to the /database directory as follows:

docker run -p 8000:8000 \
           -v {path to the directory containing the database file}:/database \
           -e LBUG_FILE={database file name} \
           --rm lbugdb/explorer:latest

By mounting local database files to Docker via -v {path to the directory containing the database file} and -e LBUG_FILE={database file name}, the changes done in the UI will persist to the local database files after the UI is shutdown. If the directory is mounted but the LBUG_FILE environment variable is not set, Ladybug Explorer will look for a file named database.kz in the mounted directory or create a new database file named database.kz in the mounted directory if it does not exist.

The --rm flag tells docker that the container should automatically be removed after we close docker.

Option 2: Start with an empty database with example data

You can also launch Ladybug Explorer without specifying an existing database. Ladybug Explorer comes with bundled datasets that you can use to explore the basic functionalities of Ladybug. This is simply done by removing the -v flag in the example above. If no database path is specified with -v, the server will be started with an empty database.

docker run -p 8000:8000 --rm lbugdb/explorer:latest

Click on the Datasets tab on the top right corner and then: (i) you can select one of the bundled dataset of your choice from the drow-down menu; (ii) load it into Ladybug by clicking the "Load Dataset" button; and (iii) finally use Ladybug Explorer to explore it.

Additional launch configurations

Access mode

By default, Ladybug Explorer is launched in read-write mode, which means that you can modify the database. If you want to launch Ladybug Explorer in read-only mode, you can do so by setting the MODE environment variable to READ_ONLY as follows.

docker run -p 8000:8000 \
           -v {path to the directory containing the database file}:/database \
           -e LBUG_FILE={database file name} \
           -e MODE=READ_ONLY \
           --rm lbugdb/explorer:latest

In read-only mode, you can still issue read queries and visualize the results, but you cannot run write queries or modify the schema.

Buffer pool size

By default, Ladybug Explorer is launched with a maximum buffer pool size of 80% of the available memory. If you want to launch Ladybug Explorer with a different buffer pool size, you can do so by setting the LBUG_BUFFER_POOL_SIZE environment variable to the desired value in bytes as follows.

For example, to launch Ladybug Explorer with a buffer pool size of 1GB, you can run the following command.

docker run -p 8000:8000 \
           -v {path to the directory containing the database file}:/database \
           -e LBUG_FILE={database file name} \
           -e LBUG_BUFFER_POOL_SIZE=1073741824 \
           --rm lbugdb/explorer:latest

In-memory mode

By default, Ladybug Explorer is launched in disk-based mode. If you want to launch Ladybug Explorer in in-memory mode, you can do so by setting the LBUG_IN_MEMORY environment variable to true as follows.

docker run -p 8000:8000 \
           -e LBUG_IN_MEMORY=true \
           --rm lbugdb/explorer:latest

In in-memory mode, the database is stored in memory and all changes are lost when the server is shut down even if a database directory is mounted. Also, read-only access mode is not supported in in-memory mode.

WebAssembly mode

In WebAssembly mode, Ladybug Explorer is launched with @lbug/lbug-wasm, which runs all the queries directly in browser. If you want to launch Ladybug Explorer in WebAssembly mode, you can do so by setting the LBUG_WASM environment variable to true as follows.

docker run -p 8000:8000 \
           -e LBUG_WASM=true \
           --rm lbugdb/explorer:latest

In WebAssembly mode, the database is stored in the current browser session and all changes are lost when the browser tab is closed or when the tab is refreshed. All other configuration parameters are ignored in WebAssembly mode.

Dev builds

If you want to launch Ladybug Explorer with the latest development build of Ladybug, you can do so by using the dev tag instead of latest.

docker run -p 8000:8000 \
           -v {path to the directory containing the database file}:/database \
           -e LBUG_FILE={database file name} \
           --rm lbugdb/explorer:dev

The dev tag is updated daily, approximately two hours after the latest dev build of Ladybug is released.

Updating Ladybug Explorer

When a new version of Ladybug Explorer is released after the initial launch, re-launching the container WILL NOT automatically update the local image to the latest version. To update the local image to the latest version, you can run the following command.

docker pull lbugdb/explorer:latest

After pulling the latest image, you can re-launch the container with the same command as before.

Launch with Podman

If you are using Podman instead of Docker, you can launch Ladybug Explorer by replacing docker with podman in the commands above. However, note that by default Podman maps the default user account to the root user in the container. This may cause permission issues when mounting local database files to the container. To avoid this, you can use the --userns=keep-id flag to keep the user ID of the current user inside the container, or enable :U option for each volume to change the owner and group of the source volume to the current user.

For example:

podman run -p 8000:8000 \
           -v {path to the directory containing the database file}:/database:U \
           -e LBUG_FILE={database file name} \
           --rm lbugdb/explorer:latest

or,

podman run -p 8000:8000 \
           -v {path to the directory containing the database file}:/database \
           -e LBUG_FILE={database file name} \
           --userns=keep-id \
           --rm lbugdb/explorer:latest

Please refer to the official Podman docs for mounting external volumes and user namespace mode for more information.

Documentation

For more information regarding launching and using Ladybug Explorer, please refer to the documentation.

Development (with Ladybug compiled from source)

Stack

• Server
  • Node.js
  • Express.js
  • [Ladybug](TODO: Ladybug website)
• Client
  • Vue 3
  • Bootstrap 5
  • Monaco Editor
  • G6

Prerequisite

• Node.js v20
• JDK 11+
• Toolchain for building Ladybug
• Git

Environment setup

Install Node.js dependencies

npm i

Download and compile Ladybug

git submodule update --init --recursive
npm run build-lbug

Generate grammar files

npm run generate-grammar

Fetch datasets

npm run fetch-datasets

Run development server (with hot-reloading)

env LBUG_DIR={directory containing ladybug database} LBUG_FILE={database file name} npm run serve

Check code style with ESLint

npm run eslint

Include -fix for automatic correction of fixable styles.

npm run eslint-fix

Build and serve for production

Run production server locally

npm run build
env LBUG_DIR={directory containing ladybug database} LBUG_FILE={database file name} npm run serve-prod

Run production server with Docker

docker build -t lbugdb/explorer:latest .
docker run -p 8000:8000 \
           -v {path to the directory containing the database file}:/database \
           -e LBUG_FILE={database file name} \
           --rm lbugdb/explorer:latest

Deployment

A GitHub actions pipeline has been configured to automatically build and deploy the Docker image to Docker Hub upon pushing to the master branch. The pipeline will build images for both amd64 and arm64 platforms.

Contributing

We welcome contributions to Ladybug Explorer. By contributing to Ladybug Explorer, you agree that your contributions will be licensed under the MIT License.