Wiki source code of XWiki (Helm)

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

version	line-number	content
6.1	1	(% class="row" %)
	2	(((
	3	(% class="col-xs-12 col-sm-8" %)
	4	(((
2.1	5	== About ==
	6
	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
7.1	9	=== Security ===
	10
8.1	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.
7.1	12
2.1	13	== Background ==
	14
18.1	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, guides, etc. The requirement was simple, can run on Kubernetes without too much customization, building, testing and other complex CI/CD prerequisite.
2.1	16
3.1	17	Things may change in the future, as Kubernetes becomes the de-facto way to run Apps, so do some homework before continuing, [[Awesome Selfhosted>>https://github.com/awesome-selfhosted/awesome-selfhosted#wikis]].
	18
	19	== Requirements ==
	20
	21	Here is the list of things you need to have:
	22
9.1	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).
3.1	30
4.1	31	=== Note about Storage ===
	32
11.1	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:
4.1	34
	35	1. Creating the path/loop device prior of creating PV.
	36	1. The PV is manually created.
8.1	37
9.1	38	You may not need that if your cluster knows to provision storage by itself.
8.1	39
9.1	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
16.1	44	=== Build and Publish ===
9.1	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
20.1	52	Once you have the repo locally, modify the [[//Dockerfile//>>attach:Dockerfile]] as shown below:
9.1	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/
20.1	74	docker build -t behemothil/xwiki-mysql-tomcat-nonroot:16.2.0-3 .
9.1	75	docker login
20.1	76	docker push behemothil/xwiki-mysql-tomcat-nonroot:16.2.0-3
9.1	77	{{/code}}
	78
	79	{{code language="sh" layout="LINENUMBERS" title="# Podman"}}
	80	cd ./16/mysql-tomcat/
20.1	81	buildah build -f Dockerfile -t behemothil/xwiki-mysql-tomcat-nonroot:16.2.0-3
	82	podman push --creds=[Username:[Password]] behemothil/xwiki-mysql-tomcat-nonroot:16.2.0-3
9.1	83	{{/code}}
	84
	85	=== Deploy ===
	86
11.1	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
20.1	89	After the path/loop devices were created, create the [[PVs>>attach:pv_storage.yaml]] (only if your cluster doesn't know how to provision storage for itself):
11.1	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
13.1	147	Now we can install XWiki's charts (repo) and download it's //values.yaml// file:
11.1	148
13.1	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
11.1	152
13.1	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
15.1	169	Once you have your custom [[//values.yaml//>>attach:values.yaml]] file, deploy the app with Helm:
13.1	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
16.1	177	=== Upgrade ===
15.1	178
	179	To upgrade XWiki, you should read the content in [[XWiki official Helm pages regarding upgrades>>https://extensions.xwiki.org/xwiki/bin/view/Extension/XWikiHelm/#HUpgrading]].
	180
	181	Theoretically, if there aren't any breaking changes or prerequisites, you can run:
	182
	183	{{code language="sh" layout="LINENUMBERS" title="# Helm upgrade"}}
22.1	184	helm repo update xwiki-helm
15.1	185	helm upgrade --namespace behemoth-wiki \
	186	--values values.yaml \
	187	behemoth-xwiki xwiki-helm/xwiki
	188	{{/code}}
	189
16.1	190	=== Uninstall ===
15.1	191
22.1	192	To fully remove XWiki from your cluster, use the following commands:
15.1	193
	194	{{code language="sh" layout="LINENUMBERS" title="# Uninstalling"}}
	195	helm uninstall --namespace behemoth-wiki behemoth-xwiki
	196	kubectl -n behemoth-wiki delete pvc/data-behemoth-xwiki-mysql-0
	197	kubectl -n behemoth-wiki delete pvc/xwiki-data-behemoth-xwiki-0
	198	kubectl delete -f pv_storage.yaml
	199	kubectl delete namespace behemoth-wiki
	200	{{/code}}
	201
	202	This will uninstall the chart, delete the PVCs, delete the PVs and lastly, delete the namespace.
	203
	204	== Links ==
	205
16.1	206	1. [[XWiki - Extensions - Helm>>https://extensions.xwiki.org/xwiki/bin/view/Extension/XWikiHelm/]]
	207	1. [[Github - XWiki Contrib - Helm Charts>>https://github.com/xwiki-contrib/xwiki-helm]]
15.1	208	1. [[Github - XWiki - Docker>>https://github.com/xwiki/xwiki-docker/]]
	209	1. [[Docker Hub - XWiki - Official>>https://hub.docker.com/_/xwiki]]
17.1	210	1. [[Docker Hub - Behemoth LTD - Custom XWiki Non-root Image>>https://hub.docker.com/r/behemothil/xwiki-mysql-tomcat-nonroot]]
6.1	211	)))
	212
	213	(% class="col-xs-12 col-sm-4" %)
	214	(((
7.1	215	{{box title="Contents"}}
9.1	216	{{toc numbered="true"/}}
7.1	217	{{/box}}
6.1	218	)))
	219	)))

Wiki source code of XWiki (Helm)

Navigation

Child Pages