building: add BUILDING.md (#198)

Describe how to build and run on arbitrary systems.

BUILDING.md

@@ -0,0 +1,51 @@
+# Building RKE2
+
+## Prerequisites
+
+By default, RKE2 is built with Dapper which uses Docker. To build RKE2 you will need to install these packages:
+- bash
+- docker
+- gcc (CGO, don't ya know, if using `scripts/build` directly)
+- go (check the `go.mod` for which series of go, e.g. 1.14.x, 1.15.x, etc)
+- make
+
+### Required for Running
+When running RKE2 you will also need to install these packages:
+- libseccomp (libseccomp2 on Debian/Ubuntu)
+- ca-certificates
+
+## Building
+
+```shell script
+# for non air-gap testing
+make build image
+# for air-gap testing
+make build-airgap
+```
+
+## Running
+
+### rke2 (dev-shell)
+To run locally in a container, there is a handy `make` target:
+```shell script
+make dev-shell
+```
+
+This will spin up a privileged container and setup the environment ready for you to invoke `./bin/rke2` at your leisure.
+Since the `rancher/rke2-runtime` image was built locally and likely not yet pushed, this, along with the airgap images,
+has been bind-mounted into the container ready to be imported into containerd on start-up.
+
+### rke2 (generic)
+
+To run the built artifact(s) locally or on a remote host:
+- install prerequisites mentioned above
+- copy `./bin/rke2` to the path on your host
+- copy `./build/images/rke2-runtime-image-$(go env GOARCH).tar` to `/var/lib/rancher/rke2/agent/images/` on your host
+- if testing airgap, also copy `./build/images/airgap.tar` to `/var/lib/rancher/rke2/agent/images/` on your host
+- run rke2 server: `rke2 server --token=test`
+
+### kubectl
+
+It isn't obvious but `kubectl` will be installed and ready to use after starting up `rke2`. To use it you will need to:
+- `export KUBECONFIG=/etc/rancher/rke2/rke2.yaml`
+- `export PATH="$(ls -td /var/lib/rancher/rke2/data/*/bin | head -n 1):$PATH"`

Makefile

@@ -23,12 +23,15 @@ dapper-ci: .ci                           ## Used by Drone CI, does the same as "
 build:                                   ## Build using host go tools
 	./scripts/build
 
+.PHONY: build-airgap
+build-airgap: | build image k8s-image build/images/airgap.tar	## Build all images for an airgapped installation
+
 .PHONY: build-debug
 build-debug:                             ## Debug build using host go tools
 	./scripts/build-debug
 
 .PHONY: image
-image:                                   ## Build final docker image for push
+image: download-charts					## Build final docker image for push
 	./scripts/image
 
 .PHONY: k8s-image
@@ -56,7 +59,7 @@ remote-debug-exit:              		 ## Kill dlv started with make remote-debug
 	./scripts/remote-debug-exit
 
 .PHONY: dev-shell-build
-dev-shell-build: build/images/airgap.tar
+dev-shell-build: build-airgap
 	./scripts/dev-shell-build
 
 build/images/airgap.tar:

scripts/clean-cache

@@ -2,7 +2,7 @@
 
 cd $(dirname $0)/..
 
-source . ./scripts/version.sh
+source ./scripts/version.sh
 
 docker rm -fv ${PROG}-dev-shell
 docker volume rm ${PROG}-cache ${PROG}-pkg

scripts/dev-shell-build

@@ -8,13 +8,8 @@ IMAGE_REPO=rancher
 
 . ./scripts/version.sh
 
-mkdir -p build/images
-
-docker save -o ./build/images/rke2-runtime-image-amd64.tar rancher/rke2-runtime:${VERSION}-${GOARCH}
-
-if [ -n "${BUILD_K8S_IMAGE}" ]; then
-  docker save -o ./build/images/k8s-image-amd64.tar rancher/kubernetes:${VERSION}
+if [ ! -d build/images ]; then
+  ./scripts/image
 fi
-
 # build the dev shell image
-docker build -t ${PROG}-dev --target shell .
+docker build -t ${PROG}-dev --target shell .

scripts/image

@@ -8,3 +8,9 @@ cd $(dirname $0)/..
 docker build \
   --build-arg KUBERNETES_VERSION=${KUBERNETES_VERSION} \
   -t ${REPO}/rke2-runtime:${VERSION}-${GOARCH} .
+
+mkdir -p build/images
+docker save -o ./build/images/rke2-runtime-image-amd64.tar rancher/rke2-runtime:${VERSION}-${GOARCH}
+if [ -n "${BUILD_K8S_IMAGE}" ]; then
+  docker save -o ./build/images/k8s-image-amd64.tar rancher/kubernetes:${VERSION}
+fi