Merge pull request #167 from vadorovsky/book-update

docs: Make a separate section for developers

docs/src/README.md

@@ -1,4 +1,4 @@
-![lockc](/images/logo-horizontal-lockc.png)
+![lockc](https://rancher-sandbox.github.io/lockc/images/logo-horizontal-lockc.png)
 
 # Introduction
 

docs/src/SUMMARY.md

@@ -4,20 +4,22 @@
 - [Containers do not contain](containers-do-not-contain.md)
 - [Architecture](architecture.md)
 - [Getting started](configuration.md)
-    - [Build](build/README.md)
-        - [Dapper](build/dapper.md)
-        - [Cargo](build/cargo.md)
-        - [Container image](build/container-image.md)
     - [Install](install/README.md)
         - [With Docker](install/docker.md)
         - [With Kubernetes](install/kubernetes.md)
-    - [Development environment (Terraform)](terraform/README.md)
-        - [libvirt](terraform/libvirt.md)
-        - [OpenStack](terraform/openstack.md)
 - [Policies](policies/README.md)
     - [File access](policies/file-access.md)
     - [Mount](policies/mount.md)
     - [Syslog](policies/syslog.md)
 - [Tuning](tuning/README.md)
+- [For Developers](developers/README.md)
+    - [Repositories](developers/repositories.md)
+    - [Build](developers/build/README.md)
+        - [Dapper](developers/build/dapper.md)
+        - [Cargo](developers/build/cargo.md)
+        - [Container image](developers/build/container-image.md)
+    - [Development environment (Terraform)](developers/terraform/README.md)
+        - [libvirt](developers/terraform/libvirt.md)
+        - [OpenStack](developers/terraform/openstack.md)
 - [Demos](demos/README.md)
     - [Mount](demos/mount.md)

docs/src/developers/README.md

@@ -0,0 +1,9 @@
+# For Developers
+
+- [Repositories] - Cloning and working with our git repositories
+- [Build] - How to build lockc from the sources
+- [Development environment (Terraform)] - Using Terraform for setting up development environment lockc
+
+[Repositories]: repositories.md
+[Build]: build/README.md
+[Development environment (Terraform)]: terraform/README.md

docs/src/build/cargo.md → docs/src/developers/build/cargo.md

@@ -4,7 +4,7 @@ If you are comfortable with installing all dependencies on your host system,
 you need to install the following software:
 
 * LLVM
-* libbpf, bpftool
+* bpftool
 * Rust, Cargo
 
 ## LLVM
@@ -31,58 +31,25 @@ zypper in clang llvm
 If there is no packaging of recent LLVM versions for your distribution, there
 is also an option to [download binaries](https://releases.llvm.org/download.html).
 
-## libbpf, bpftool
+## bpftool
 
-libbpf is the official C library for writing, loading and managing BPF programs
-and entities. bpftool is the official CLI for interacting with BPF subsystem.
+bpftool is the official CLI for interacting with BPF subsystem.
 
 Distributions with up to date software (Arch, Fedora, openSUSE Tumbleweed)
-usually provide packaging for both.
+usually provide packaging for it.
 
 Especially for more stable and less up to date distributions, but even
-generally, we would recommend to build both dependencies from source. Both of
+generally, we would recommend to build bpftool from source. Both of
 them are the part of the Linux kernel source.
 
-The easiest way to get the kernel source is to download a tarball available on
-[kernel.org](https://www.kernel.org/). Then build and install tools from it
-(the version might vary from this snippet):
+bpftool is available in its own repo - [github.com/libbpf/bpftool](https://github.com/libbpf/bpftool).
+It lets you to build bpftool with the following commands:
 
 ```bash
-tar -xvf linux-5.14.9.tar.xz
-cd linux-5.14.9
-cd tools/lib/bpf
-make -j $(nproc)
-make install prefix=/usr
-cd ../../bpf/bpftool
-make -j $(nproc)
-make install prefix=/usr
-```
-
-If you are interested in tracking the history of Linux kernel source and/or are
-comfortable using git for it, you can clone one of the git trees:
-
-* [stable tree](https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/) -
-  stable releases and release candidates, this is where the tarball comes from
-* [mainline tree](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/) -
-  patches accepted by Linus, release candidates
-* [bpf-next tree](https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git/) -
-  development of BPF features, before being mainlined
-* [bpf tree](https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf.git/) -
-  BPF bugfixes which are backported to the stable tree
-
-Assuming you want to use the stable tree:
-
-```bash
-git clone git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
-cd linux
-git tag -l # List available tags
-git checkout v5.14.9 # Check out to whatever is the newest
-cd tools/lib/bpf
-make -j $(nproc)
-make install prefix=/usr
-cd ../../bpf/bpftool
-make -j $(nproc)
-make install prefix=/usr
+git clone --recurse-submodules https://github.com/libbpf/bpftool.git
+cd src
+make
+sudo make install prefix=/usr
 ```
 
 ## Installing Rust

docs/src/developers/repositories.md

@@ -0,0 +1,16 @@
+# Repositories
+
+lockc currently uses two git repositories:
+
+* **[rancher-sandbox/lockc](https://github.com/rancher-sandbox/lockc)** - the
+  main repository containing lockc source code
+* **[rancher-sandbox/lockc-helm-charts](https://github.com/rancher-sandbox/lockc-helm-charts)** -
+  repository with Helm charts to deploy lockc on Kubernetes
+
+If you are interested in development and contributing to lockc, we recommend to
+fork and clone both of them. Both will be needed especially for building a
+[development environment based on Terraform](terraform/README.md).
+
+The latter chapters assume that you have **lockc** and **lockc-helm-charts**
+cloned in the same parent directory. For example, as
+*$HOME/my-repositories/lockc* and *$HOME/my-repositories/lockc-helm-charts*.

docs/src/terraform/libvirt.md → docs/src/developers/terraform/libvirt.md

@@ -20,7 +20,8 @@ sudo systemctl restart libvirtd
 
 ## Running VMs
 
-Now it's time to prepare Terraform environment.
+Now it's time to prepare Terraform environment. Terraform files are included in
+the main lockc git repository.
 
 ```bash
 cd contrib/terraform/libvirt
@@ -130,21 +131,25 @@ kube-system   kube-scheduler-lockc-control-plane-0            1/1     Running
 kube-system   kube-scheduler-lockc-control-plane-1            1/1     Running   0             14m
 ```
 
-Now it's time to build and deploy lockc! Detailed instructions how to do that
-are in the following documentation sections:
+Now it's time to build and deploy lockc!
 
-* [Container image](../build/container-image.md)
-* [Install on Kubernetes](../install/kubernetes.md)
-
-But let's continue with a short summary of the easiest way to do that:
+To build lockc container image, we have to go to the main directory in lockc
+git repository:
 
 ```bash
 # Go to the main directory of lockc sources
 cd ../../..
 export IMAGE_NAME=$(uuidgen)
 docker build -t ttl.sh/${IMAGE_NAME}:30m .
 docker push ttl.sh/${IMAGE_NAME}:30m
-helm install lockc contrib/helm/lockc/ --namespace kube-system \
+```
+
+Then we need to go to the lockc-helm-charts git repository:
+
+```bash
+# Go to the main directory of lockc-helm-charts sources
+cd ../lockc-helm-charts
+helm install lockc charts/lockc/ --namespace kube-system \
     --set lockcd.image.repository=ttl.sh/${IMAGE_NAME} \
     --set lockcd.image.tag=30m \
     --set lockcd.debug.enabled=true

docs/src/install/README.md

@@ -1 +1,12 @@
 # Install
+
+lockc provides integration with two container engines and separate installation
+methods for each of them:
+
+* **[Kubernetes]** (+ containerd-cri) - installation through a Helm chart,
+  after which lockc secures newly created pods
+* **[Docker]** - installation on a single machine with Docker as a loca
+  container engine
+
+[Kubernetes]: kubernetes.md
+[Docker]: docker.md

docs/src/install/kubernetes.md

@@ -3,34 +3,13 @@
 This section explains how to install lockc on a Kubernetes cluster with
 [helm](https://helm.sh/).
 
-The helm chart is available on [lockc-helm-chart](https://github.com/rancher-sandbox/lockc-helm-charts) git repository.
-Installation with default values can be done with:
+The helm chart is available on [lockc-helm-chart](https://rancher-sandbox.github.io/lockc-helm-charts/)
+website. Installation with default values can be done with:
 
 ```bash
-repo add lockc https://rancher-sandbox.github.io/lockc-helm-charts/
-helm install install --create-namespace -n lockc lockc lockc/lockc
+kubectl apply -f https://rancher-sandbox.github.io/lockc-helm-charts/namespace.yaml
+helm repo add lockc https://rancher-sandbox.github.io/lockc-helm-charts/
+helm install -n lockc lockc lockc/lockc
 ```
 
 More info on lockc helm chart installation can be found [here](https://rancher-sandbox.github.io/lockc-helm-charts)
-
-To use your own container image, you can override values. Please refer to the
-[Container image](../build/container-image.md) section for instructions about
-building container images with lockc. Let's assume that you pushed an image
-with lockc to `ttl.sh/caa530ed-1371-43f7-a9ad-293a4f930f83:30m`. In that case,
-installation with that image can be done with the following command:
-
-```bash
-helm install lockc lockc/lockc --namespace lockc \
-    --set lockcd.image.repository=ttl.sh/caa530ed-1371-43f7-a9ad-293a4f930f83 \
-    --set lockcd.image.tag=30m
-```
-
-Enabling debug logs can be helpful for troubleshooting or development. That can
-be done with the following command:
-
-```bash
-helm install lockc lockc/lockc/ --namespace lockc \
-    --set lockcd.image.repository=ttl.sh/caa530ed-1371-43f7-a9ad-293a4f930f83 \
-    --set lockcd.image.tag=30m \
-    --set lockcd.debug.enabled=true
-```