Changes for page How to setup an XWiki docker container

Summary

• Page properties (2 modified, 0 added, 0 removed)

Details

Page properties

Tags

...	...	@@ -1,0 +1,1 @@
	1	+technical guide

Content

...	...	@@ -14,4 +14,121 @@
14	14
15	15	= Configuring an appropriate docker-compose setup =
16	16
17		-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/xwiki
	17	+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.
	18	+
	19	+Afterwards, in this newly created directory, please create the following empty subdirectory: mariadb
	20	+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:
	21	+
	22	+{{code language="bash"}}
	23	+wget https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/14/mariadb-tomcat/mariadb/init.sql
	24	+wget https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/14/mariadb-tomcat/mariadb/xwiki.cnf
	25	+{{/code}}
	26	+
	27	+**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**
	28	+
	29	+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:
	30	+
	31	+{{code language="yaml"}}
	32	+# ---------------------------------------------------------------------------
	33	+# See the NOTICE file distributed with this work for additional
	34	+# information regarding copyright ownership.
	35	+#
	36	+# This is free software; you can redistribute it and/or modify it
	37	+# under the terms of the GNU Lesser General Public License as
	38	+# published by the Free Software Foundation; either version 2.1 of
	39	+# the License, or (at your option) any later version.
	40	+#
	41	+# This software is distributed in the hope that it will be useful,
	42	+# but WITHOUT ANY WARRANTY; without even the implied warranty of
	43	+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
	44	+# Lesser General Public License for more details.
	45	+#
	46	+# You should have received a copy of the GNU Lesser General Public
	47	+# License along with this software; if not, write to the Free
	48	+# Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
	49	+# 02110-1301 USA, or see the FSF site: http://www.fsf.org.
	50	+# ---------------------------------------------------------------------------
	51	+version: '2'
	52	+networks:
	53	+ bridge:
	54	+ driver: bridge
	55	+services:
	56	+ # The container that runs XWiki + Tomcat
	57	+ web:
	58	+ image: "xwiki:lts-mariadb-tomcat"
	59	+ container_name: xwiki-mariadb-tomcat-web
	60	+ depends_on:
	61	+ - db
	62	+ ports:
	63	+ - "8081:8080"
	64	+ # Default values defined in .env file.
	65	+ # The DB_USER/DB_PASSWORD/DB_DATABASE/DB_HOST variables are used in the hibernate.cfg.xml file.
	66	+ environment:
	67	+ - XWIKI_VERSION=${XWIKI_VERSION}
	68	+ - DB_USER=${DB_USER}
	69	+ - DB_PASSWORD=${DB_PASSWORD}
	70	+ - DB_DATABASE=${DB_DATABASE}
	71	+ - DB_HOST=xwiki-mariadb-db
	72	+ # Provide a name instead of an auto-generated id for xwiki data (the permanent directory in included in it)
	73	+ # configured in the Dockerfile, to make it simpler to identify in 'docker volume ls'.
	74	+ volumes:
	75	+ - ./data/xwiki-data:/usr/local/xwiki
	76	+ networks:
	77	+ internal_xwiki_network:
	78	+ ipv4_address: 192.168.80.3
	79	+ # The container that runs the database (mariadb)
	80	+ db:
	81	+ image: "mariadb:10.5"
	82	+ container_name: xwiki-mariadb-db
	83	+ # - We provide a xwiki.cnf file in order to configure the mysql db to support UTF8 and be case-insensitive
	84	+ # We have to do it here since we use an existing image and that's how this image allows customizations.
	85	+ # See https://hub.docker.com/_/mariadb/ for more details.
	86	+ # - Provide a name instead of an auto-generated id for the mariadb data, to make it simpler to identify in
	87	+ # 'docker volume ls'
	88	+ volumes:
	89	+ - ./mariadb/xwiki.cnf:/etc/mysql/conf.d/xwiki.cnf
	90	+ - ./data/mariadb-data:/var/lib/mysql
	91	+ - ./mariadb/init.sql:/docker-entrypoint-initdb.d/init.sql
	92	+
	93	+ # Configure the MariaDB database and create a user with provided name/password.
	94	+ # See https://hub.docker.com/_/mariadb/ for more details.
	95	+ # Default values defined in .env file.
	96	+ environment:
	97	+ - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
	98	+ - MYSQL_USER=${DB_USER}
	99	+ - MYSQL_PASSWORD=${DB_PASSWORD}
	100	+ - MYSQL_DATABASE=${DB_DATABASE}
	101	+ networks:
	102	+ internal_xwiki_network:
	103	+ ipv4_address: 192.168.80.4
	104	+
	105	+networks:
	106	+ internal_xwiki_network:
	107	+ driver: bridge
	108	+ ipam:
	109	+ driver: default
	110	+ config:
	111	+ - subnet: 192.168.80.0/24
	112	+{{/code}}
	113	+
	114	+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!**
	115	+
	116	+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.
	117	+
	118	+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.
	119	+
	120	+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:
	121	+
	122	+{{code language="ini"}}
	123	+DB_USER=xwiki
	124	+DB_PASSWORD=<database_password>
	125	+MYSQL_ROOT_PASSWORD=<mysql_root_password>
	126	+DB_DATABASE=xwiki
	127	+XWIKI_VERSION=1.0
	128	+{{/code}}
	129	+
	130	+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.
	131	+
	132	+= External references =
	133	+
	134	+[[Official docker guide for installing XWiki>>https://github.com/xwiki/xwiki-docker/blob/master/README.md]]