Skip to main content

Development

If you are looking to contribute to Komodo, this page is a launching point for setting up your Komodo development environment.

Dependencies​

Running Komodo from source requires either Docker (and can use the included devcontainer), or can have the development dependencies installed locally:

  • Backend (Core / Periphery APIs)
    • Rust stable via rustup installer
    • MongoDB or FerretDB available locally.
    • On Debian/Ubuntu: apt install build-essential pkg-config libssl-dev required to build the rust source.
  • Web UI
    • Node >= 18.18 + NPM
      • Yarn - (Tip: use corepack enable after installing node to use yarn)
    • typeshare
    • Deno >= 2.0.2

runnables-cli​

mbecker20/runnables-cli can be used as a convience CLI for running common project tasks found in runfile.toml. Otherwise, you can create your own project tasks by references the cmds found in runfile.toml. All instructions below will use runnables-cli v1.3.7+.

Docker​

After making changes to the project, run run dev-compose-build to rebuild Komodo and then run dev-compose-exposed to start a Komodo container with the UI accessible at localhost:9120. Any changes made to source files will require re-running the dev-compose-build and dev-compose-exposed commands.

Devcontainer​

Use the included .devcontainer.json with VSCode or other compatible IDE to stand-up a full environment, including database, with one click.

VSCode Tasks are provided for building and running Komodo.

After opening the repository with the devcontainer run the task Init to build the ui/backend. Then, the task Run Komodo can be used to run ui/backend. Other tasks for rebuilding/running just one component of the stack (Core API, Periphery API, UI) are also provided.

Local​

You can also run the components locally, using Docker only for the database.

Initial One-time Setup​

Create the local config directories.

mkdir -p .dev/keys .dev/periphery

Add .dev/core.config.toml with the following contents:

host = "http://localhost:9120"
private_key = "file:.dev/keys/core.key"
local_auth = true
enable_new_users = true
jwt_secret = "a_random_secret"
first_server_address = "http://localhost:8120"
cors_allowed_origins = ["http://localhost:5173"]
cors_allow_credentials = true
session_allow_cross_site = true

database.address = "localhost:27017"
database.username = "komodo"
database.password = "komodo"

Add .dev/periphery.config.toml:

ssl_enabled = false
root_directory = ".dev/periphery"

Create ui/.env.development with the following:

VITE_KOMODO_HOST=http://localhost:9120

Make sure your Rust toolchain is up to date and install the CLI tools:

rustup update
cargo install typeshare-cli runnables-cli
run link-client

Starting the services​

Start a Mongo instance in Docker:

docker run -d --name komodo-mongo \
-p 27017:27017 \
-v komodo-mongo-data:/data/db \
-v komodo-mongo-config:/data/configdb \
-e MONGO_INITDB_ROOT_USERNAME=komodo \
-e MONGO_INITDB_ROOT_PASSWORD=komodo \
mongo

In separate terminals, run Core, Periphery, and UI.

run dev-core
run dev-periphery

```sh
run dev-ui      # Start in dev (watch) mode

Once everything is running, open http://localhost:5173 and create a user account.

Rebuilding the frontend client​

After API changes, rebuild the client with

run gen-client  # Rebuild client (after API changes)

Docsite Development​

Use run dev-docsite to start the Docusaurus Komodo docs site in development mode. Changes made to files in ./docsite will be automatically reloaded by the server.