From e272d725a54c819020b9e0040c054a5be659d9aa Mon Sep 17 00:00:00 2001 From: leonnicolas <60091705+leonnicolas@users.noreply.github.com> Date: Fri, 28 May 2021 13:01:17 +0200 Subject: [PATCH] docs/building.md: add docs for building Kilo and the website (#177) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs/building.md: add docs for building Kilo and the website Signed-off-by: leonnicolas Update docs/building_kilo.md Co-authored-by: Lucas Servén Marín * Apply suggestions from code review Co-authored-by: Lucas Servén Marín Co-authored-by: Lucas Servén Marín --- docs/building_kilo.md | 100 ++++++++++++++++++++++++++++++++++ docs/building_website.md | 44 +++++++++++++++ website/docs/building_kilo | 5 ++ website/docs/building_website | 5 ++ website/sidebars.js | 5 ++ 5 files changed, 159 insertions(+) create mode 100644 docs/building_kilo.md create mode 100644 docs/building_website.md create mode 100644 website/docs/building_kilo create mode 100644 website/docs/building_website diff --git a/docs/building_kilo.md b/docs/building_kilo.md new file mode 100644 index 0000000..13d1f11 --- /dev/null +++ b/docs/building_kilo.md @@ -0,0 +1,100 @@ +# Build and Test Kilo + +This document describes how you can build and test Kilo. + +To follow along, you need to install the following utilities: + - `go` not for building but formatting the code and running unit tests + - `make` + - `jq` + - `git` + - `curl` + - `docker` + +## Getting Started + +Clone the Repository and `cd` into it. +```shell +git clone https://github.com/squat/kilo.git +cd kilo +``` + +## Build + +For consistency, the Kilo binaries are compiled in a Docker container, so make sure the `docker` package is installed and the daemon is running. + +### Compile Binaries + +To compile the `kg` and `kgctl` binaries run: +```shell +make +``` +Binaries are always placed in a directory corresponding to the local system's OS and architecture following the pattern `bin///`, so on an AMD64 machine running Linux, the binaries will be stored in `bin/linux/amd64/`. + +You can build the binaries for a different architecture by setting the `ARCH` environment variable before invoking `make`, e.g.: +```shell +ARCH= make +``` + +Likewise, to build `kg` for another OS, set the `OS` environment variable before invoking `make`: +```shell +OS= make +``` +## Test + +To execute the unit tests, run: +```shell +make unit +``` + +To lint the code in the repository, run: +```shell +make lint +``` + +To execute basic end to end tests, run: +```shell +make e2e +``` +__Note__: The end to end tests are currently flaky, so try running them again if they fail. + +To instead run all of the tests with a single command, run: +```shell +make test +``` + +## Build and Push the Container Images + +If you want to build containers for a processor architecture that is different from your computer's, then you will first need to configure QEMU as the interpreter for binaries built for non-native architectures: +```shell +docker run --rm --privileged multiarch/qemu-user-static --reset -p yes +``` + +Set the `$IMAGE` environment variable to `/kilo`. +This way the generated container images and manifests will be named accordingly. +By skipping this step, you will be able to tag images but will not be able to push the containers and manifests to your own Docker Hub. +```shell +export IMAGE=/kilo +``` + +If you want to use a different container registry, run: +```shell +export REGISTRY= +``` + +To build containers with the `kg` image for `arm`, `arm64` and `amd64`, run: +```shell +make all-container +``` + +Push the container images and build a manifest with: +```shell +make manifest +``` + +To tag and push the manifest with `latest`, run: +```shell +make manifest-latest +``` + +Now you can deploy the custom build of Kilo to your cluster. +If you are already running Kilo, change the image from `squat/kilo` to `[registry/]/kilo[:sha]`. diff --git a/docs/building_website.md b/docs/building_website.md new file mode 100644 index 0000000..415b48f --- /dev/null +++ b/docs/building_website.md @@ -0,0 +1,44 @@ +# Build and Test the Website + +You may have noticed that the `markdown` files in the `/docs` directory are also displayed on [Kilo's website](https://kilo.squat.ai/). +If you want to add documentation to Kilo, you can start a local webserver to check out how the website would look like. + +## Requirements + +Install [yarn](https://yarnpkg.com/getting-started/install). + +## Build and Run + +The markdown files for the website are located in `/website/docs` and are generated from the like-named markdown files in the `/docs` directory and from the corresponding header files without the `.md` extension in the `/website/docs` directory. +To generate the markdown files in `/website/docs`, run: +```shell +make website/docs/README.md +``` + +Next, build the website itself by installing the `node_modules` and building the website's HTML from the generated markdown: +```shell +make website/build/index.html +``` + +Now, start the website server with: +```shell +yarn --cwd website start +``` +This command should have opened a browser window with the website; if not, open your browser and point it to `http://localhost:3000`. + +If you make changes to any of the markdown files in `/docs` and want to reload the local `node` server, run: +```shell +make website/docs/README.md -B +``` + +You can execute the above while the node server is running and the website will be rebuilt and reloaded automatically. + +## Add a New File to the Docs + +If you add a new file to the `/docs` directory, you also need to create a corresponding header file containing the front-matter in `/website/docs/`. +Then, regenerate the markdown for the website with the command: +```shell +make website/docs/README.md +``` +Edit `/website/sidebars.js` accordingly. +_Note:_ The `id` in the header file `/website/docs/` must match the `id` specified in `website/sidebars.js`. diff --git a/website/docs/building_kilo b/website/docs/building_kilo new file mode 100644 index 0000000..56d2208 --- /dev/null +++ b/website/docs/building_kilo @@ -0,0 +1,5 @@ +--- +id: building_kilo +title: Building Kilo +hide_title: true +--- diff --git a/website/docs/building_website b/website/docs/building_website new file mode 100644 index 0000000..d4b1bda --- /dev/null +++ b/website/docs/building_website @@ -0,0 +1,5 @@ +--- +id: building_website +title: Building the Website +hide_title: true +--- diff --git a/website/sidebars.js b/website/sidebars.js index c3c55b2..d977bc1 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -14,6 +14,11 @@ module.exports = { label: 'Reference', items: ['annotations', 'kg', 'kgctl', 'api'], }, + { + type: 'category', + label: 'Contributing', + items: ['building_kilo', 'building_website'], + }, //Features: ['mdx'], ], };