Wiki source code of XWiki Snap Guide

Last modified by Vedant Pol on 2022/09/26 08:59
Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc /}}
3 {{/box}}
4
5
6 = Description =
7
8 === XWiki-jetty Snap ===
9
10 Based on the [[XWiki Demo package>>https://www.xwiki.org/xwiki/bin/view/Download/DownloadVersion/?projectVersion=13.10.8]] modified to be production ready. It includes all the Java connectors required for the supported databases. **This is the current XWiki Snap** (Other Snaps have been decommissioned).
11 //[[Source>>https://github.com/xwiki-contrib/packaging-snap/tree/main/xwiki-jetty]]//
12
13 === XWiki-base-Snap ===
14
15 This Snap is based on the [[XWiki War package>>https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Installation/InstallationWAR/]].It also includes [[Tomcat9>>https://tomcat.apache.org/]] and all the supported Java connectors. **The following Snap has been retired. **[[Source>>https://github.com/xwiki-contrib/packaging-snap/tree/main/xwiki-base-snap]]
16
17 === XWiki-mysql-snap ===
18
19 This Snap is also based on the [[XWiki War package>>https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Installation/InstallationWAR/]]. The Snap includes [[Tomcat9>>https://tomcat.apache.org/]], MySQL, and the MySQL java connector.**The following Snap has also been discontinued. **
20 //[[Source>>https://github.com/xwiki-contrib/packaging-snap/tree/main/xwiki-mysql-snap]]//
21
22 = Installation =
23
24  
25
26 You can download and install the snap from the [[Snapcraft Store>>https://snapcraft.io/xwiki]]
27 Generally for ubuntu users with preinstalled snapd can install it by using the following command:
28 {{code}}sudo snap install xwiki {{/code}}
29
30 = Getting Started =
31
32 === To Start XWiki ===
33
34 After installing the snap you can start XWiki with the command
35 {{code}} sudo xwiki.start {{/code}}
36 {{info}}Sudo previliges are essential{{/info}}
37
38 === To Stop XWiki ===
39
40 If an instance of XWiki is running, you can stop it with the command
41 {{code}}sudo xwiki.stop {{/code}}
42 {{info}}Sudo previliges are essential{{/info}}
43
44 === To upgrade XWiki ===
45
46 Just enter {{code}}sudo snap refresh xwiki {{/code}} ,it would automatically update your snap and copy your permanent directory and config files.
47
48 {{warning}}
49 All the config files and permanent directory data of the previous version is stored in **var/snap/xwiki/<previous_revision>**.(You can copy them manually if you desire)
50 {{/warning}}
51
52 = Configuration =
53
54 === Configure your database ===
55
56 XWiki snap comes preconfigured with [[HSQL>>https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Installation/InstallationWAR/InstallationHSQL/]] database . This database is not recomended for production enviorment.Refer to the following link for more information on HSQLDB([[link>>https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Installation/InstallationWAR/InstallationHSQL/]]).
57
58 Install and configure the database you wish to use:
59
60 {{warning}}
61 The permanent directory has been set to **var/snap/xwiki/<revision>/data/**
62 The WEB-INF folder can be found in **var/snap/xwiki/<revision>/webapps/xwiki/WEB-INF/**
63 All the configuration file changes are to be made in the following directory for it to take effect in the xwiki **var/snap/xwiki/<revision>/**
64 {{/warning}}
65
66 * [[HSQL Installation>>https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Installation/InstallationWAR/InstallationHSQL/]]
67 * [[MySQL Installation>>https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Installation/InstallationWAR/InstallationMySQL/]]
68 * [[MariaDB>>https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Installation/InstallationWAR/InstallationMariaDB/]]
69 * [[PostgreSQL>>https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Installation/InstallationWAR/InstallationPostgreSQL/]]
70 * [[Oracle>>https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Installation/InstallationWAR/InstallationOracle/]]
71 * [[DB2 Installation>>https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Installation/InstallationWAR/InstallationDB2/]]
72 * [[Derby Installation>>https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Installation/InstallationWAR/InstallationDerby/]]
73 * [[Microsoft SQL Server Installation>>https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Installation/InstallationWAR/InstallationMSSQL/]]
74 * [[H2 Installation>>https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Installation/InstallationWAR/InstallationH2/]]
75
76 {{info}}
77 All the jdbc drivers have been already installed in `/var/snap/xwiki/<revision>/webapps/xwiki/WEB-INF/lib/`
78 {{/info}}
79
80 = Building XWiki snap =
81
82 === Prerequisites to build ===
83
84 You'll need to perform 3 mandatory steps to build the snap :
85
86 * [[install snapd>>https://snapcraft.io/docs/installing-snapd]]
87 * [[installing snapcraft and multipass>>https://snapcraft.io/docs/snapcraft-overview]]
88 * building the XWiki snap
89
90 Run the following commands to install **snapcraft** and **multipass** after installing snapd :
91 {{code}}sudo snap install snapcraft --classic
92 sudo snap install multipass{{/code}}
93
94 === Building the snap ===
95
96 * clone the repository
97 * cd into xwiki-jetty
98 * run snapcraft
99
100 This will build the xwiki_13.10.8_amd64.snap
101 {{info}} cd into the directory of the snap you would like to build {{/info}}
102 {{info}} eg. cd into xwiki-base-snap folder to build xwiki-base-snap {{/info}}
103
104 === Installing the snap ===
105
106 Make sure you are in the directory where the snap is built
107 {{code}}sudo snap install xwiki_13.10.8_amd64.snap --dangerous{{/code}}
108
109 {{warning}}
110 xwiki-base-snap and xwiki-mysql-snap has been depriciated. xwiki-jetty snap is the official snap.
111 {{/warning}}
112
113 = Releasing new version of the snap (XWiki release manager) =
114
115 To release a new version of XWiki snap is fairly simple
116
117 * First you would replace the `Source:` in xwiki part [[here>>https://github.com/xwiki-contrib/packaging-snap/blob/600178af0354869eb280370242fda4b64332892c/xwiki-jetty/snapcraft.yaml#L23]] with the newer zip file link.
118
119 * Change the version name [[here>>https://github.com/xwiki-contrib/packaging-snap/blob/600178af0354869eb280370242fda4b64332892c/xwiki-jetty/snapcraft.yaml#L3]] .
120
121 * lastly you would change the version variable name in [[override-build of xwiki part>>https://github.com/xwiki-contrib/packaging-snap/blob/1a6eb26f7e56052fdc55b98ad6f5faa0439ae444/xwiki-jetty/edge/snapcraft.yaml#L28]] & [[override-prime in scripts part>>https://github.com/xwiki-contrib/packaging-snap/blob/1a6eb26f7e56052fdc55b98ad6f5faa0439ae444/xwiki-jetty/edge/snapcraft.yaml#L64]]
122
123 Thats all you need to do if there are no major changes in the XWiki-jetty package .
124 Now you can simply build the snap following the above guide.
125
126 If there some other configuration or package changes :
127
128 === To change the java version ===
129
130 * First change the stage package to the desired java version package [[here>>https://github.com/xwiki-contrib/packaging-snap/blob/600178af0354869eb280370242fda4b64332892c/xwiki-jetty/snapcraft.yaml#L45]].
131 * Then rename the java folder from 11 to your desired version [[here>>https://github.com/xwiki-contrib/packaging-snap/blob/600178af0354869eb280370242fda4b64332892c/xwiki-jetty/snapcraft.yaml#L33]]
132 * Change the cacerts and blacklisted.certs accordingly [[here>>https://github.com/xwiki-contrib/packaging-snap/blob/600178af0354869eb280370242fda4b64332892c/xwiki-jetty/snapcraft.yaml#L36]]
133 * Change the java home variable folder [[here>>https://github.com/xwiki-contrib/packaging-snap/blob/600178af0354869eb280370242fda4b64332892c/xwiki-jetty/snapcraft.yaml#L71]]
134
135 Now build the snap to see if everything works as desired .
136
137 === To add another java connector or replace already existing ===
138
139 * add or replace the java connector in the scripts folder of the repository .
140 * move the connector inside the lib/ folder .[[similar to this>>https://github.com/xwiki-contrib/packaging-snap/blob/600178af0354869eb280370242fda4b64332892c/xwiki-jetty/snapcraft.yaml#L57]]
141
142 Now build the snap to see if there are any errors.
143
144 = Setting up the xwiki-base-snap mysql database **(obsolete)** =
145
146 {{warning}}
147 The following snap functions are depriciated
148
149 {{/warning}}
150
151 * Make sure you have [[mysql>>https://dev.mysql.com/doc/refman/8.0/en/installing.html]] 5.7 or greater installed.
152 * Start the MySQL server. You can do that in several ways. For example use mysqld --console--
153 * Create the wiki database.
154 {{code}}mysql -u root -e "create database xwiki default character set utf8mb4 collate utf8mb4_bin"{{/code}}
155 * Create the xwiki user with password xwiki
156 {{code}}mysql -u root -e "CREATE USER 'xwiki'@'localhost' IDENTIFIED BY 'xwiki'";{{/code}}
157 * Give privileges to the xwiki user for accessing and creating databases (for the multi wiki support). Specifically, the xwiki users need permissions to be able to execute CREATE DATABASE, DROP SCHEMA, and then all CRUD operations on tables. Note that the command below should be tuned to be more restrictive as granting all permissions is not required:
158 {{code}}mysql -u root -e "grant all privileges on *.* to xwiki@localhost"{{/code}}
159 * The mysql JDBC Driver JAR and hibernate.cfg.xml have already been configured for mysql in the snap
160 * Restart the snap
161 {{code}}sudo snap restart xwiki.tomcat{{/code}}
162 * now you can launch xwiki: http://localhost:8080/xwiki/bin/view/Main/
163
164 === Setting up the xwiki-mysql-snap **(obsolete)** ===
165
166 This snap consist of three parts:
167
168 * xwiki-14.4.1
169 * tomcat-9.0.x
170 * mysql-8
171
172 The building would be similar to xwiki-base-snap except the installation part:
173
174 install the snap in devmode:
175 {{code}}
176 sudo snap install xwiki_14.4.1_amd64.snap --devmode{{/code}}
177
178 === Running the snap a system service **(obsolete)** ===
179
180
181
182 Running mysql as a system service requires root access, but the server itself should never run as root, so it drops privileges to a dedicated user. This user must own the server files and directories. Currently snapd blocks access to creating users and changing process user, so the only way to do this is to disable the restrictions by installing the snap with the devmode argument.
183
184 post installation steps:
185 {{code}} sudo snap connect xwiki:process-control :process-control
186 xwiki.startup
187 xwiki.client -uroot -p{{/code}}
188
189 This should start the mysql server . Then follow the steps mentioned in **Setting up the xwiki-base-snap mysql database** section and your mysql would be ready .
190 now you can launch xwiki: http://localhost:8080/xwiki/bin/view/Main/
191
192 === Files and directories **(obsolete)** ===
193
194 The first time you run mysql.startup, it will generate the following in $HOME/snap/xwiki/common (if run as root, /var/snap/xwiki/common is used instead):
195 - conf/my.cnf: Basic configuration file
196 - data/: Data directoriy
197 - files/: Default location for the secure-file-priv option
198 - log/: Location of error log
199 - run/: Location of sock and pid files

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected