Wiki source code of Installing XWiki .war package manually
Last modified by Eleni Cojocariu on 2026/05/28 16:34
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 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 [[Prerequisites>>documentation.xs.admin.installation.prerequisites.WebHome]]. | ||
| 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>>documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.WebHome]] | ||
| 16 | * [[Jetty installation>>documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-jetty.WebHome]] | ||
| 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"/}} |
