docs: Update user-facing docs (#219)

Signed-off-by: Anurag Rajawat <[email protected]>
5GSEC · Jul 9, 2024 · 8e63ed3 · 8e63ed3
1 parent d0532ae
commit 8e63ed3
Show file tree

Hide file tree

Showing 5 changed files with 282 additions and 140 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,130 @@
+# Want to contribute?
+
+Great! We welcome contributions of all kinds, big or small! This includes bug reports, code fixes, documentation
+improvements, and code examples.
+
+Before you dive in, please take a moment to read through this guide.
+
+# Reporting issue
+
+We use [GitHub](https://github.com/5GSEC/nimbus) to manage the issues. Please open
+a [new issue](https://github.com/5GSEC/nimbus/issues/new) directly there.
+
+# Getting Started
+
+## Setting Up Your Environment
+
+- Head over to [GitHub](https://github.com/5GSEC/nimbus) and fork the 5GSec Nimbus repository.
+- Clone your forked repository onto your local machine.
+  ```shell
+  git clone [email protected]:<your-username>/nimbus.git
+  ```
+
+## Install development tools
+
+You'll need these tools for a smooth development experience:
+
+- [Make](https://www.gnu.org/software/make/#download)
+- [Go](https://go.dev/doc/install) SDK, version 1.21 or later
+- Go IDE ([Goland](https://www.jetbrains.com/go/) / [VS Code](https://code.visualstudio.com/download))
+- Container tools ([Docker](https://www.docker.com/) / [Podman](https://podman.io/))
+- [Kubernetes cluster](https://kubernetes.io/docs/setup/) running version 1.26 or later.
+- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) version 1.26 or later.
+
+# Project Setup
+
+## Building Locally
+
+- Install development tools (mentioned above).
+
+- Build Nimbus using:
+  ```shell
+  make build
+  ```
+
+## Testing Local Build
+
+### Against the Cluster (without installing as workload):
+
+#### Nimbus operator
+
+- Generate code and manifests:
+  ```shell
+  make manifests generate
+  ```
+
+- Install CRDs:
+  ```shell
+  make install
+  ```
+
+- Run the operator:
+  ```shell
+  make run
+  ```
+
+#### Adapters
+
+- Navigate to adapter's directory:
+  ```shell
+  cd pkg/adapter/<adapter-name>
+  ```
+- Run it:
+  ```shell
+  make run
+  ```
+
+### In the Cluster (installing as workload):
+
+Follow [this](deployments/nimbus/Readme.md) guide to install Nimbus or the complete suite.
+
+Alternatively, follow [this](docs/adapters.md) guide to install individual adapters.
+
+# Contributing Code
+
+### Understanding the Project
+
+Before contributing to any Open Source project, it's important to have basic understanding of what the project is about.
+It is advised to try out the project as an end user.
+
+### Pull Requests and Code Reviews
+
+We use GitHub [pull requests](https://github.com/5GSEC/nimbus/pulls) for code contributions. All submissions, including
+those from project members, require review before merging.
+We typically aim for two approvals per pull request, with reviews happening within a week or two.
+Feel free to ping reviewers if you haven't received feedback within that timeframe.
+
+#### Commit Messages
+
+We follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification for clear and
+consistent commit messages.
+
+Please make sure you have added the **Signed-off-by:** footer in your git commit. In order to do it automatically, use
+the **--signoff** flag:
+
+```shell
+git commit --signoff
+```
+
+With this command, git would automatically add a footer by reading your name and email from git config.
+
+# Testing and Documentation
+
+Tests and documentation are not optional, make sure your pull requests include:
+
+- Tests that verify your changes and don't break existing functionality.
+- Updated [documentation](docs) reflecting your code changes.
+- Reference information and any other relevant details.
+
+## Commands to run tests
+
+- Integration tests:
+  ```shell
+  make integration-test
+  ```
+
+- End-to-end tests:
+  **Requires installing the complete suite, follow [this](deployments/nimbus/Readme.md)**
+  ```shell
+  make e2e-test
+  ```
diff --git a/README.md b/README.md
@@ -30,6 +30,7 @@ best implementation method available given the deployment.
 
 * [Getting Started](docs/getting-started.md)
 * [Quick Tutorials](docs/quick-tutorials.md)
+* [Contribution guide](CONTRIBUTING.md)
 
 # Credits
 

diff --git a/docs/adapters.md b/docs/adapters.md
@@ -0,0 +1,101 @@
+# Adapters
+
+Clone your forked repository onto your local machine.
+
+```shell
+git clone [email protected]:<your-username>/nimbus.git
+```
+
+## nimbus-kubearmor
+
+### From source
+
+**Requires installing corresponding security engine**:
+Follow [this](https://docs.kubearmor.io/kubearmor/quick-links/deployment_guide) guide to install
+KubeArmor.
+
+Navigate to `nimbus-kubearmor` directory:
+
+```shell
+cd nimbus/pkg/adapter/nimbus-kubearmor
+```
+
+Run adapter:
+
+```shell
+make run
+```
+
+### From Helm chart
+
+Follow [this](../../deployments/nimbus-kubearmor/Readme.md) guide to install using a helm cahrt.
+
+## nimbus-netpol
+
+> [!Note]
+> The `nimbus-netpol` adapter leverages
+> the [network plugin](https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/).
+> To use network policies, you must be using a networking solution which supports NetworkPolicy. Creating a
+> NetworkPolicy resource without a controller that implements it will have no effect.
+
+### From source
+
+Navigate to `nimbus-netpol` directory:
+
+```shell
+cd nimbus/pkg/adapter/nimbus-netpol
+```
+
+Run adapter:
+
+```shell
+make run
+```
+
+### From Helm chart
+
+Follow [this](../../deployments/nimbus-netpol/Readme.md) to install using a helm chart.
+
+## nimbus-kyverno
+
+**Requires installing corresponding security engine**:
+Follow [this](https://kyverno.io/docs/installation/) guide to install
+Kyverno.
+
+### From source
+
+Navigate to `nimbus-kyverno` directory:
+
+```shell
+cd nimbus/pkg/adapter/nimbus-kyverno
+```
+
+Run adapter:
+
+```shell
+make run
+```
+
+### From Helm chart
+
+Follow [this](../../deployments/nimbus-kyverno/Readme.md) to install using a helm chart.
+
+## nimbus-k8tls
+
+### From source
+
+Navigate to `nimbus-k8tls` directory:
+
+```shell
+cd nimbus/pkg/adapter/nimbus-kyverno
+```
+
+Run adapter:
+
+```shell
+make run
+```
+
+### From Helm chart
+
+Follow [this](../../deployments/nimbus-k8tls/Readme.md) to install using a helm chart.
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -25,32 +25,6 @@ gcloud compute instances create $VM_NAME --zone=$VM_ZONE --machine-type=$VM_MACH
 
 
 # Nimbus
-
-There are various ways of installing Nimbus.
-
-## From source
-
-Install [go](https://go.dev/doc/install) version 1.20 or later.
-
-Clone the repository:
-
-```shell
-git clone https://github.com/5GSEC/nimbus.git
-cd nimbus
-```
-
-Install CRDs:
-
-```shell
-make install
-```
-
-Run the operator:
-
-```shell
-make run
-```
-
 ## From Helm Chart
 
 Follow [this](../deployments/nimbus/Readme.md) guide to install `nimbus` operator. By default the install of the `nimbus` operator installs the adapters also, and all the security engines - except confidential containers - too.
@@ -109,90 +83,3 @@ kata-qemu-sev   kata-qemu-sev   10d
 kata-qemu-snp   kata-qemu-snp   10d
 kata-qemu-tdx   kata-qemu-tdx   10d
 ```
-
-# Adapters
-
-Just like Nimbus, there are various ways of installing Security engine adapters.
-
-- ## nimbus-kubearmor
-  ### From source
-
-  Clone the repository:
-
-    ```shell
-    git clone https://github.com/5GSEC/nimbus.git
-    ```
-
-  Go to nimbus-kubearmor directory:
-
-    ```shell
-    cd nimbus/pkg/adapter/nimbus-kubearmor
-    ```
-
-  Run `nimbus-kubearmor` adapter:
-
-    ```shell
-    make run
-    ```
-
-  ### From Helm Chart
-
-  Follow [this](../deployments/nimbus-kubearmor/Readme.md) guide to install `nimbus-kubearmor` adapter.
-
-- ## nimbus-netpol
-
-  > [!Note]
-  > The `nimbus-netpol` adapter leverages
-  > the [network plugin](https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/).
-  > To use network policies, you must be using a networking solution which supports NetworkPolicy. Creating a
-  > NetworkPolicy resource without a controller that implements it will have no effect.
-
-  ### From source
-
-  Clone the repository:
-
-  ```shell
-  git clone https://github.com/5GSEC/nimbus.git
-  ```
-
-  Go to nimbus-netpol directory:
-
-  ```shell
-  cd nimbus/pkg/adapter/nimbus-netpol
-  ```
-
-  Run `nimbus-netpol` adapter:
-
-  ```shell
-  make run
-  ```
-
-  ### From Helm Chart
-
-  Follow [this](../deployments/nimbus-netpol/Readme.md) guide to install `nimbus-netpol` adapter.
-
-- ## nimbus-kyverno
-
-  ### From source
-
-  Clone the repository:
-
-  ```shell
-  git clone https://github.com/5GSEC/nimbus.git
-  ```
-
-  Go to nimbus-kyverno directory:
-
-  ```shell
-  cd nimbus/pkg/adapter/nimbus-kyverno
-  ```
-
-  Run `nimbus-kyverno` adapter:
-
-  ```shell
-  make run
-  ```
-
-  ### From Helm Chart
-
-  Follow [this](../deployments/nimbus-kyverno/Readme.md) guide to install `nimbus-kyverno` adapter.