docs/building.md: add docs for building Kilo and the website (#177)

* docs/building.md: add docs for building Kilo and the website

Signed-off-by: leonnicolas <leonloechner@gmx.de>

Update docs/building_kilo.md

Co-authored-by: Lucas Servén Marín <lserven@gmail.com>

* Apply suggestions from code review

Co-authored-by: Lucas Servén Marín <lserven@gmail.com>

Co-authored-by: Lucas Servén Marín <lserven@gmail.com>
This commit is contained in:
leonnicolas 2021-05-28 13:01:17 +02:00 committed by GitHub
parent a8f4143f53
commit e272d725a5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 159 additions and 0 deletions

100
docs/building_kilo.md Normal file
View File

@ -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/<os>/<architecture>/`, 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=<arm|arm64|amd64> make
```
Likewise, to build `kg` for another OS, set the `OS` environment variable before invoking `make`:
```shell
OS=<windows|darwin|linux> 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 `<your Docker Hub user name>/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=<docker hub user name>/kilo
```
If you want to use a different container registry, run:
```shell
export REGISTRY=<your registry without a trailing slash>
```
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/]<username>/kilo[:sha]`.

44
docs/building_website.md Normal file
View File

@ -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/<new file>` must match the `id` specified in `website/sidebars.js`.

View File

@ -0,0 +1,5 @@
---
id: building_kilo
title: Building Kilo
hide_title: true
---

View File

@ -0,0 +1,5 @@
---
id: building_website
title: Building the Website
hide_title: true
---

View File

@ -14,6 +14,11 @@ module.exports = {
label: 'Reference', label: 'Reference',
items: ['annotations', 'kg', 'kgctl', 'api'], items: ['annotations', 'kg', 'kgctl', 'api'],
}, },
{
type: 'category',
label: 'Contributing',
items: ['building_kilo', 'building_website'],
},
//Features: ['mdx'], //Features: ['mdx'],
], ],
}; };