diff --git a/README.md b/README.md index 034134c..6ad687d 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ # KùzuExplorer + Browser-based user interface for the [Kùzu](https://github.com/kuzudb/kuzu) graph database. ![image](https://github.com/kuzudb/explorer/assets/14037726/12bfcd9e-cb7f-4fd5-9214-7bbd3b547bd6) - ## Get started KùzuExplorer is a web application that is launched from a deployed Docker image. @@ -76,11 +76,39 @@ docker run -p 8000:8000 \ --rm kuzudb/explorer:latest ``` +### Launch with Podman + +If you are using [Podman](https://podman.io/) instead of Docker, you can launch KùzuExplorer 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: + +```bash +podman run -p 8000:8000 \ + -v /absolute/path/to/database:/database:U \ + --rm kuzudb/explorer:latest +``` + +or, + +```bash +podman run -p 8000:8000 \ + -v /absolute/path/to/database:/database \ + --userns=keep-id \ + --rm kuzudb/explorer:latest +``` + +Please refer to the official Podman docs for [mounting external volumes] +(https://docs.podman.io/en/latest/markdown/podman-run.1.html#mounting-external-volumes) and [user namespace mode] +(https://https://docs.podman.io/en/latest/markdown/podman-run.1.html#userns-mode) for more information. + ## Documentation + For more information regarding launching and using KùzuExplorer, please refer to the [documentation](https://kuzudb.com/docusaurus/kuzuexplorer). ## Development (with Kùzu compiled from source) + ### Stack + - Server - [Node.js](https://nodejs.org) - [Express.js](https://expressjs.com/) @@ -92,46 +120,56 @@ For more information regarding launching and using KùzuExplorer, please refer t - [G6](https://github.com/antvis/G6) ### Prerequisite + - [Node.js v20](https://nodejs.org/dist/latest-v20.x/) - [JDK 11+](https://jdk.java.net/11/) - [Toolchain for building Kùzu](https://kuzudb.com/docusaurus/development/building-kuzu) - [Git](https://git-scm.com/) ### Environment setup + #### Install Node.js dependencies + ```bash npm i ``` #### Download and compile Kùzu + ```bash git submodule update --init --recursive -npm run build-kuzu +npm run build-kuzu ``` #### Generate grammar files + ```bash npm run generate-grammar ``` #### Fetch datasets + ```bash npm run fetch-datasets ``` ### Run development server (with hot-reloading) + ``` env KUZU_PATH=path/to/database npm run serve ``` ## Build and serve for production + ### Run production server locally + ```bash npm run build env KUZU_PATH=path/to/database npm run serve-prod ``` ### Run production server with Docker + ``` docker build -t kuzudb/explorer:latest . docker run -p 8000:8000 \ @@ -140,9 +178,11 @@ docker run -p 8000:8000 \ ``` ## Deployment -A [GitHub actions pipeline](.github/workflows/build-and-deploy.yml) has been configured to automatically build and deploy + +A [GitHub actions pipeline](.github/workflows/build-and-deploy.yml) has been configured to automatically build and deploy the Docker image to [Docker Hub](https://hub.docker.com/) upon pushing to the master branch. The pipeline will build images for both `amd64` and `arm64` platforms. ## Contributing + We welcome contributions to KùzuExplorer. By contributing to KùzuExplorer, you agree that your contributions will be licensed under the [MIT License](LICENSE).