chore: Integrate MkDocs with jimporter/mike (aquasecurity#372)

Resolves: aquasecurity#308 Signed-off-by: Daniel Pacak <pacak.daniel@gmail.com>
amit-catalogic · Feb 1, 2021 · 3912678 · 3912678
1 parent 057c751
commit 3912678
Show file tree

Hide file tree

Showing 8 changed files with 69 additions and 29 deletions.
diff --git a/.github/workflows/mkdocs-deploy.yaml b/.github/workflows/mkdocs-deploy.yaml
@@ -1,17 +1,36 @@
 # This is a manually triggered workflow to build and publish the MkDocs from the
 # main branch to GitHub pages at https://aquasecurity.github.io/starboard.
-name: Manually deploy MkDocs
+name: Deploy documentation
+
 on:
   workflow_dispatch:
+    inputs:
+      version:
+        description: Version to be deployed
+        required: true
 
 jobs:
   deploy:
-    name: Deploy MkDocs
+    name: Deploy documentation
     runs-on: ubuntu-18.04
     steps:
-      - name: Checkout code
-        uses: actions/checkout@v1
-      - name: Deploy MkDocs
-        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+      - name: Checkout main
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+          persist-credentials: true
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.x
+      - run: |
+          pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
+          pip install mike
+          pip install mkdocs-macros-plugin
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # Note: It is not the same as ${{ secrets.GITHUB_TOKEN }} !
+          GH_TOKEN: ${{ secrets.MKDOCS_GH_TOKEN }}
+      - run: |
+          git config user.name "Daniel Pacak"
+          git config user.email "pacak.daniel@gmail.com"
+      - run: |
+          mike deploy --push --update-aliases ${{ github.event.inputs.version }} latest
diff --git a/Makefile b/Makefile
@@ -13,7 +13,7 @@ STARBOARD_CLI_IMAGE := aquasec/starboard:$(IMAGE_TAG)
 STARBOARD_OPERATOR_IMAGE := aquasec/starboard-operator:$(IMAGE_TAG)
 STARBOARD_SCANNER_AQUA_IMAGE := aquasec/starboard-scanner-aqua:$(IMAGE_TAG)
 
-MKDOCS_IMAGE := squidfunk/mkdocs-material:6.1.7
+MKDOCS_IMAGE := aquasec/mkdocs-material:starboard
 MKDOCS_PORT := 8000
 
 .PHONY: all
@@ -128,4 +128,5 @@ docker-build-starboard-scanner-aqua: build-starboard-scanner-aqua
 .PHONY: mkdocs-serve
 ## Runs MkDocs development server to preview the documentation page
 mkdocs-serve:
+	docker build -t $(MKDOCS_IMAGE) -f build/mkdocs-material/Dockerfile bin
 	docker run --name mkdocs-serve --rm -v $(PWD):/docs -p $(MKDOCS_PORT):8000 $(MKDOCS_IMAGE)
diff --git a/build/mkdocs-material/Dockerfile b/build/mkdocs-material/Dockerfile
@@ -0,0 +1,10 @@
+FROM squidfunk/mkdocs-material
+
+## If you want to see exactly the same version as is published to GitHub pages
+## use a private image for insiders, which requires authentication.
+
+# docker login -u ${GITHUB_USERNAME} -p ${GITHUB_TOKEN} ghcr.io
+# FROM ghcr.io/squidfunk/mkdocs-material-insiders
+
+RUN pip install mike
+RUN pip install mkdocs-macros-plugin
diff --git a/docs/index.md b/docs/index.md
@@ -1,4 +1,4 @@
-# Welcome to Starboard
+# Welcome to {{ config.site_name }}!
 
 Starboard integrates security tools into the Kubernetes environment, so that
 users can find and view the risks that relate to different resources in

diff --git a/docs/operator/installation/helm.md b/docs/operator/installation/helm.md
@@ -9,7 +9,7 @@ configure it to watch the `default` namespaces:
 
 1. Clone the chart repository:
    ```
-   git clone --depth 1 --branch v0.9.0 https://github.com/aquasecurity/starboard.git
+   git clone --depth 1 --branch {{ var.version }} https://github.com/aquasecurity/starboard.git
    cd starboard
    ```
 2. Create the `starboard-operator` namespace:
@@ -23,7 +23,7 @@ configure it to watch the `default` namespaces:
    If you skip this step, the operator will ensure [configuration objects](./../../settings.md)
    on startup with the default settings:
    ```
-   kubectl apply -f https://raw.githubusercontent.com/aquasecurity/starboard/v0.9.0/deploy/static/05-starboard-operator.config.yaml
+   kubectl apply -f https://raw.githubusercontent.com/aquasecurity/starboard/{{ var.version }}/deploy/static/05-starboard-operator.config.yaml
    ```
    Review the default values and makes sure the operator is configured properly:
    ```

diff --git a/docs/operator/installation/kubectl.md b/docs/operator/installation/kubectl.md
@@ -8,15 +8,15 @@ watch the `default` namespace:
 
 1. Send custom resource definitions to the Kubernetes API:
    ```
-   kubectl apply -f https://raw.githubusercontent.com/aquasecurity/starboard/v0.9.0/deploy/crd/vulnerabilityreports.crd.yaml \
-     -f https://raw.githubusercontent.com/aquasecurity/starboard/v0.9.0/deploy/crd/configauditreports.crd.yaml
+   kubectl apply -f https://raw.githubusercontent.com/aquasecurity/starboard/{{ var.version }}/deploy/crd/vulnerabilityreports.crd.yaml \
+     -f https://raw.githubusercontent.com/aquasecurity/starboard/{{ var.version }}/deploy/crd/configauditreports.crd.yaml
    ```
 2. Send the following Kubernetes objects definitions to the Kubernetes API:
    ```
-   kubectl apply -f https://raw.githubusercontent.com/aquasecurity/starboard/v0.9.0/deploy/static/01-starboard-operator.ns.yaml \
-     -f https://raw.githubusercontent.com/aquasecurity/starboard/v0.9.0/deploy/static/02-starboard-operator.sa.yaml \
-     -f https://raw.githubusercontent.com/aquasecurity/starboard/v0.9.0/deploy/static/03-starboard-operator.clusterrole.yaml \
-     -f https://raw.githubusercontent.com/aquasecurity/starboard/v0.9.0/deploy/static/04-starboard-operator.clusterrolebinding.yaml
+   kubectl apply -f https://raw.githubusercontent.com/aquasecurity/starboard/{{ var.version }}/deploy/static/01-starboard-operator.ns.yaml \
+     -f https://raw.githubusercontent.com/aquasecurity/starboard/{{ var.version }}/deploy/static/02-starboard-operator.sa.yaml \
+     -f https://raw.githubusercontent.com/aquasecurity/starboard/{{ var.version }}/deploy/static/03-starboard-operator.clusterrole.yaml \
+     -f https://raw.githubusercontent.com/aquasecurity/starboard/{{ var.version }}/deploy/static/04-starboard-operator.clusterrolebinding.yaml
    ```
 3. (Optional) Configure Starboard by creating the `starboard` ConfigMap and the `starboard` secret in
    the `starboard-operator` namespace. For example, you can use Trivy
@@ -25,7 +25,7 @@ watch the `default` namespace:
    If you skip this step, the operator will ensure [configuration objects](./../../settings.md)
    on startup with the default settings:
    ```
-   kubectl apply -f https://raw.githubusercontent.com/aquasecurity/starboard/v0.9.0/deploy/static/05-starboard-operator.config.yaml
+   kubectl apply -f https://raw.githubusercontent.com/aquasecurity/starboard/{{ var.version }}/deploy/static/05-starboard-operator.config.yaml
    ```
    Review the default values and makes sure the operator is configured properly:
    ```
@@ -35,7 +35,7 @@ watch the `default` namespace:
 4. Finally, create the `starboard-operator` Deployment in the `starboard-operator`
    namespace to start the operator's pod:
    ```
-   kubectl apply -f https://raw.githubusercontent.com/aquasecurity/starboard/v0.9.0/deploy/static/06-starboard-operator.deployment.yaml
+   kubectl apply -f https://raw.githubusercontent.com/aquasecurity/starboard/{{ var.version }}/deploy/static/06-starboard-operator.deployment.yaml
    ```
 5. To confirm that the operator is running, check the number of replicas created by
    the `starboard-operator` Deployment in the `starboard-operator` namespace:
@@ -55,19 +55,19 @@ watch the `default` namespace:
 You can uninstall the operator with the following command:
 
 ```
-kubectl delete -f https://raw.githubusercontent.com/aquasecurity/starboard/v0.9.0/deploy/static/06-starboard-operator.deployment.yaml \
-  -f https://raw.githubusercontent.com/aquasecurity/starboard/v0.9.0/deploy/static/05-starboard-operator.config.yaml \
-  -f https://raw.githubusercontent.com/aquasecurity/starboard/v0.9.0/deploy/static/04-starboard-operator.clusterrolebinding.yaml \
-  -f https://raw.githubusercontent.com/aquasecurity/starboard/v0.9.0/deploy/static/03-starboard-operator.clusterrole.yaml \
-  -f https://raw.githubusercontent.com/aquasecurity/starboard/v0.9.0/deploy/static/02-starboard-operator.sa.yaml \
-  -f https://raw.githubusercontent.com/aquasecurity/starboard/v0.9.0/deploy/static/01-starboard-operator.ns.yaml
+kubectl delete -f https://raw.githubusercontent.com/aquasecurity/starboard/{{ var.version }}/deploy/static/06-starboard-operator.deployment.yaml \
+  -f https://raw.githubusercontent.com/aquasecurity/starboard/{{ var.version }}/deploy/static/05-starboard-operator.config.yaml \
+  -f https://raw.githubusercontent.com/aquasecurity/starboard/{{ var.version }}/deploy/static/04-starboard-operator.clusterrolebinding.yaml \
+  -f https://raw.githubusercontent.com/aquasecurity/starboard/{{ var.version }}/deploy/static/03-starboard-operator.clusterrole.yaml \
+  -f https://raw.githubusercontent.com/aquasecurity/starboard/{{ var.version }}/deploy/static/02-starboard-operator.sa.yaml \
+  -f https://raw.githubusercontent.com/aquasecurity/starboard/{{ var.version }}/deploy/static/01-starboard-operator.ns.yaml
 ```
 
 Delete custom resources definitions:
 
 ```
-kubectl delete -f https://raw.githubusercontent.com/aquasecurity/starboard/v0.9.0/deploy/crd/vulnerabilityreports.crd.yaml \
-  -f https://raw.githubusercontent.com/aquasecurity/starboard/v0.9.0/deploy/crd/configauditreports.crd.yaml
+kubectl delete -f https://raw.githubusercontent.com/aquasecurity/starboard/{{ var.version }}/deploy/crd/vulnerabilityreports.crd.yaml \
+  -f https://raw.githubusercontent.com/aquasecurity/starboard/{{ var.version }}/deploy/crd/configauditreports.crd.yaml
 ```
 
 !!! danger

diff --git a/docs/operator/installation/olm.md b/docs/operator/installation/olm.md
@@ -36,7 +36,7 @@ configure it to watch the `default` namespaces:
    If you skip this step, the operator will ensure [configuration objects](./../../settings.md)
    on startup with the default settings:
    ```
-   kubectl apply -f https://raw.githubusercontent.com/aquasecurity/starboard/v0.9.0/deploy/static/05-starboard-operator.config.yaml
+   kubectl apply -f https://raw.githubusercontent.com/aquasecurity/starboard/{{ var.version }}/deploy/static/05-starboard-operator.config.yaml
    ```
    Review the default values and makes sure the operator is configured properly:
    ```
@@ -95,7 +95,7 @@ To uninstall the operator delete the Subscription, the ClusterServiceVersion, an
 
 ```
 kubectl delete subscription starboard-operator -n starboard-operator
-kubectl delete clusterserviceversion starboard-operator.v0.9.0 -n starboard-operator
+kubectl delete clusterserviceversion starboard-operator.{{ var.version }} -n starboard-operator
 kubectl delete operatorgroup starboard-operator -n starboard-operator
 ```
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -48,6 +48,16 @@ markdown_extensions:
   - pymdownx.superfences
   - admonition
 
+# All data defined under extra is automatically exposed as a variable and can
+# be used from the template. For example, {{ var.version }}.
+#
+# Requires pip install mike and pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
 extra:
   version:
     method: mike
+  var:
+    version: "v0.9.0"
+
+# Requires pip install mkdocs-macros-plugin
+plugins:
+  - macros