Installing XWiki .war package manually
You'll need to perform 4 mandatory steps:
- Install and configure a Servlet Container
- Set a proper permanent directory
- Install and configure a Relational Database
- Install the XWiki UI
But first, you'll need to download the .war version of XWiki and check the System Requirements.
Install and configure a Servlet Container
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.
- Tomcat installation
- Jetty installation
- GlassFish installation
- WebSphere installation
- JBoss Installation
- Oracle OC4J Installation
- Apache Geronimo
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:
permission java.util.PropertyPermission "file.encoding", "read";
// Needed by Hibernate -> antlr
permission java.util.PropertyPermission "ANTLR_DO_NOT_EXIT", "read";
permission java.util.PropertyPermission "ANTLR_USE_DIRECT_CLASS_LOADING", "read";
// Needed by Hibernate and others
permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
permission java.lang.RuntimePermission "createClassLoader";
permission java.lang.RuntimePermission "setContextClassLoader";
// Needed by commons-logging
permission java.util.PropertyPermission "org.apache.commons.logging.LogFactory.HashtableImpl", "read";
// Needed for connecting to the database
permission java.net.SocketPermission "127.0.0.1:3306", "connect,resolve";
// Needed by the scheduler plugin -> quartz, but works without (maybe except scheduling? should be checked)
// permission java.util.PropertyPermission "org.quartz.properties", "read";
//Allow file storage directory reading - for directory and everything underneath
//This is dependent on the setting of environment.permanentDirectory in xwiki.properties
permission java.io.FilePermission "${catalina.home}${file.separator}xwikidata${file.separator}", "read,write,delete";
permission java.io.FilePermission "${catalina.home}${file.separator}xwikidata${file.separator}-", "read,write,delete";
//Allow file storage directory reading - temporary directory and everything underneath
//This is dependent on the setting of environment.temporaryDirectory in xwiki.properties.
permission java.io.FilePermission "${catalina.home}${file.separator}temp${file.separator}", "read,write,delete";
permission java.io.FilePermission "${catalina.home}${file.separator}temp${file.separator}-", "read,write,delete";
};
You're now ready to install and configure your relational database.
Set a proper permanent directory
Open WEB-INF/xwiki.properties and make sure to set a proper permanent directory.
Install and configure a Relational Database
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 and the other ones are supported by the community (the XWiki devs apply patches/Pull Requests).
The general strategy is the following:
- Install your favorite RDBMS
- Create a xwiki database
- Create a user with all privileges on that database
- Copy your RDBMS Java drivers to the XWiki webapp's WEB-INF/lib directory
- 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.
- XWiki will automatically create the various tables it needs when it executes on the first run
- Add the missing indexes manually
Specific databases instructions
Install and configure the database you wish to use:
- HSQL Installation
- MySQL Installation
- MariaDB Installation
- PostgreSQL Installation
- Oracle Installation
- DB2 Installation
- Derby Installation
- Microsoft SQL Server Installation
- H2 Installation
Using a Data Source
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.
- Do not add your JDBC library to the web app. Install it to the container's classpath instead, like in $CATALINA_HOME/common/lib.
- 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.
- 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.
Install the XWiki UI
At this point your wiki is empty, i.e it doesn't contain any wiki page. Since applications in XWiki are done in wiki pages so you also don't need any application available (e.g. Blog, User Directory, User Profiles, etc). In addition, your wiki doesn't contain any user.
Thus the final step is to fill your Wiki with some initial content (i.e. wiki pages).
This is the job of the Distribution Wizard which automatically starts when you are browsing your new XWiki instance for the first time.
The default distribution is a fully configured wiki that you can use as a starting point for creating your own wiki content. It provides the following:
- A Dashboard
- A Panels Application
- Search
- Administration features (Access rights, Group and users management, etc)
- ... and much more
Installing without internet connection
XIP Package
A XIP package is available. It contains an offline extension repository with all the extensions making the Standard Flavor.
This is actually a zip file containing the required XWiki extensions for both the main wiki and subwikis, in the same format as the one of the local extensions repository. It allows the Distribution Wizard to find the extensions locally instead of getting them online and is thus suited for offline installations of XWiki.
- download it (use the exact same version of the XIP package as the version of XWiki you have)
- Unzip it (rename it to .zip if your zip tool does not recognize it) in the folder <permanentdirectory>/extension/repository (if you get complains about already existing files don't overwrite them)
- Make sure the user running XWiki has the permissions to write to these unzipped files
- Restart XWiki if it was running
- Resume standard installation, this time it will find the flavor locally
Other methods
Several options:
- Set up a local Extension Repository, either as a Maven Repository or using the Extension Repository Application. Of course you'll need to prefill it with all the extensions you'll wish to install when offline, which isn't something easy to do.
- Install the Standalone Distribution which contains a default set of wiki pages.
- Use the Offline Packager Maven plugin.
Extension Repositories
XWiki performs some checks at startup and even at runtime and tries to connects to remote Extension repositories. This will not cause any problem if you're offline but you'll get some error logs. You may want to disable Extension repositories by editing your xwiki.properties config file and adding the following empty property (make sure that this is the only property defined with the name):
