Skip to Content
Version 46.1 by Alexandru Pentilescu on 2022/06/09 23:19
Show last authors
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
12 {{box title="**Contents**"}}
13 {{toc /}}
14 {{/box}}
15
16 ----
17
18
19 = Configuring an appropriate docker-compose setup =
20
21 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.
22
23 Afterwards, in this newly created directory, please create the following empty subdirectory: mariadb
24 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:
25
26 {{code language="bash"}}
27 wget https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/14/mariadb-tomcat/mariadb/init.sql
28 wget https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/14/mariadb-tomcat/mariadb/xwiki.cnf
29 {{/code}}
30
31 **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**
32
33 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:
34
35 {{code language="yaml"}}
36 # ---------------------------------------------------------------------------
37 # See the NOTICE file distributed with this work for additional
38 # information regarding copyright ownership.
39 #
40 # This is free software; you can redistribute it and/or modify it
41 # under the terms of the GNU Lesser General Public License as
42 # published by the Free Software Foundation; either version 2.1 of
43 # the License, or (at your option) any later version.
44 #
45 # This software is distributed in the hope that it will be useful,
46 # but WITHOUT ANY WARRANTY; without even the implied warranty of
47 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
48 # Lesser General Public License for more details.
49 #
50 # You should have received a copy of the GNU Lesser General Public
51 # License along with this software; if not, write to the Free
52 # Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
53 # 02110-1301 USA, or see the FSF site: http://www.fsf.org.
54 # ---------------------------------------------------------------------------
55 version: '2'
56 networks:
57 bridge:
58 driver: bridge
59 services:
60 # The container that runs XWiki + Tomcat
61 web:
62 image: "xwiki:lts-mariadb-tomcat"
63 container_name: xwiki-mariadb-tomcat-web
64 depends_on:
65 - db
66 ports:
67 - "8081:8080"
68 # Default values defined in .env file.
69 # The DB_USER/DB_PASSWORD/DB_DATABASE/DB_HOST variables are used in the hibernate.cfg.xml file.
70 environment:
71 - XWIKI_VERSION=${XWIKI_VERSION}
72 - DB_USER=${DB_USER}
73 - DB_PASSWORD=${DB_PASSWORD}
74 - DB_DATABASE=${DB_DATABASE}
75 - DB_HOST=xwiki-mariadb-db
76 # Provide a name instead of an auto-generated id for xwiki data (the permanent directory in included in it)
77 # configured in the Dockerfile, to make it simpler to identify in 'docker volume ls'.
78 volumes:
79 - ./data/xwiki-data:/usr/local/xwiki
80 networks:
81 internal_xwiki_network:
82 ipv4_address: 192.168.80.3
83 # The container that runs the database (mariadb)
84 db:
85 image: "mariadb:10.5"
86 container_name: xwiki-mariadb-db
87 # - We provide a xwiki.cnf file in order to configure the mysql db to support UTF8 and be case-insensitive
88 # We have to do it here since we use an existing image and that's how this image allows customizations.
89 # See https://hub.docker.com/_/mariadb/ for more details.
90 # - Provide a name instead of an auto-generated id for the mariadb data, to make it simpler to identify in
91 # 'docker volume ls'
92 volumes:
93 - ./mariadb/xwiki.cnf:/etc/mysql/conf.d/xwiki.cnf
94 - ./data/mariadb-data:/var/lib/mysql
95 - ./mariadb/init.sql:/docker-entrypoint-initdb.d/init.sql
96
97 # Configure the MariaDB database and create a user with provided name/password.
98 # See https://hub.docker.com/_/mariadb/ for more details.
99 # Default values defined in .env file.
100 environment:
101 - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
102 - MYSQL_USER=${DB_USER}
103 - MYSQL_PASSWORD=${DB_PASSWORD}
104 - MYSQL_DATABASE=${DB_DATABASE}
105 networks:
106 internal_xwiki_network:
107 ipv4_address: 192.168.80.4
108
109 networks:
110 internal_xwiki_network:
111 driver: bridge
112 ipam:
113 driver: default
114 config:
115 - subnet: 192.168.80.0/24
116 {{/code}}
117
118 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!**
119
120 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.
121
122 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.
123
124 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:
125
126 {{code language="ini"}}
127 DB_USER=xwiki
128 DB_PASSWORD=<database_password>
129 MYSQL_ROOT_PASSWORD=<mysql_root_password>
130 DB_DATABASE=xwiki
131 XWIKI_VERSION=1.0
132 {{/code}}
133
134 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.
135
136
137 = First run of the container =
138
139 The first run is always the scariest. Start up the docker image and wait for everything to initialize:
140
141 {{code language="bash"}}
142 docker-compose up -d
143 {{/code}}
144
145 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.
146
147 Take your time and don't rush!
148
149 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/
150
151 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.
152
153 In the end, you should see an image like the one below:
154
155 [[image:Screenshot_20220607_015727.png]]
156
157 **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**
158
159 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!
160
161 = Nginx reverse proxy configuration =
162
163 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.
164
165 In "/etc/nginx/sites-available/", please create a "xwiki.conf" file with the following contents:
166
167 {{code language="nginx"}}
168 server {
169 server_name wiki.pentilescu.com;
170
171 listen [::]:443 ssl http2; # managed by Certbot
172 listen 443 ssl http2; # managed by Certbot
173
174 include /etc/nginx/snippets/ssl.conf;
175
176 location / {
177 proxy_pass http://localhost:8081;
178 }
179 }
180 {{/code}}
181
182 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.
183
184 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.
185
186 Once you've done this, create a symbolic link with the following command to activate your new configuration:
187
188 {{code language="bash"}}
189 sudo ln -s /etc/nginx/sites-available/xwiki.conf /etc/nginx/sites-enabled/xwiki.conf
190 {{/code}}
191
192 Finally, test your configuration before restarting Nginx with:
193
194 {{code language="bash"}}
195 sudo nginx -t
196 {{/code}}
197
198 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!
199
200 = Retrieving files for installing the Standard flavor packages and all its extensions =
201
202 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.
203 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.
204 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.
205 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.
206 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.
207 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!
208
209 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.
210
211
212 = Initial XWiki setup for administrative account and installing the Standard flavor =
213
214 At this point, you should see the following image in your browser again:
215 [[image:Screenshot_20220607_015727.png]]
216
217 It's finally time to setup the administration account! This account will have full privileges throghout the wiki and will be able to view and edit anything and everything. As such, please use a very strong password to protect it from password stuffing attacks!
218 If in doubt, always use a password manager like Bitwarden to generate strong, long passwords for you! These are guarenteed to have high entropy and are resistant to dictionary attacks.
219
220 Fill in all the details for your account, as detailed in the image below:
221 [[image:Screenshot_20220607_015843.png]]
222
223 Press the "Register and login" button to immediately login as the newly created user. Once this is done, we can proceed with the Standard flavor installation, as shown below:
224 [[image:Screenshot_20220607_020931.png]]
225
226 The "XWiki Standard Flavor" option should appear in the FLAVOR window by default if you downloaded the aforementioned XIP package and extracted its contents via the upload I already described in the proper directory. This flavor is ready to be installed now. Press the "Install this flavor" and let's get this show going!
227 You should come up to the following screen:
228 [[image:Screenshot_20220607_020959.png]]
229
230 Press "Install".
231
232 After some time, the following screen should appear:
233 [[image:Screenshot_20220607_021031.png]]
234
235 Press "Continue". Admittedly, this took several attempts on my end. I had to press "Continue" multiple times and a Time-out error appeared many times over, indicating that the process failed at some point.
236
237 Not sure what was wrong, or what was even timing out. All the packages were supposed to already be provided by the XIP package which I already unarchived, so all the files should have been locally accessible for the server. Was it downloading something else in the process? Don't know.
238 If you encounter a similar bug, please be persistent and keep on pressing "Continue" for another couple of times, like I did, around 3 or 4 times. If no progress is being made, press the "Later" button instead. If that button is disabled, press the "Select other flavor" at the top first and then press "Later", so that the installation of the Standard flavor is skipped. I did that and eventually it took me to the full Wiki page.
239 Proceed through the next installation steps and eventually finish the setup wizard entirely.
240 Once this is done, you should be directed to your XWiki's greeting page!
241 Congratulations, you've finished your first installation!
242
243
244 = Post-installation configurations that are a good idea =
245
246 You've setup an administrative account, you installed the Standard flavor package and now the Wiki is up and running. You're pretty much done, right?
247 Well, not quite...
248 There are still certain configurations which are a good idea that you should do. First and foremost, you should disable account registration, if possible, to ensure that rogue visitors don't get to pollute your database with bogus names. The user registration process is available to all visitors, by default, and this means that literally anyone can register an account on your Wiki. Which may be what you want or it might not be. For me, I prefer creating user accounts manually as the administrator so I opted to turn off the registration option. I suggest you do the same.
249
250 == Disable guest registration and configure unregistered users' rights ==
251
252 Log into your administrative account if you're not already logged in. Press the hamburger menu button at the top right of the grettings page and open the side menu. From there, select the "Administer Wiki" option.
253 On the new page, expand the "Users & Rights" left panel and then click on the "Rights" menu option. You should then be redirected to a "Global Administration: Rights" page. Here, you can micro-manage the rights of every single user and groups of users. Explaining user rights and the exact functions of each of these options is outside the scope of this wiki. For now, I'll only describe the disabling of the registration.
254 There's a horizontal combo box on the new page with the "Groups" and "Users" options, on the top of the page. Click on the "Users" option.
255 Here, you can micro-manage the rights of individual users. The "Register" checkbox is what we're after. We must deny registration rights to unregistered users.
256 It may seem that this right is already denied by default for all users, given that the Registration checkboxes will appear empty on your end. This is a quirk of the XWiki access rights UX. Despite these looking like checkboxes, they are not, in fact, traditional checkboxes.
257 In computer graphics design, one of the most fundamental lessons is that the element of a Checkbox is the graphical equivalent of a mathematical boolean variable (i.e. it must have only one of two states, at any point in time): a checkbox must either be checked or unchecked. The XWiki Rights panel has a different kind of checkbox, though, one that can take 1 of 3 states: empty, allowed and denied. In most cases, the default is the empty state.
258 Empty means that no particular configuration has been made with respect to that right for that user.
259 In our case, we wish to deny registration rights for unregistered users, so we have to set the "Registration" checkbox of the "Unregistered Users" row in that table to the "denied" state, like in the screenshot below:
260 [[image:Denied.png]]
261
262 I intentionally left the "View" and "Comment" rights specifically allowed for "Unregistered Users" as I believe that visitors should, intrinsically, have the ability to contribute to content as they see fit, without having to register for an account. You may wish to tweak these user rights as you see fit, though.
263 If you will allow unregistered users to comment, though, please consider checking the checkbox below for requiring them to solve a CAPTCHA for each comment, like I did. This will prevent technically savvy individuals from writing automated scripts or bots that will access your wiki and continously and automatically keep generating machine-generated text comments. While this will not prevent humans from posting spam on your Wiki, it should prevent bots from doing so.
264
265
266 == Configuring an SMTP server for your XWiki ==
267
268 Having a reachable SMTP server that your XWiki instance can use may come in handy, at some point.
269 The most obvious example of this is when you forget your XWiki user's password. When this happens, you will not be able to login anymore and, if this was the password for your administrator account, then, you're out of luck.
270 Having the option to reset your password via email will be really useful in this particular case. Of course, this implies that the email you set during your account setup is not outdated and still in your control.
271 To configure an SMTP server, go to the "Administer Wiki" section of the hamburger menu again, then expand the "Mail" section of the options on the left side and finally click on the "Mail Sending" menu option.
272 [[image:Mail.png]]
273 Of course, the exact configuration options you have to enter depend on your SMTP server's configuration. If you configured mandatory authentication on your SMTP server, you will have to enter login credentials here. I don't have to do that, personally.
274 The "EMAIL ADDRESS TO SEND FROM" can be any email address you wish to configure. Preferrably, it should be under the domain name of the machine where you're running your XWiki from (in my case, under "pentilescu.com").
275 The "EMAIL SERVER" option is a bit trickier. Assuming you're using postfix as your SMTP server, this should be an email configured in the "inet_interfaces" setting from the "/etc/postfix/main.cf" configuration file.
276 Also, if your postfix is not configured to accept email relays from outside its network, as mine does, you must remember to edit "/etc/postfix/main.cf" to add "192.168.80.3" to its "mynetworks" configuration, to, essentially, whitelist your docker container as a valid relay source, otherwise it will deny any email sending requests from it.
277 Please be sure to use the appropriate IP address as configured in your "docker-compose.yml" file for your xwiki service.
278 For more information about postfix and setting it up, please visit the "How to setup a postfix SMTP server" article in the external references section at the bottom of this article!
279
280 == Modifying cookie encryption keys==
281 XWiki has an interesting login mechanism. It doesn't use session tokens to keep track of your user account. What it does do is that it stores two session cookies in your browser: one for your username and one for your password.
282 Every time you make a request to your server, these two session cookies are sent along with each request, effecitvely authenticating it.
283 This might seem as a huge security problem, as the password is stored in the session cookie and it can be easily viewed by anyone with local access to the web browser's machine.
284 To mitigate this security risk, XWiki encrypts both the username cookie's value and the password cookie's value using keys configured in a configuration file. These keys come with strong default values, by itself but, since these values are the same for everyone that downloads the docker image, are inherently public.
285 As such, you, as the administrator, should change these encryption keys to your own, randomly generated ones. To do so, go to <your XWiki directory>/data/xwiki-data/data/ and modify the "xwiki.cfg" configuration file there. This file should have two configuration options called "xwiki.authentication.validationKey" and "xwiki.authentication.encryptionKey". Generate, from scratch, two different 32 character long encryption keys and replace the default ones with your ones. Uppercase and lowercase letters, as well as digits, are allowed. I don't believe other symbols are accepted though.
286 Change these and restart the docker container, for the changes to apply.
287
288 = External references =
289
290 [[Official docker guide for installing XWiki>>https://github.com/xwiki/xwiki-docker/blob/master/README.md]]
291 How to setup an Nginx reverse proxy and also provide a global X.509 certificate for it [NOT YET WRITTEN!]
292 How to setup a postfix SMTP server [NOT YET WRITTEN]