Changes for page XWiki (Helm)

Last modified by Itzhak Daniel on 2024/04/29 16:35
From version 13.1
edited by Itzhak Daniel
on 2024/04/29 00:25
Change comment: There is no comment for this version
To version 5.1
edited by Itzhak Daniel
on 2024/04/28 20:10
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -1,15 +1,14 @@
1 -(% class="row" %)
2 -(((
3 -(% class="col-xs-12 col-sm-8" %)
4 -(((
1 +~(% class="box" %)
2 +~(~(~(
3 +~*~*Contents~*~*
4 +
5 +~{~{toc/}}
6 +~)~)~)
7 +
5 5  == About ==
6 6  
7 7  **XWiki** is a [[free>>url:https://en.wikipedia.org/wiki/Free_software]] [[wiki software>>url:https://en.wikipedia.org/wiki/Wiki_software]] platform written in [[Java>>url:https://en.wikipedia.org/wiki/Java_(programming_language)]] with a design emphasis on extensibility. As an [[application wiki>>url:https://en.wikipedia.org/wiki/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>>url:https://en.wikipedia.org/wiki/Jakarta_Velocity]], [[Apache Groovy>>url:https://en.wikipedia.org/wiki/Groovy_(programming_language)]], [[Python>>url:https://en.wikipedia.org/wiki/Python_(programming_language)]], [[Ruby>>url:https://en.wikipedia.org/wiki/Ruby_(programming_language)]] and [[PHP>>url:https://en.wikipedia.org/wiki/PHP]] can be written directly into wiki pages using wiki [[macros>>url:https://en.wikipedia.org/wiki/Macro_(computer_science)]]. XWiki code is licensed under the [[GNU Lesser General Public License>>url:https://en.wikipedia.org/wiki/GNU_Lesser_General_Public_License]] and hosted on [[GitHub>>url:https://en.wikipedia.org/wiki/GitHub]] where everyone is free to [[fork>>url:https://en.wikipedia.org/wiki/Fork_(software_development)]] the source code and develop changes in their own repository. While most of the active developers are funded by commercial support company XWiki [[SAS>>url:https://en.wikipedia.org/wiki/Soci%C3%A9t%C3%A9_par_actions_simplifi%C3%A9e]], XWiki SAS maintains a strict boundary between itself and the XWiki free software project. ~[[[source>>https://en.wikipedia.org/wiki/XWiki]]]
8 8  
9 -=== Security ===
10 -
11 -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.
12 -
13 13  == Background ==
14 14  
15 15  [[Behemoth LTD>>https://www.behemoth.co.il/]] was in a search for a 'knowledge base' software, a central place to collect and collaborate on documents which hold information, instructions, guide, etc. The requirement was simple, it required to be able to run on Kubernetes without too much customization, building, testing and other complex CI/CD prerequisite.
... ... @@ -20,167 +20,17 @@
20 20  
21 21  Here is the list of things you need to have:
22 22  
23 -* Kubernetes 1.27+.
24 -** Automatic storage provisioner.
25 -** Ingress-nginx.
26 -** Cert-manager.
27 -* Helm 3.12+.
28 -* XWiki 16.2.0.
29 -** Custom Image (non-root).
22 +* Kubernetes 1.27 (probably will work with later versions as well).
23 +** Automatic storage provisioner (Behemoth LTD special case).
24 +* Helm 3.12 (probably will work with later versions as well).
30 30  
26 +== Deploying ==
27 +
28 +We're going to deploy XWiki as a [[statefulset>>https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/]], the Database (MySQL) and the App, each will have a volume to store their content.
29 +
31 31  === Note about Storage ===
32 32  
33 -Behemoth LTD is running an on-prem Kubernetes solution, we (currently) don't have any shared storage solution ([[ceph>>https://docs.ceph.com/]], [[nfs>>https://github.com/kubernetes-csi/csi-driver-nfs]], [[...>>https://kubernetes.io/docs/concepts/storage/storage-classes/#provisioner]]) , which require two things from us:
32 +Behemoth LTD is running an on-prem Kubernetes solutions, we (currently?) don't have any shared storage solution ([[ceph>>https://docs.ceph.com/]], [[nfs>>https://github.com/kubernetes-csi/csi-driver-nfs]], [[...>>https://kubernetes.io/docs/concepts/storage/storage-classes/#provisioner]]) , which require two things:
34 34  
35 35  1. Creating the path/loop device prior of creating PV.
36 36  1. The PV is manually created.
37 -
38 -You may not need that if your cluster knows to provision storage by itself.
39 -
40 -== CI/CD ==
41 -
42 -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.
43 -
44 -=== Building and Publish ===
45 -
46 -You will need to perform the following actions:
47 -
48 -{{code language="sh" layout="LINENUMBERS" title="# Clone the repository"}}
49 -git clone --depth 1 --branch master https://github.com/xwiki/xwiki-docker.git
50 -{{/code}}
51 -
52 -Once you have the repo locally, modify the //Dockerfile// as shown below:
53 -
54 -{{code language="git" title="# Diff"}}
55 -@@ -89,6 +89,11 @@ COPY xwiki/docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
56 - # across runs)
57 - VOLUME /usr/local/xwiki
58 -
59 -+# Added by Behemoth LTD - Apr 28th, 2024
60 -+# Fixing permissions error when using non-root user/group (30001:30001) to start the app
61 -+RUN chown -R 30001:30001 /usr/local/tomcat/webapps
62 -+USER 30001:30001
63 -+
64 - # At this point the image is done and what remains below are the runtime configuration used by the user to configure
65 - # the container that will be created out of the image. Namely the user can override some environment variables with
66 - # docker run -e "var1=val1" -e "var2=val2" ...
67 -
68 -{{/code}}
69 -
70 -Once the changes have been made, build and push it to your repository.
71 -
72 -{{code language="sh" layout="LINENUMBERS" title="# Docker"}}
73 -cd ./16/mysql-tomcat/
74 -docker build -t behemothil/xwiki-mysql-tomcat-nonroot:16.2.0-2 .
75 -docker login
76 -docker push behemothil/xwiki-mysql-tomcat-nonroot:16.2.0-2
77 -{{/code}}
78 -
79 -{{code language="sh" layout="LINENUMBERS" title="# Podman"}}
80 -cd ./16/mysql-tomcat/
81 -buildah build -f Dockerfile -t behemothil/xwiki-mysql-tomcat-nonroot:16.2.0-2
82 -docker push --creds=[Username:[Password]] behemothil/xwiki-mysql-tomcat-nonroot:16.2.0-2
83 -{{/code}}
84 -
85 -=== Deploy ===
86 -
87 -We're going to deploy XWiki as a [[statefulset>>https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/]] using [[Helm>>https://helm.sh/]], 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.
88 -
89 -After the path/loop devices were created, create the PVs (only if your cluster doesn't know how to provision storage for itself):
90 -
91 -{{code language="sh" layout="LINENUMBERS" title="# kubectl stdin"}}
92 -kubectl create -f - <<EOF
93 ----
94 -kind: PersistentVolume
95 -apiVersion: v1
96 -metadata:
97 - name: behemoth-xwiki-db
98 - namespace: behemoth-wiki
99 - labels:
100 - type: behemoth-xwiki-db
101 -spec:
102 - storageClassName: behemoth-xwiki-db
103 - capacity:
104 - storage: 5Gi
105 - accessModes:
106 - - ReadWriteOnce
107 - hostPath:
108 - path: "/mnt/kubenernetes/behemoth-xwiki/db"
109 - nodeAffinity:
110 - required:
111 - nodeSelectorTerms:
112 - - matchExpressions:
113 - - key: kubernetes.io/hostname
114 - operator: In
115 - values:
116 - - k8s-uk-2
117 -
118 ----
119 -kind: PersistentVolume
120 -apiVersion: v1
121 -metadata:
122 - name: behemoth-xwiki-www
123 - namespace: behemoth-wiki
124 - labels:
125 - type: behemoth-xwiki-www
126 -spec:
127 - storageClassName: behemoth-xwiki-www
128 - capacity:
129 - storage: 5Gi
130 - accessModes:
131 - - ReadWriteOnce
132 - hostPath:
133 - path: "/mnt/kubenernetes/behemoth-xwiki/www"
134 - nodeAffinity:
135 - required:
136 - nodeSelectorTerms:
137 - - matchExpressions:
138 - - key: kubernetes.io/hostname
139 - operator: In
140 - values:
141 - - k8s-uk-2
142 -EOF
143 -{{/code}}
144 -
145 -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).
146 -
147 -Now we can install XWiki's charts (repo) and download it's //values.yaml// file:
148 -
149 -{{code language="sh" layout="LINENUMBERS" title="# Charts and Values"}}
150 -helm repo add xwiki-helm https://xwiki-contrib.github.io/xwiki-helm
151 -helm repo update xwiki-helm
152 -
153 -curl -LO https://raw.githubusercontent.com/xwiki-contrib/xwiki-helm/master/charts/xwiki/values.yaml
154 -{{/code}}
155 -
156 -Modify the values.yaml file, our example has:
157 -
158 -* Using custom image (so it won't run as //root//).
159 -* Increased memory/core usage allowance.
160 -* Running as UID/GID 30001.
161 -* Dropping all capabilities.
162 -* Using MySQL.
163 -* Enabling persistence.
164 -* Ingress (Nginx).
165 -* TLS (Cert manager)
166 -
167 -You can download our example from the attachment area.
168 -
169 -Once you have your custom //values.yaml// file, deploy the app with Helm:
170 -
171 -{{code language="sh" layout="LINENUMBERS" title="# Helm install"}}
172 -helm install --namespace behemoth-wiki --create-namespace \
173 - --values values.yaml \
174 - behemoth-xwiki xwiki-helm/xwiki
175 -{{/code}}
176 -
177 -
178 -)))
179 -
180 -(% class="col-xs-12 col-sm-4" %)
181 -(((
182 -{{box title="**Contents**"}}
183 -{{toc numbered="true"/}}
184 -{{/box}}
185 -)))
186 -)))
Dockerfile
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.itzhak
Size
... ... @@ -1,1 +1,0 @@
1 -6.6 KB
Content
... ... @@ -1,122 +1,0 @@
1 -# ---------------------------------------------------------------------------
2 -# See the NOTICE file distributed with this work for additional
3 -# information regarding copyright ownership.
4 -#
5 -# This is free software; you can redistribute it and/or modify it
6 -# under the terms of the GNU Lesser General Public License as
7 -# published by the Free Software Foundation; either version 2.1 of
8 -# the License, or (at your option) any later version.
9 -#
10 -# This software is distributed in the hope that it will be useful,
11 -# but WITHOUT ANY WARRANTY; without even the implied warranty of
12 -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 -# Lesser General Public License for more details.
14 -#
15 -# You should have received a copy of the GNU Lesser General Public
16 -# License along with this software; if not, write to the Free
17 -# Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
18 -# 02110-1301 USA, or see the FSF site: http://www.fsf.org.
19 -# ---------------------------------------------------------------------------
20 -FROM tomcat:9-jre17
21 -
22 -# ____ ____ ____ ____ _ __ _
23 -# |_ _||_ _||_ _| |_ _|(_) [ | _ (_)
24 -# \ \ / / \ \ /\ / / __ | | / ] __
25 -# > `' < \ \/ \/ / [ | | '' < [ |
26 -# _/ /'`\ \_ \ /\ / | | | |`\ \ | |
27 -# |____||____| \/ \/ [___][__| \_][___]
28 -
29 -LABEL org.opencontainers.image.authors='XWiki Development Team <committers@xwiki.org>'
30 -LABEL org.opencontainers.image.url='https://hub.docker.com/_/xwiki'
31 -LABEL org.opencontainers.image.documentation='https://hub.docker.com/_/xwiki'
32 -LABEL org.opencontainers.image.source='https://github.com/xwiki/xwiki-docker.git'
33 -LABEL org.opencontainers.image.vendor='xwiki.org'
34 -LABEL org.opencontainers.image.licenses='LGPL-2.1'
35 -
36 -# Note: when using docker-compose, the ENV values below are overridden from the .env file.
37 -
38 -# Install LibreOffice + other tools
39 -# Note that procps is required to get ps which is used by JODConverter to start LibreOffice
40 -RUN apt-get update && \
41 - apt-get --no-install-recommends -y install \
42 - curl \
43 - libreoffice \
44 - unzip \
45 - procps && \
46 - rm -rf /var/lib/apt/lists/*
47 -
48 -# Install XWiki as the ROOT webapp context in Tomcat
49 -# Create the Tomcat temporary directory
50 -# Configure the XWiki permanent directory
51 -ENV XWIKI_VERSION="16.2.0"
52 -ENV XWIKI_URL_PREFIX "https://maven.xwiki.org/releases/org/xwiki/platform/xwiki-platform-distribution-war/${XWIKI_VERSION}"
53 -ENV XWIKI_DOWNLOAD_SHA256 7d355ae1c88691b19af9658e3f042083d57c08d5e52e1ade25536536ad72fb3f
54 -RUN rm -rf /usr/local/tomcat/webapps/* && \
55 - mkdir -p /usr/local/tomcat/temp && \
56 - mkdir -p /usr/local/xwiki/data && \
57 - curl -fSL "${XWIKI_URL_PREFIX}/xwiki-platform-distribution-war-${XWIKI_VERSION}.war" -o xwiki.war && \
58 - echo "$XWIKI_DOWNLOAD_SHA256 xwiki.war" | sha256sum -c - && \
59 - unzip -d /usr/local/tomcat/webapps/ROOT xwiki.war && \
60 - rm -f xwiki.war
61 -
62 -# Copy the JDBC driver in the XWiki webapp
63 -# We take the database driver version from the Maven Central repository since we want to control the version
64 -# used and have it being consistent with what is tested in the CI.
65 -ENV MYSQL_JDBC_VERSION="8.3.0"
66 -ENV MYSQL_JDBC_SHA256="94e7fa815370cdcefed915db7f53f88445fac110f8c3818392b992ec9ee6d295"
67 -ENV MYSQL_JDBC_PREFIX="https://repo1.maven.org/maven2/com/mysql/mysql-connector-j/${MYSQL_JDBC_VERSION}"
68 -ENV MYSQL_JDBC_ARTIFACT="mysql-connector-j-${MYSQL_JDBC_VERSION}.jar"
69 -ENV MYSQL_JDBC_TARGET="/usr/local/tomcat/webapps/ROOT/WEB-INF/lib/${MYSQL_JDBC_ARTIFACT}"
70 -RUN curl -fSL "${MYSQL_JDBC_PREFIX}/${MYSQL_JDBC_ARTIFACT}" -o $MYSQL_JDBC_TARGET && \
71 - echo "$MYSQL_JDBC_SHA256 $MYSQL_JDBC_TARGET" | sha256sum -c -
72 -
73 -# Configure Tomcat. For example set the memory for the Tomcat JVM since the default value is too small for XWiki
74 -COPY tomcat/setenv.sh /usr/local/tomcat/bin/
75 -
76 -# Setup the XWiki Hibernate configuration
77 -COPY xwiki/hibernate.cfg.xml /usr/local/tomcat/webapps/ROOT/WEB-INF/hibernate.cfg.xml
78 -
79 -# Set a specific distribution id in XWiki for this docker packaging.
80 -RUN sed -i 's/<id>org.xwiki.platform:xwiki-platform-distribution-war/<id>org.xwiki.platform:xwiki-platform-distribution-docker/' \
81 - /usr/local/tomcat/webapps/ROOT/META-INF/extension.xed
82 -
83 -# Add scripts required to make changes to XWiki configuration files at execution time
84 -# Note: we don't run CHMOD since 1) it's not required since the executabe bit is already set in git and 2) running
85 -# CHMOD after a COPY will sometimes fail, depending on different host-specific factors (especially on AUFS).
86 -COPY xwiki/docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
87 -
88 -# Make the XWiki directory (the permanent directory is included in it) persist on the host (so that it's not recreated
89 -# across runs)
90 -VOLUME /usr/local/xwiki
91 -
92 -# Added by Behemoth LTD - Apr 28th, 2024
93 -# Fixing permissions error when using non-root user/group (30001:30001) to start the app
94 -RUN chown -R 30001:30001 /usr/local/tomcat/webapps
95 -USER 30001:30001
96 -
97 -# At this point the image is done and what remains below are the runtime configuration used by the user to configure
98 -# the container that will be created out of the image. Namely the user can override some environment variables with
99 -# docker run -e "var1=val1" -e "var2=val2" ...
100 -# The supported environment variables that can be overridden are:
101 -# - DB_USER: the name of the user configured for XWiki in the DB. Default is "xwiki". This is used to configure
102 -# xwiki's hibernate.cfg.xml file.
103 -# - DB_PASSWORD: the password for the user configured for XWiki in the DB. Default is "xwiki". This is used to
104 -# configure xwiki's hibernate.cfg.xml file.
105 -# - DB_DATABASE: the name of the database to use. Default is "xwiki". This is used to configure xwiki's
106 -# hibernate.cfg.xml file.
107 -# - DB_HOST: The name of the host (or docker container) containing the database. Default is "db". This is used to
108 -# configure xwiki's hibernate.cfg.xml file.
109 -# - CONTEXT_PATH: The name of the context path under which XWiki will be deployed in Tomcat. If not specified then it'll
110 -# be deployed as ROOT.
111 -# - JDBC_PARAMS: Replaces the default JDBC parameters with the passed ones.
112 -
113 -# Example:
114 -# docker run -it -e "DB_USER=xwiki" -e "DB_PASSWORD=xwiki" <imagename>
115 -
116 -# Starts XWiki by starting Tomcat. All options passed to "docker run [OPTIONS] IMAGE[:TAG|@DIGEST] [COMMAND] [ARG...]"
117 -# are also passed to docker-entrypoint.sh. If "xwiki" is passed then XWiki will be configured the first time the
118 -# container executes and Tomcat will be started. If some other parameter is passed then it'll be executed to comply
119 -# with best practices defined at https://github.com/docker-library/official-images#consistency.
120 -ENTRYPOINT ["docker-entrypoint.sh"]
121 -CMD ["xwiki"]
122 -
pv_storage.yaml
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.itzhak
Size
... ... @@ -1,1 +1,0 @@
1 -999 bytes
Content
... ... @@ -1,50 +1,0 @@
1 ----
2 -kind: PersistentVolume
3 -apiVersion: v1
4 -metadata:
5 - name: behemoth-xwiki-db
6 - namespace: behemoth-wiki
7 - labels:
8 - type: behemoth-xwiki-db
9 -spec:
10 - storageClassName: behemoth-xwiki-db
11 - capacity:
12 - storage: 5Gi
13 - accessModes:
14 - - ReadWriteOnce
15 - hostPath:
16 - path: "/mnt/kubenernetes/behemoth-xwiki/db"
17 - nodeAffinity:
18 - required:
19 - nodeSelectorTerms:
20 - - matchExpressions:
21 - - key: kubernetes.io/hostname
22 - operator: In
23 - values:
24 - - k8s-2
25 -
26 ----
27 -kind: PersistentVolume
28 -apiVersion: v1
29 -metadata:
30 - name: behemoth-xwiki-www
31 - namespace: behemoth-wiki
32 - labels:
33 - type: behemoth-xwiki-www
34 -spec:
35 - storageClassName: behemoth-xwiki-www
36 - capacity:
37 - storage: 5Gi
38 - accessModes:
39 - - ReadWriteOnce
40 - hostPath:
41 - path: "/mnt/kubenernetes/behemoth-xwiki/www"
42 - nodeAffinity:
43 - required:
44 - nodeSelectorTerms:
45 - - matchExpressions:
46 - - key: kubernetes.io/hostname
47 - operator: In
48 - values:
49 - - k8s-2
50 -