Last modified by Simon Urli on 2023/10/10

Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
5 You'll need to perform 4 mandatory steps:
6
7 {{toc depth="1"/}}
8
9 But first, you'll need to [[download>>xwiki:Main.Download]] the .war version of XWiki and check the [[System Requirements>>xwiki:Documentation.AdminGuide.Installation#HPrerequisites]].
10
11 = Install and configure a Servlet Container =
12
13 XWiki will work with any Servlet Container (provided it's properly configured obviously). We're only listing instructions for a few containers but you can adapt these instructions for your favorite container.
14
15 * [[Tomcat installation>>xwiki:Documentation.AdminGuide.InstallationTomcat]]
16 * [[Jetty installation>>xwiki:Documentation.AdminGuide.InstallationJetty]]
17 * [[GlassFish installation>>xwiki:Documentation.AdminGuide.InstallationGlassFish]]
18 * [[WebSphere installation>>xwiki:Documentation.AdminGuide.InstallationWebSphere]]
19 * [[JBoss Installation>>xwiki:Documentation.AdminGuide.InstallationJBoss]]
20 * [[Oracle OC4J Installation>>xwiki:Documentation.AdminGuide.InstallationOC4J]]
21 * [[Apache Geronimo>>xwiki:Documentation.AdminGuide.InstallationGeronimo]]
22
23 Some containers have the Java Security Manager turned on. In this case, XWiki needs to be granted some permissions. Below there's a sample policy file if you want to run your container with the Security Manager active. Depending on the version of XWiki that you use and on the plugins/extensions that you use the permissions might need to be adjusted to your needs:
24
25 {{code language="none"}}
26 grant codeBase "file:<full-path-here>/webapps/xwiki/WEB-INF/lib/-" {
27 permission java.util.PropertyPermission "file.encoding", "read";
28 // Needed by Hibernate -> antlr
29 permission java.util.PropertyPermission "ANTLR_DO_NOT_EXIT", "read";
30 permission java.util.PropertyPermission "ANTLR_USE_DIRECT_CLASS_LOADING", "read";
31 // Needed by Hibernate and others
32 permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
33 permission java.lang.RuntimePermission "createClassLoader";
34 permission java.lang.RuntimePermission "setContextClassLoader";
35 // Needed by commons-logging
36 permission java.util.PropertyPermission "org.apache.commons.logging.LogFactory.HashtableImpl", "read";
37 // Needed for connecting to the database
38 permission java.net.SocketPermission "127.0.0.1:3306", "connect,resolve";
39 // Needed by the scheduler plugin -> quartz, but works without (maybe except scheduling? should be checked)
40 // permission java.util.PropertyPermission "org.quartz.properties", "read";
41
42 //Allow file storage directory reading - for directory and everything underneath
43 //This is dependent on the setting of environment.permanentDirectory in xwiki.properties
44 permission java.io.FilePermission "${catalina.home}${file.separator}xwikidata${file.separator}", "read,write,delete";
45 permission java.io.FilePermission "${catalina.home}${file.separator}xwikidata${file.separator}-", "read,write,delete";
46 //Allow file storage directory reading - temporary directory and everything underneath
47 //This is dependent on the setting of environment.temporaryDirectory in xwiki.properties.
48 permission java.io.FilePermission "${catalina.home}${file.separator}temp${file.separator}", "read,write,delete";
49 permission java.io.FilePermission "${catalina.home}${file.separator}temp${file.separator}-", "read,write,delete";
50 };
51 {{/code}}
52
53 You're now ready to install and configure your relational database.
54
55 = Set a proper permanent directory =
56
57 Open ##WEB-INF/xwiki.properties## and make sure to [[set a proper permanent directory>>xwiki:Documentation.AdminGuide.Configuration#HConfiguringDirectories]].
58
59 = Install and configure a Relational Database =
60
61 XWiki can work with a lot of relational databases. We're only listing those that we have tested it on. However please note that the XWiki Developers [[only support some of those databases>>dev:Community.DatabaseSupportStrategy]] and the other ones are supported by the community (the XWiki devs apply patches/Pull Requests).
62
63 The general strategy is the following:
64
65 * Install your favorite RDBMS
66 * Create a ##xwiki## database
67 * Create a user with all privileges on that database
68 * Copy your RDBMS Java drivers to the XWiki webapp's ##WEB-INF/lib## directory
69 * Configure XWiki to use the created database. This involves modifying the ##WEB-INF/hibernate.cfg.xml## file as is described in the tutorials for each database below.
70 * XWiki will automatically create the various tables it needs when it executes on the first run
71 * [[Add the missing indexes manually>>Documentation.AdminGuide.Performances.Database Administration.WebHome]]
72
73 == Specific databases instructions ==
74
75 Install and configure the database you wish to use:
76
77 * [[HSQL Installation>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationHSQL]]
78 * [[MySQL Installation>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationMySQL]]
79 * [[MariaDB Installation>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationMariaDB]]
80 * [[PostgreSQL Installation>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationPostgreSQL]]
81 * [[Oracle Installation>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationOracle]]
82 * [[DB2 Installation>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationDB2]]
83 * [[Derby Installation>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationDerby]]
84 * [[Microsoft SQL Server Installation>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationMSSQL]]
85 * [[H2 Installation>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationH2]]
86
87 == Using a Data Source ==
88
89 A more scalable and J2EE-conformant tactic is to use the Servlet Container to manage your data source. You modify the web app as little as possible.
90
91 * Do not add your JDBC library to the web app. Install it to the container's classpath instead, like in ##$CATALINA_HOME/common/lib##.
92 * Do not set user, url, etc., nor ##connection.provider_class## in ##hibernate.cfg.xml##. The critical settings are ##connection.datasource## (with JNDI name like ##java:/comp/env/jdbc/XWikiDS##) and the dialect class for your DB vendor. Do not comment out ##<mapping resource="..."/>## elements, hibernate needs them. Note that you should leave the ##provider_class## unset, since XWiki's implementation doesn't handle container-managed data sources.
93 * Manage all database access settings using your container facilities, for example Tomcat admin webapp or ##server.xml## + ##APPNAME.xml##. Uncommenting the ##<resource-ref>## element inside ##WEB-INF/web.xml## that matches the above JNDI name and looks like ##<res-ref-name>jdbc/XWikiDS</res-ref-name>## could be a good idea.
94
95 = Install the XWiki UI =
96
97 {{include reference="Documentation.AdminGuide.Installation.InstallationConcludingSteps.WebHome"/}}

Get Connected