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
mbecker20 · Oct 22, 2024 · d66a781 · d66a781
1 parent f9b2994
commit d66a781
Show file tree

Hide file tree

Showing 9 changed files with 333 additions and 0 deletions.
diff --git a/.devcontainer/dev.compose.yaml b/.devcontainer/dev.compose.yaml
@@ -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:
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -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"
+}
diff --git a/.devcontainer/postCreate.sh b/.devcontainer/postCreate.sh
@@ -0,0 +1,3 @@
+#!/bin/sh
+
+cargo install typeshare-cli
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
@@ -0,0 +1,8 @@
+{
+    "recommendations": [
+        "rust-lang.rust-analyzer",
+        "tamasfe.even-better-toml",
+        "vadimcn.vscode-lldb",
+        "denoland.vscode-deno"
+    ]
+}
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
@@ -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": []
+        },
+    ]
+  }
diff --git a/docsite/docs/development.md b/docsite/docs/development.md
@@ -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.
diff --git a/docsite/sidebars.ts b/docsite/sidebars.ts
@@ -63,6 +63,7 @@ const sidebars: SidebarsConfig = {
     "permissioning",
     "version-upgrades",
     "api",
+    "development"
   ],
 };
 

diff --git a/expose.compose.yaml b/expose.compose.yaml
@@ -0,0 +1,6 @@
+services:
+  core:
+    ports:
+      - 9120:9120
+    environment:
+      KOMODO_FIRST_SERVER: http://periphery:8120
diff --git a/runfile.toml b/runfile.toml
@@ -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 = """
-Original file line number
+Diff line change
@@ Expand Up / @@ -63,6 +63,7 @@ const sidebars: SidebarsConfig = { @@
         "permissioning",
         "version-upgrades",
         "api",
+        "development"
       ],
     };
@@ Expand Down @@