mirror of
https://github.com/moghtech/komodo.git
synced 2025-12-05 19:17:36 -06:00
docs: Add development docs (#136)
* docs: Add development POC * docs: Flesh out full build/run steps * feat: Add mergeable compose file to expose port and internal periphery url * feat: Add .devcontainer and VSCode Tasks for developing Komodo * Make cargo cache persistent in devcontainer * Add deno to devcontainer * Update tasks to include TS client copy to frontend before run * Recommend extensions for used dependencies in vscode workspace All extensions recommended are included in the devcontainer. This makes it easier for users not using devcontainer to get lang support. * Update local `run` sequence for development docs
This commit is contained in:
Matt Foxx
GitHub
33
.devcontainer/dev.compose.yaml
Normal file
33
.devcontainer/dev.compose.yaml
Normal file
@@ -0,0 +1,33 @@
|
||||
services:
|
||||
dev:
|
||||
image: mcr.microsoft.com/devcontainers/rust:1-1-bullseye
|
||||
volumes:
|
||||
# Mount the root folder that contains .git
|
||||
- ../:/workspace:cached
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
- /proc:/proc
|
||||
- repos:/etc/komodo/repos
|
||||
- stacks:/etc/komodo/stacks
|
||||
command: sleep infinity
|
||||
ports:
|
||||
- "9121:9121"
|
||||
environment:
|
||||
KOMODO_FIRST_SERVER: http://localhost:8120
|
||||
KOMODO_DATABASE_ADDRESS: db
|
||||
KOMODO_ENABLE_NEW_USERS: true
|
||||
KOMODO_LOCAL_AUTH: true
|
||||
KOMODO_JWT_SECRET: a_random_secret
|
||||
links:
|
||||
- db
|
||||
# ...
|
||||
|
||||
db:
|
||||
extends:
|
||||
file: ../test.compose.yaml
|
||||
service: ferretdb
|
||||
|
||||
volumes:
|
||||
data:
|
||||
repo-cache:
|
||||
repos:
|
||||
stacks:
|
||||
46
.devcontainer/devcontainer.json
Normal file
46
.devcontainer/devcontainer.json
Normal file
@@ -0,0 +1,46 @@
|
||||
// For format details, see https://aka.ms/devcontainer.json. For config options, see the
|
||||
// README at: https://github.com/devcontainers/templates/tree/main/src/rust
|
||||
{
|
||||
"name": "Komodo",
|
||||
// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
|
||||
//"image": "mcr.microsoft.com/devcontainers/rust:1-1-bullseye",
|
||||
"dockerComposeFile": ["dev.compose.yaml"],
|
||||
"workspaceFolder": "/workspace",
|
||||
"service": "dev",
|
||||
// Features to add to the dev container. More info: https://containers.dev/features.
|
||||
"features": {
|
||||
"ghcr.io/devcontainers/features/node:1": {
|
||||
"version": "18.18.0"
|
||||
},
|
||||
"ghcr.io/devcontainers-community/features/deno:1": {
|
||||
|
||||
}
|
||||
},
|
||||
|
||||
// Use 'mounts' to make the cargo cache persistent in a Docker Volume.
|
||||
"mounts": [
|
||||
{
|
||||
"source": "devcontainer-cargo-cache-${devcontainerId}",
|
||||
"target": "/usr/local/cargo",
|
||||
"type": "volume"
|
||||
}
|
||||
],
|
||||
|
||||
// Use 'forwardPorts' to make a list of ports inside the container available locally.
|
||||
"forwardPorts": [
|
||||
9121
|
||||
],
|
||||
|
||||
// Use 'postCreateCommand' to run commands after the container is created.
|
||||
"postCreateCommand": "./.devcontainer/postCreate.sh",
|
||||
|
||||
"runServices": [
|
||||
"db"
|
||||
]
|
||||
|
||||
// Configure tool-specific properties.
|
||||
// "customizations": {},
|
||||
|
||||
// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
|
||||
// "remoteUser": "root"
|
||||
}
|
||||
3
.devcontainer/postCreate.sh
Executable file
3
.devcontainer/postCreate.sh
Executable file
@@ -0,0 +1,3 @@
|
||||
#!/bin/sh
|
||||
|
||||
cargo install typeshare-cli
|
||||
8
.vscode/extensions.json
vendored
Normal file
8
.vscode/extensions.json
vendored
Normal file
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"recommendations": [
|
||||
"rust-lang.rust-analyzer",
|
||||
"tamasfe.even-better-toml",
|
||||
"vadimcn.vscode-lldb",
|
||||
"denoland.vscode-deno"
|
||||
]
|
||||
}
|
||||
179
.vscode/tasks.json
vendored
Normal file
179
.vscode/tasks.json
vendored
Normal file
@@ -0,0 +1,179 @@
|
||||
{
|
||||
"version": "2.0.0",
|
||||
"tasks": [
|
||||
{
|
||||
"label": "Run Core",
|
||||
"command": "cargo",
|
||||
"args": [
|
||||
"run",
|
||||
"-p",
|
||||
"komodo_core",
|
||||
"--release"
|
||||
],
|
||||
"options": {
|
||||
"cwd": "${workspaceFolder}",
|
||||
"env": {
|
||||
"KOMODO_CONFIG_PATH": "test.core.config.toml"
|
||||
}
|
||||
},
|
||||
"problemMatcher": [
|
||||
"$rustc"
|
||||
]
|
||||
},
|
||||
{
|
||||
"label": "Build Core",
|
||||
"command": "cargo",
|
||||
"args": [
|
||||
"build",
|
||||
"-p",
|
||||
"komodo_core",
|
||||
"--release"
|
||||
],
|
||||
"options": {
|
||||
"cwd": "${workspaceFolder}",
|
||||
"env": {
|
||||
"KOMODO_CONFIG_PATH": "test.core.config.toml"
|
||||
}
|
||||
},
|
||||
"problemMatcher": [
|
||||
"$rustc"
|
||||
]
|
||||
},
|
||||
{
|
||||
"label": "Run Periphery",
|
||||
"command": "cargo",
|
||||
"args": [
|
||||
"run",
|
||||
"-p",
|
||||
"komodo_periphery",
|
||||
"--release"
|
||||
],
|
||||
"options": {
|
||||
"cwd": "${workspaceFolder}",
|
||||
"env": {
|
||||
"KOMODO_CONFIG_PATH": "test.periphery.config.toml"
|
||||
}
|
||||
},
|
||||
"problemMatcher": [
|
||||
"$rustc"
|
||||
]
|
||||
},
|
||||
{
|
||||
"label": "Build Periphery",
|
||||
"command": "cargo",
|
||||
"args": [
|
||||
"build",
|
||||
"-p",
|
||||
"komodo_periphery",
|
||||
"--release"
|
||||
],
|
||||
"options": {
|
||||
"cwd": "${workspaceFolder}",
|
||||
"env": {
|
||||
"KOMODO_CONFIG_PATH": "test.periphery.config.toml"
|
||||
}
|
||||
},
|
||||
"problemMatcher": [
|
||||
"$rustc"
|
||||
]
|
||||
},
|
||||
{
|
||||
"label": "Run Backend",
|
||||
"dependsOn": [
|
||||
"Run Core",
|
||||
"Run Periphery"
|
||||
],
|
||||
"problemMatcher": [
|
||||
"$rustc"
|
||||
]
|
||||
},
|
||||
{
|
||||
"label": "Build TS Client Types",
|
||||
"type": "process",
|
||||
"command": "node",
|
||||
"args": [
|
||||
"./client/core/ts/generate_types.mjs"
|
||||
],
|
||||
"problemMatcher": []
|
||||
},
|
||||
{
|
||||
"label": "Init TS Client",
|
||||
"type": "shell",
|
||||
"command": "yarn && yarn build && yarn link",
|
||||
"options": {
|
||||
"cwd": "${workspaceFolder}/client/core/ts",
|
||||
},
|
||||
"problemMatcher": []
|
||||
},
|
||||
{
|
||||
"label": "Init Frontend Client",
|
||||
"type": "shell",
|
||||
"command": "yarn link komodo_client && yarn install",
|
||||
"options": {
|
||||
"cwd": "${workspaceFolder}/frontend",
|
||||
},
|
||||
"problemMatcher": []
|
||||
},
|
||||
{
|
||||
"label": "Init Frontend",
|
||||
"dependsOn": [
|
||||
"Build TS Client Types",
|
||||
"Init TS Client",
|
||||
"Init Frontend Client"
|
||||
],
|
||||
"dependsOrder": "sequence",
|
||||
"problemMatcher": []
|
||||
},
|
||||
{
|
||||
"label": "Build Frontend",
|
||||
"type": "shell",
|
||||
"command": "yarn build",
|
||||
"options": {
|
||||
"cwd": "${workspaceFolder}/frontend",
|
||||
},
|
||||
"problemMatcher": []
|
||||
},
|
||||
{
|
||||
"label": "Prepare Frontend For Run",
|
||||
"type": "shell",
|
||||
"command": "cp -r ./client/core/ts/dist/. frontend/public/client/.",
|
||||
"options": {
|
||||
"cwd": "${workspaceFolder}",
|
||||
},
|
||||
"dependsOn": [
|
||||
"Build TS Client Types",
|
||||
"Build Frontend"
|
||||
],
|
||||
"dependsOrder": "sequence",
|
||||
"problemMatcher": []
|
||||
},
|
||||
{
|
||||
"label": "Run Frontend",
|
||||
"type": "shell",
|
||||
"command": "yarn dev",
|
||||
"options": {
|
||||
"cwd": "${workspaceFolder}/frontend",
|
||||
},
|
||||
"dependsOn": ["Prepare Frontend For Run"],
|
||||
"problemMatcher": []
|
||||
},
|
||||
{
|
||||
"label": "Init",
|
||||
"dependsOn": [
|
||||
"Build Backend",
|
||||
"Init Frontend"
|
||||
],
|
||||
"dependsOrder": "sequence",
|
||||
"problemMatcher": []
|
||||
},
|
||||
{
|
||||
"label": "Run Komodo",
|
||||
"dependsOn": [
|
||||
"Run Core",
|
||||
"Run Periphery",
|
||||
"Run Frontend"
|
||||
],
|
||||
"problemMatcher": []
|
||||
},
|
||||
]
|
||||
}
|
||||
51
docsite/docs/development.md
Normal file
51
docsite/docs/development.md
Normal file
@@ -0,0 +1,51 @@
|
||||
# Development
|
||||
|
||||
## Dependencies
|
||||
|
||||
Running Komodo from [source](https://github.com/mbecker20/komodo) requires either [Docker](https://www.docker.com/), use of the included [devcontainer](https://code.visualstudio.com/docs/devcontainers/containers) or these dependencies installed:
|
||||
|
||||
* For backend (Komodo core server, periphery, API)
|
||||
* [Rust](https://www.rust-lang.org/) stable 1.81
|
||||
* [rustup](https://rustup.rs/)
|
||||
* [MongoDB](https://www.mongodb.com/) compatible database
|
||||
* For frontend (Web UI)
|
||||
* [Node](https://nodejs.org/en) >= 18.18 + NPM
|
||||
* [Yarn](https://yarnpkg.com/)
|
||||
* [typeshare](https://github.com/1password/typeshare)
|
||||
* [Deno](https://deno.com/) >= 2.0.2
|
||||
|
||||
## Docker
|
||||
|
||||
After making changes to the project simply run `run test-compose-build` to rebuild Komodo and then `run test-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 build and 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](https://code.visualstudio.com/Docs/editor/tasks) are provded for building and running Komodo.
|
||||
|
||||
After opening the repository with the devcontainer run the task `Init` to build the frontend/backend. Then, the task `Run Komodo` can be used to run frontend/backend. Other tasks for rebuilding/running only parts of the application are also provided.
|
||||
|
||||
## Local
|
||||
|
||||
[runnables-cli](https://github.com/mbecker20/runnables-cli) can be used as a convience for running common project tasks (like a Makefile) found in `runfile.toml`. Otherwise, you can create your own project tasks by references the `cmd`s found in `runfile.toml`. All instructions below will use runnables-cli.
|
||||
|
||||
To run a full Komodo instance from a non-container environment run commands in this order:
|
||||
|
||||
* Ensure dependencies are up to date
|
||||
* `rustup update` -- ensure rust toolchain is up to date
|
||||
* Build and Run backend
|
||||
* `run test-core` -- builds core binary
|
||||
* `run test-periphery` -- builds periphery binary
|
||||
* Build Frontend
|
||||
* `run gen-client` -- generates TS client and adds to the frontend
|
||||
* Prepare API Client
|
||||
* `cd client/core/ts && yarn && yarn build && yarn link`
|
||||
* After running once client can be rebuilt with `run build-ts-client`
|
||||
* [Prepare Frontend](/frontend//README.md)
|
||||
* `cd frontend && yarn link komodo_client && yarn install`
|
||||
* After running once client can be built with `run build-frontend` or started in dev (watch) mode with `run start-frontend`
|
||||
|
||||
### Docs
|
||||
|
||||
Use `run docsite-start` to start the [Docusaurus](https://docusaurus.io/) Komodo docs site in development mode. Changes made to files in `/docsite` will be automatically reloaded by the server.
|
||||
@@ -63,6 +63,7 @@ const sidebars: SidebarsConfig = {
|
||||
"permissioning",
|
||||
"version-upgrades",
|
||||
"api",
|
||||
"development"
|
||||
],
|
||||
};
|
||||
|
||||
|
||||
6
expose.compose.yaml
Normal file
6
expose.compose.yaml
Normal file
@@ -0,0 +1,6 @@
|
||||
services:
|
||||
core:
|
||||
ports:
|
||||
- 9120:9120
|
||||
environment:
|
||||
KOMODO_FIRST_SERVER: http://periphery:8120
|
||||
@@ -24,6 +24,12 @@ cmd = """
|
||||
docker compose -p komodo-dev -f test.compose.yaml down --remove-orphans && \
|
||||
docker compose -p komodo-dev -f test.compose.yaml up -d"""
|
||||
|
||||
[test-compose-exposed]
|
||||
description = "deploys test.compose.yaml with exposed port and non-ssl periphery"
|
||||
cmd = """
|
||||
docker compose -p komodo-dev -f test.compose.yaml -f expose.compose.yaml down --remove-orphans && \
|
||||
docker compose -p komodo-dev -f test.compose.yaml -f expose.compose.yaml up -d"""
|
||||
|
||||
[test-compose-build]
|
||||
description = "builds and deploys test.compose.yaml"
|
||||
cmd = """
|
||||
|
||||
Reference in New Issue
Block a user