From 69c64d6c695650bddfee30a3867022594318ff51 Mon Sep 17 00:00:00 2001 From: Markus Rudy Date: Fri, 17 Nov 2023 19:16:52 +0100 Subject: [PATCH] docs: improve developer documentation for folks new to the codebase * Correct example invocation of aws cli * Add warning to Helm Intellisense recommendation * Link code conventions in PR guidelines * Tighten debugd README * cmake is not used for building debugd anymore, remove references to it * make the debug-cluster workflow the authoritative source for cdbg usage - don't replicate the same instructions in different places * Document that Bazel eats a lot of RAM --- debugd/README.md | 40 ++++------------------ dev-docs/workflows/build-develop-deploy.md | 3 +- dev-docs/workflows/dev-setup.md | 2 +- dev-docs/workflows/pull-request.md | 2 +- 4 files changed, 11 insertions(+), 36 deletions(-) diff --git a/debugd/README.md b/debugd/README.md index 83a8e5fc38..c2127dc491 100644 --- a/debugd/README.md +++ b/debugd/README.md @@ -9,43 +9,17 @@ Subsequently you can initialize your cluster with `constellation apply` as usual ## Build cdbg -```shell -mkdir -p build -cmake .. -make cdbg -``` - -## debugd & cdbg usage - -Before continuing, remember to [set up](https://docs.edgeless.systems/constellation/getting-started/install#set-up-cloud-credentials) your cloud credentials for the CLI to work. - -With `cdbg` and `yq` installed in your path: - -1. Run `constellation config generate` to create a new default configuration +The `cdbg` tool is part of the `//:devbuild` target, if you follow the generic build instructions at [build-develop-deploy](../dev-docs/workflows/build-develop-deploy.md). -2. Locate the latest debugd images by running `(cd internal/api/versionsapi/cli && go build -o versionsapi . && ./versionsapi latest --ref main --stream debug)` +If you need to build `cdbg` standalone for your current platform, you can run -3. Modify the `constellation-conf.yaml` to use an image with the debugd already included and add required firewall rules: - - ```shell-session - # Set full reference of cloud provider image name - export IMAGE_URI= - ``` - - ```shell-session - yq -i \ - ".image = \"${IMAGE_URI}\" | \ - .debugCluster = true" \ - constellation-conf.yaml - ``` - -4. Run `constellation create […]` - -5. Run `./cdbg deploy` +```sh +bazel build //debugd/cmd/cdbg:cdbg_host +``` - By default, `cdbg` searches for the bootstrapper in the current path (`./bootstrapper`). You can define a custom path by appending the argument `--bootstrapper ` to `cdbg deploy`. +## debugd & cdbg usage -6. Run `constellation apply […]` as usual +Follow the [debug-cluster workflow](../dev-docs/workflows/debug-cluster.md) to deploy a bootstrapper with `cdbg` and `debugd`. ### Logcollection to Opensearch diff --git a/dev-docs/workflows/build-develop-deploy.md b/dev-docs/workflows/build-develop-deploy.md index 8c061c56ae..cc43f6b1ae 100644 --- a/dev-docs/workflows/build-develop-deploy.md +++ b/dev-docs/workflows/build-develop-deploy.md @@ -5,6 +5,7 @@ The following are instructions for building all components in the constellation Prerequisites: * 20GB (minimum), better 40 GB disk space (required if you want to cross compile for all platforms) +* 16GB of unutilized RAM for a full Bazel build. * [Latest version of Go](https://go.dev/doc/install). * Unless you use Nix / NixOS: [Bazelisk installed as `bazel` in your path](https://github.com/bazelbuild/bazelisk/releases). * We require Nix to be installed. It is recommended to install nix using the [determinate systems installer](https://github.com/DeterminateSystems/nix-installer) (or to use NixOS as host system). @@ -55,7 +56,7 @@ To provision the constellation cluster on the provider infrastructure, please au E.g. AWS: ```sh -aws login +aws configure ``` For more details, see [here](https://docs.edgeless.systems/constellation/getting-started/install#set-up-cloud-credentials). diff --git a/dev-docs/workflows/dev-setup.md b/dev-docs/workflows/dev-setup.md index 5d5d57f7a8..e959404813 100644 --- a/dev-docs/workflows/dev-setup.md +++ b/dev-docs/workflows/dev-setup.md @@ -37,7 +37,7 @@ Additionally, we use the [Redhat YAML formatter](https://marketplace.visualstudi * ShellCheck (timonwong.shellcheck): Shell script linter * vscode-proto3 (zxh404.vscode-proto3): Protobuf language support * Code Spell Checker (streetsidesoftware.code-spell-checker): Highlights potential spelling mistakes -* Helm Intellisense: (Tim-Koehler.helm-intellisense): Syntax highlighting and more for Helm charts +* Helm Intellisense: (Tim-Koehler.helm-intellisense): Syntax highlighting and more for Helm charts (not available on [Open VSX Registry](https://open-vsx.org/)) * YAML (redhat.vscode-yaml): YAML language support. (Does not work with Helm charts) * markdownlint (DavidAnson.vscode-markdownlint): Markdown linter diff --git a/dev-docs/workflows/pull-request.md b/dev-docs/workflows/pull-request.md index 46c3ec3e38..72c54259dd 100644 --- a/dev-docs/workflows/pull-request.md +++ b/dev-docs/workflows/pull-request.md @@ -8,7 +8,7 @@ For pull requests, we employ the following workflow: 1. Fork the repository to your own GitHub account 2. Create a branch locally with a descriptive name 3. Commit changes to the branch -4. Write your code according to our development guidelines +4. Write your code according to our [development guidelines](../conventions.md) 5. Push changes to your fork 6. Clean up your commit history 7. Open a PR in our repository and summarize the changes in the description