XWiki (Helm)

Last modified by Itzhak Daniel on 2024/04/29 16:35

About

XWiki is a free wiki software platform written in Java with a design emphasis on extensibility. As an application wiki, XWiki allows for the storing of structured data and the execution of server side script within the wiki interface. Scripting languages including Velocity, Apache Groovy, Python, Ruby and PHP can be written directly into wiki pages using wiki macros. XWiki code is licensed under the GNU Lesser General Public License and hosted on GitHub where everyone is free to fork the source code and develop changes in their own repository. While most of the active developers are funded by commercial support company XWiki SAS, XWiki SAS maintains a strict boundary between itself and the XWiki free software project. [source]

Security

XWiki is running as root by default, we had to rebuild the image in order to enable us to run it as an unprivileged user (uid/gid: 30001). With MySQL we didn't go to the same effort, but in that case we're running the process as uid/gid: 30001:0, which is far from perfect, but much better than running as the user root.

Background

Behemoth LTD was in a search for a 'knowledge base' software, a central place to collect and collaborate on documents which hold information, instructions, guides, etc. The requirement was simple, can run on Kubernetes without too much customization, building, testing and other complex CI/CD prerequisite.

Things may change in the future, as Kubernetes becomes the de-facto way to run Apps, so do some homework before continuing, Awesome Selfhosted.

Requirements

Here is the list of things you need to have:

  • Kubernetes 1.27+.
    • Automatic storage provisioner.
    • Ingress-nginx.
    • Cert-manager.
  • Helm 3.12+.
  • XWiki 16.2.0.
    • Custom Image (non-root).

Note about Storage

Behemoth LTD is running an on-prem Kubernetes solution, we (currently) don't have any shared storage solution (ceph, nfs, ...) , which require two things from us:

  1. Creating the path/loop device prior of creating PV.
  2. The PV is manually created.

You may not need that if your cluster knows to provision storage by itself.

CI/CD

At the beginning we tried to avoid making any custom changes to the images in question (XWiki and Bitnami's MySQL). But XWiki running as root, didn't fly. So we had to create a custom image with minor changes to enable it to run as a unprivileged uid/gid: 30001.

Build and Publish

You will need to perform the following actions:

# Clone the repository
1
git clone --depth 1 --branch master https://github.com/xwiki/xwiki-docker.git

Once you have the repo locally, modify the Dockerfile as shown below:

# Diff
@@ -89,6 +89,11 @@ COPY xwiki/docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
 # across runs)
 VOLUME /usr/local/xwiki

+# Added by Behemoth LTD - Apr 28th, 2024
+# Fixing permissions error when using non-root user/group (30001:30001) to start the app
+RUN chown -R 30001:30001 /usr/local/tomcat/webapps
+USER 30001:30001
+
 # At this point the image is done and what remains below are the runtime configuration used by the user to configure
 # the container that will be created out of the image. Namely the user can override some environment variables with
 #   docker run -e "var1=val1" -e "var2=val2" ...

Once the changes have been made, build and push it to your repository.

# Docker
1
2
3
4
cd ./16/mysql-tomcat/
docker build -t behemothil/xwiki-mysql-tomcat-nonroot:16.2.0-3 .
docker login
docker push behemothil/xwiki-mysql-tomcat-nonroot:16.2.0-3
# Podman
1
2
3
cd ./16/mysql-tomcat/
buildah build -f Dockerfile -t behemothil/xwiki-mysql-tomcat-nonroot:16.2.0-3
podman push --creds=[Username:[Password]] behemothil/xwiki-mysql-tomcat-nonroot:16.2.0-3

Deploy

We're going to deploy XWiki as a statefulset using Helm, the Database (MySQL) and the App, each will have a volume to store their information. As I mentioned, in our case, we need to perform several additional steps.

After the path/loop devices were created, create the PVs (only if your cluster doesn't know how to provision storage for itself):

# kubectl stdin
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
kubectl create -f - <<EOF
---
kind: PersistentVolume
apiVersion: v1
metadata:
  name: behemoth-xwiki-db
  namespace: behemoth-wiki
  labels:
    type: behemoth-xwiki-db
spec:
  storageClassName: behemoth-xwiki-db
  capacity:
    storage: 5Gi
  accessModes:
  - ReadWriteOnce
  hostPath:
    path: "/mnt/kubenernetes/behemoth-xwiki/db"
  nodeAffinity:
    required:
      nodeSelectorTerms:
        - matchExpressions:
            - key: kubernetes.io/hostname
              operator: In
              values:
                - k8s-uk-2

---
kind: PersistentVolume
apiVersion: v1
metadata:
  name: behemoth-xwiki-www
  namespace: behemoth-wiki
  labels:
    type: behemoth-xwiki-www
spec:
  storageClassName: behemoth-xwiki-www
  capacity:
    storage: 5Gi
  accessModes:
  - ReadWriteOnce
  hostPath:
    path: "/mnt/kubenernetes/behemoth-xwiki/www"
  nodeAffinity:
    required:
      nodeSelectorTerms:
      - matchExpressions:
        - key: kubernetes.io/hostname
          operator: In
          values:
          - k8s-uk-2
EOF

This will create 2 PVs that we'll use later. Notice nodeAffinity, linking the deployment to a specific node (the pods can run only at that location, as the PV is defined only there).

Now we can install XWiki's charts (repo) and download it's values.yaml file:

# Charts and Values
1
2
3
4
helm repo add xwiki-helm https://xwiki-contrib.github.io/xwiki-helm
helm repo update xwiki-helm

curl -LO https://raw.githubusercontent.com/xwiki-contrib/xwiki-helm/master/charts/xwiki/values.yaml

Modify the values.yaml file, our example has:

  • Using custom image (so it won't run as root).
  • Increased memory/core usage allowance.
  • Running as UID/GID 30001.
  • Dropping all capabilities.
  • Using MySQL.
  • Enabling persistence.
  • Ingress (Nginx).
  • TLS (Cert manager)

You can download our example from the attachment area.

Once you have your custom values.yaml file, deploy the app with Helm:

# Helm install
1
2
3
helm install --namespace behemoth-wiki --create-namespace \
  --values values.yaml \
  behemoth-xwiki xwiki-helm/xwiki

Upgrade

To upgrade XWiki, you should read the content in XWiki official Helm pages regarding upgrades.

Theoretically, if there aren't any breaking changes or prerequisites, you can run:

# Helm upgrade
1
2
3
4
helm repo update xwiki-helm
helm upgrade --namespace behemoth-wiki \
  --values values.yaml \
  behemoth-xwiki xwiki-helm/xwiki

Uninstall

To fully remove XWiki from your cluster, use the following commands:

# Uninstalling
1
2
3
4
5
helm uninstall --namespace behemoth-wiki behemoth-xwiki
kubectl -n behemoth-wiki delete pvc/data-behemoth-xwiki-mysql-0
kubectl -n behemoth-wiki delete pvc/xwiki-data-behemoth-xwiki-0
kubectl delete -f pv_storage.yaml
kubectl delete namespace behemoth-wiki

This will uninstall the chart, delete the PVCs, delete the PVs and lastly, delete the namespace.

  1. XWiki - Extensions - Helm
  2. Github - XWiki Contrib - Helm Charts
  3. Github - XWiki - Docker
  4. Docker Hub - XWiki - Official
  5. Docker Hub - Behemoth LTD - Custom XWiki Non-root Image
Contents
    1. About
      1. Security
    2. Background
    3. Requirements
      1. Note about Storage
    4. CI/CD
      1. Build and Publish
      2. Deploy
      3. Upgrade
      4. Uninstall
    5. Links