Wiki source code of How to setup an XWiki docker container

Version 32.1 by Alexandru Pentilescu on 2022/06/09 21:58

version	line-number	content
1.1	1	This page will give detailed information on how to setup a docker container for a XWiki server on a linux machine that you have administrative privileges on. This guide will allow you to accomplish such a setup in a straight-forward way.
	2
	3	But first, the following assumptions must be true:
	4
	5	* You have sudo rights on the machine where you're trying to install the XWiki server on
	6	* This machine already has docker fully installed and properly configured on it. Please perform a test installation of any random image from docker hub to ensure that everything works appropriately
	7	* You already own and are in control of a domain name for which you wish to make the XWiki server accessible through. This domain name is already pre-configured to point to the server that you wish to install XWiki on. In my particular case, I already have pentilescu.com configured to point to my VPS and, what I wished to accomplish was to have a subdomain via which I could access XWiki. In this particular case, this subdomain was wiki.pentilescu.com. To that end, you must have nginx also configured and running on the same server in the background, to have it redirect connections whose destination is a specific port to a subdomain
	8	* Finally, you must have an SMTP email server running somewhere accessible to the docker instance. XWiki will need to use this server to relay account activation emails as well as password reset emails to its users
	9
	10	With all of these details in mind, let's begin!
	11
31.1	12	{{box title="Contents"}}{{toc /}}{{/box}}
26.1	13
1.1	14	----
	15
	16
	17	= Configuring an appropriate docker-compose setup =
	18
2.1	19	On the machine you wish to run the docker instance on, please go to a directory where you have write access to and make a directory specifically for the docker files that XWiki and its database will write all of their persistent data to. In my particular case, I went to "/home/alex/Scripts/" and created an empty "xwiki" directory in it. The exact location of this directory is not particularly important but, if you do regular backups of your machine and you wish for all the XWiki data to also be backed up by these processes, keep in mind to create this folder in a location that's being backed up by your preferred solution, as this directory will contain all the database and XWiki pages that you will be creating, including all attachments uploaded by your users.
	20
	21	Afterwards, in this newly created directory, please create the following empty subdirectory: mariadb
	22	This subdirectory will contain the contents of two configuration files that will later be mapped by docker into the XWiki containers. After creating the "mariadb" directory, cd into it and then run the following bash command in it:
	23
	24	{{code language="bash"}}
	25	wget https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/14/mariadb-tomcat/mariadb/init.sql
	26	wget https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/14/mariadb-tomcat/mariadb/xwiki.cnf
	27	{{/code}}
	28
	29	PLEASE NOTE: THE ABOVE LINKS MAY BE OUTDATED. Please click [[here>>https://github.com/xwiki/xwiki-docker/blob/master/README.md#for-mysql-on-tomcat]] to find a most likely more up to date version of those links
	30
	31	Finally, once both of those files are downloaded, please proceed to cd back into the parent directory (which is "xwiki" in my case) and then create a docker-compose.yml file with the following contents:
	32
	33	{{code language="yaml"}}
	34	# ---------------------------------------------------------------------------
	35	# See the NOTICE file distributed with this work for additional
	36	# information regarding copyright ownership.
	37	#
	38	# This is free software; you can redistribute it and/or modify it
	39	# under the terms of the GNU Lesser General Public License as
	40	# published by the Free Software Foundation; either version 2.1 of
	41	# the License, or (at your option) any later version.
	42	#
	43	# This software is distributed in the hope that it will be useful,
	44	# but WITHOUT ANY WARRANTY; without even the implied warranty of
	45	# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
	46	# Lesser General Public License for more details.
	47	#
	48	# You should have received a copy of the GNU Lesser General Public
	49	# License along with this software; if not, write to the Free
	50	# Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
	51	# 02110-1301 USA, or see the FSF site: http://www.fsf.org.
	52	# ---------------------------------------------------------------------------
	53	version: '2'
	54	networks:
	55	bridge:
	56	driver: bridge
	57	services:
	58	# The container that runs XWiki + Tomcat
	59	web:
	60	image: "xwiki:lts-mariadb-tomcat"
	61	container_name: xwiki-mariadb-tomcat-web
	62	depends_on:
	63	- db
	64	ports:
	65	- "8081:8080"
	66	# Default values defined in .env file.
	67	# The DB_USER/DB_PASSWORD/DB_DATABASE/DB_HOST variables are used in the hibernate.cfg.xml file.
	68	environment:
	69	- XWIKI_VERSION=${XWIKI_VERSION}
	70	- DB_USER=${DB_USER}
	71	- DB_PASSWORD=${DB_PASSWORD}
	72	- DB_DATABASE=${DB_DATABASE}
	73	- DB_HOST=xwiki-mariadb-db
	74	# Provide a name instead of an auto-generated id for xwiki data (the permanent directory in included in it)
	75	# configured in the Dockerfile, to make it simpler to identify in 'docker volume ls'.
	76	volumes:
	77	- ./data/xwiki-data:/usr/local/xwiki
	78	networks:
	79	internal_xwiki_network:
	80	ipv4_address: 192.168.80.3
	81	# The container that runs the database (mariadb)
	82	db:
	83	image: "mariadb:10.5"
	84	container_name: xwiki-mariadb-db
	85	# - We provide a xwiki.cnf file in order to configure the mysql db to support UTF8 and be case-insensitive
	86	# We have to do it here since we use an existing image and that's how this image allows customizations.
	87	# See https://hub.docker.com/_/mariadb/ for more details.
	88	# - Provide a name instead of an auto-generated id for the mariadb data, to make it simpler to identify in
	89	# 'docker volume ls'
	90	volumes:
	91	- ./mariadb/xwiki.cnf:/etc/mysql/conf.d/xwiki.cnf
	92	- ./data/mariadb-data:/var/lib/mysql
	93	- ./mariadb/init.sql:/docker-entrypoint-initdb.d/init.sql
	94
	95	# Configure the MariaDB database and create a user with provided name/password.
	96	# See https://hub.docker.com/_/mariadb/ for more details.
	97	# Default values defined in .env file.
	98	environment:
	99	- MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
	100	- MYSQL_USER=${DB_USER}
	101	- MYSQL_PASSWORD=${DB_PASSWORD}
	102	- MYSQL_DATABASE=${DB_DATABASE}
	103	networks:
	104	internal_xwiki_network:
	105	ipv4_address: 192.168.80.4
	106
	107	networks:
	108	internal_xwiki_network:
	109	driver: bridge
	110	ipam:
	111	driver: default
	112	config:
	113	- subnet: 192.168.80.0/24
	114	{{/code}}
	115
	116	There are many different configurations you can use to have an XWiki server. For one, mariadb is NOT required to install XWiki, it's simply one of many database solutions that XWiki is compatible with. Alternatively, you may use MySQL or even PostgreSQL, instead. To see docker-compose configuration options for those, please reference the full official docker reference guide for XWiki at the "External references" section of this page for more details. Keep in mind, though, in case you do decide to use an alternative to mariadb, to download a different init.sql file than the one mentioned in the previous step!
	117
3.1	118	Finally, in the current directory that you are in, please create another subdirectory called "data" containing the empty subdirectories "mariadb-data" and "xwiki-data". The mariadb-data directory will contain all the persistent data from the database and the xwiki-data will contain the persistent data with respect to our XWiki installation, such as XWiki extensions, icons, as well as user-uploaded attachments.
2.1	119
3.1	120	One last note: the subnet 192.168.80.x IP address space configured for our docker network may be changed to whatever suits your particular needs, although, if you do use a different IP space, please keep in mind to also change the reference "mynetworks" configuration for postfix accordingly, as explained in the "Configuring Postfix to send XWiki emails" section of this page.
	121
4.1	122	Now, all we need to do is create a ".env" file in the main directory ("xwiki" is the name of my directory) containing the following contents:
	123
	124	{{code language="ini"}}
	125	DB_USER=xwiki
	126	DB_PASSWORD=<database_password>
	127	MYSQL_ROOT_PASSWORD=<mysql_root_password>
	128	DB_DATABASE=xwiki
	129	XWIKI_VERSION=1.0
	130	{{/code}}
	131
5.1	132	Please replace <database_password> and <mysql_root_password> with randomly generated long strings, preferrably containing a long sequence of lowercase, uppercase letters, digits and symbols. In my case, I chose 12 character long sequences for each of them. It's unlikely for a hacker to compromise your docker environment but it's still best practice to make the passwords as long and hard to guess as possible, as an extra layer of security.
	133
6.1	134
9.1	135	= First run of the container =
	136
6.1	137	The first run is always the scariest. Start up the docker image and wait for everything to initialize:
8.1	138
6.1	139	{{code language="bash"}}
	140	docker-compose up -d
	141	{{/code}}
	142
9.1	143	If you followed along just the way I described in this article, you shouldn't have any problems with this step. Note that XWiki takes a significant amount of time to initialize, around 10 minutes.
	144
	145	Take your time and don't rush!
	146
10.1	147	When you want to see the status of your installation, visit the domain name pointing to your server at port 8081. In my case, I would visit http://pentilescu.com:8081/
9.1	148
11.1	149	You might see a page indicating that XWiki is initializing, as well as a percentage counter indicating its progress. Let the server finish doing its thing.
	150
	151	In the end, you should see an image like the one below:
	152
14.1	153	[[image:Screenshot_20220607_015727.png]]
11.1	154
16.1	155	While it may be tempting to immediately try to setup an administrator account from this portal, unless you're browsing this page from localhost (i.e. the XWiki server is on the exact same machine that you're running your web browser from) DO NOT register an account YET! All traffic is unencrypted to the server and may be intercepted by anyone sniffing your internet packets. We must first configure an X.509 TLS certificate with Nginx and configure Nginx to act as a reverse proxy for this wiki
15.1	156
	157	For the time being, press the "Later" button on the dialog (not the "Never" one!) and then run a "docker-compose down" to stop the container from running. The first test run was a success! Congratulations!
	158
17.1	159	= Nginx reverse proxy configuration =
	160
16.1	161	We assume you already have Nginx installed and properly configured on your machine. Also, we will assume you have an X.509 certificate whose Subject Alt Names includes both your domain name, as well as the subdomain for your wiki (i.e. in my case for pentilescu.com and wiki.pentilescu.com, respectively) and you've configured Nginx to utilize both of them! If this is not the case or you're unsure how to perform these configurations, please check the internal "How to setup an Nginx reverse proxy and also provide a global X.509 certificate for it" guide at the bottom of this page.
	162
17.1	163	In "/etc/nginx/sites-available/", please create a "xwiki.conf" file with the following contents:
	164
20.1	165	{{code language="nginx"}}
17.1	166	server {
	167	server_name wiki.pentilescu.com;
	168
	169	listen [::]:443 ssl http2; # managed by Certbot
	170	listen 443 ssl http2; # managed by Certbot
	171
	172	include /etc/nginx/snippets/ssl.conf;
	173
	174	location / {
	175	proxy_pass http://localhost:8081;
	176	}
	177	}
	178	{{/code}}
	179
	180	Please replace "wiki.pentilescu.com" with the domain and subdomains that you desire for your particular website. Also, please adapt "/etc/nginx/snippets/ssl.conf" to reference the X.509 Nginx configuration file on your particular server. If you do not wish to support TLS at all, you may remove this line, as well as the "listen" directives from above.
	181
	182	Effectively, what this configuration file will do is tell Nginx to redirect all HTTP/HTTPS connection verbs directed at wiki.pentilescu.com to localhost port 8081, optionally also injecting the TLS certificates into the connection to secure it as well. By doing this, instead of having to connect to port 8081 on your server manually, future users of your XWiki instance will have to type the subdomain in their browser's address bar instead, which is usually more human readable and more memorable for most people. Typing in "wiki.pentilescu.com" into your browser's address bar is more human friendly than typing "pentilescu.com:8081". Not only are numeric port numbers difficult to remember, but Nginx will also inject TLS into the connection to secure it if you configured the X.509 certificates properly, effectively securing your visitors' connection every time so that their login credentials are protected even against network sniffers.
	183
	184	Once you've done this, create a symbolic link with the following command to activate your new configuration:
	185
	186	{{code language="bash"}}
	187	sudo ln -s /etc/nginx/sites-available/xwiki.conf /etc/nginx/sites-enabled/xwiki.conf
	188	{{/code}}
	189
18.1	190	Finally, test your configuration before restarting Nginx with:
	191
	192	{{code language="bash"}}
	193	sudo nginx -t
	194	{{/code}}
	195
	196	If errors are reported, please review your configuration files and repair all the detected issues. If everything is fine then issue a "sudo systemctl restart nginx" and then you're pretty much good to go!
	197
25.1	198	= Retrieving files for installing the Standard flavor packages and all its extensions=
	199	While the docker container contains all the necessary system utilities to run the XWiki server internally, a lot of functionality for the Wiki will be missing as it is.
	200	The XWiki container is very lackluster even in administration features and not installing the Standard flavor will give you a very barebones and almost functionally broken experience. As such, while optional, it is very strongly encouraged to install the Standard flavor along with XWiki to activate many of its most basic features.
	201	To do so, we will have to download a very specific XIP package from XWiki's download portal. Visit [[here>>https://www.xwiki.org/xwiki/bin/view/Download/]] this aforementioned download portal and click the "Download" button for the Long Term Support option on that page. On the new page, click the "Download" button for the "XIP Package" section. This will allow you to download the XIP package in question to your local computer.
	202	Unzip the contents of this XIP package (XIP is just a specific flavor of a ZIP archive so you can just rename the file to use the ".zip" extension if your archive program doesn't recognize it) and upload the unzipped contents to the server where the docker image of XWiki is running, under the "data/xwiki-data/data/extension/repository/" subdirectory of your XWiki directory.
32.1	203	Once this has been done, you may issue a "docker-compose up -d" again to start up the XWiki engine once again. Now that the files have been delivered to their expected disk location and are accessible to the engine, you will be good to go to install them efficiently.
	204	There are other means of installing the Standard flavor as well, as detailed [[here>>https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Installation/#HOthermethods]]. Choose whichever alternative you wish!
	205
	206	Once the XWiki engine has initialized its start state properly, you may visit your XWiki instance by going into the browser and accessing the wiki via your Nginx configured subdomain, rather than by port 8081 as we previously did. If you opted to also configure Nginx to inject TLS into the connection, you should now see the green lock in your web browser, next to the address bar, indicating that your connection to your server is encrypted and protected from any network sniffers. You may now proceed to both create an administrative account, as well as install the Standard flavor.
	207
	208
	209	= Initial XWiki setup for administrative account and installing the Standard flavor=
	210
2.1	211	= External references =
5.1	212
2.1	213	[[Official docker guide for installing XWiki>>https://github.com/xwiki/xwiki-docker/blob/master/README.md]]
17.1	214	How to setup an Nginx reverse proxy and also provide a global X.509 certificate for it -- NOT YET WRITTEN!--