Wiki source code of Installation
Version 104.1 by Thomas Mortagne on 2017/07/06
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | {{box cssClass="floatinginfobox" title="**Contents**"}} | ||
| 2 | {{toc/}} | ||
| 3 | {{/box}} | ||
| 4 | |||
| 5 | XWiki is a Java-based wiki and runs on a Servlet Container such as Tomcat, Jetty, JBoss, WebLogic, WebSphere, etc. It also uses a relational database to store its content. It can run on almost any database (HSQL, MySQL, etc) but XWiki and the database need to be setup correctly. | ||
| 6 | |||
| 7 | There are several ways of installing XWiki: | ||
| 8 | |||
| 9 | * Use the [[Standalone distribution>>AdminGuide.InstallationStandalone]] which already packages a Servlet Container (Jetty) and a database (HSQL), filled with default wiki pages. This is the recommended option for first time XWiki users and for users who wish to quickly try out XWiki. | ||
| 10 | * Use the [[WAR distribution>>AdminGuide.InstallationWAR]] and configure both your container and your database to work with it. | ||
| 11 | * Use the [[.deb package>>AdminGuide.InstallationViaAPT]] to install the last version of XWiki and the dependencies. | ||
| 12 | * [[Use a non-official installation method>>#HOtherInstallationMethods]]. | ||
| 13 | |||
| 14 | If you're upgrading an existing XWiki install check the [[Upgrade instructions page>>AdminGuide.Upgrade]]. | ||
| 15 | |||
| 16 | Pick one of the trails in the outline on the right to get started. | ||
| 17 | |||
| 18 | Once you've finished the installation check the other topics in the [[Admin Guide>>AdminGuide.WebHome]] for configuring and [[securing>>Security]] your wiki. | ||
| 19 | |||
| 20 | {{info}} | ||
| 21 | If you want to make a manual installation or need to migrate an existing XWiki installation, check the [[Release Notes>>xwiki:ReleaseNotes.WebHome]]. | ||
| 22 | {{/info}} | ||
| 23 | |||
| 24 | {{id name="Prerequisites"/}} | ||
| 25 | |||
| 26 | = Hardware and Software requirements = | ||
| 27 | |||
| 28 | * Java 1.8.0_101 or greater installed for XWiki >= 8.1 (Java 7 or greater for XWiki < 8.1, Java 6 or greater for XWiki versions < 6.0) | ||
| 29 | * A Servlet Container supporting Servlet 3.0.1 (Servlet 2.4 for XWiki versions < 7.0) | ||
| 30 | * A JDBC 4 Driver for your database (JDBC 3 was required for XWiki versions < 7.0) | ||
| 31 | * Enough memory, check the [[Memory section>>AdminGuide.Performances#HMemory]] of the [[Performance Guide>>AdminGuide.Performances]]. | ||
| 32 | * Check the [[release notes>>xwiki:ReleaseNotes.WebHome]] for the version you're installing to see what browsers and databases are supported for it. You can also check our [[general support strategy>>dev:Community.SupportStrategy]]. | ||
| 33 | |||
| 34 | = Installation Methods = | ||
| 35 | |||
| 36 | * [[Using a standalone distribution >>AdminGuide.InstallationStandalone]]: Provides a built-in XWiki, with a portable database and a lightweight Java container. This standalone distribution is not recommended in a production environment. If you need to use it in a production basis, you may look at the other options. | ||
| 37 | * [[Using .war package (usable for production)>>AdminGuide.InstallationWAR]]: Provides a Java application package that has to be installed in a Java container (such as Tomcat). This can be used on almost any operating system. | ||
| 38 | * [[Using .deb package (usable for production)>>AdminGuide.InstallationViaAPT]]: Provides a .deb package that can be used on a Debian-based operating system. It can be installed with ##dpkg## or ##apt##; installation is thus automated. | ||
| 39 | * [[Using an official XWiki Docker image>>https://hub.docker.com/_/xwiki/]]: Provides an easy solution to test XWiki, with a configuration very close to a production setup. | ||
| 40 | |||
| 41 | = Other Installation Methods = | ||
| 42 | |||
| 43 | This section is about other, non-official ways of installing XWiki that have been contributed by the community. | ||
| 44 | |||
| 45 | {{warning}} | ||
| 46 | Tutorials external to the xwiki.org site have not been validated for correctness by the XWiki Development Team and it's also possible that they are out of date or even not working. | ||
| 47 | {{/warning}} | ||
| 48 | |||
| 49 | * [[Ansible playbook for installing XWiki Enterprise>>https://github.com/rastandy/xwiki-ansible-playbook]] | ||
| 50 | * [[Using yaourt on Arch Linux>>https://github.com/xwiki-contrib/packaging-archlinux]] | ||
| 51 | * [[XWiki On OpenShift (Platform-as-a-Service)>>https://github.com/rkmallik/xwiki-example]] | ||
| 52 | * [[XWiki On Windows>>http://agoncalves.developpez.com/tutoriels/xwiki/creer-un-site-associatif/]] (French) | ||
| 53 | * [[XWiki On Debian 4 (Etch) - Tomcat - PostgreSQL (or MySQL)>>http://www.howtoforge.com/xwiki-tomcat-mysql-debian-etch]] (English) | ||
| 54 | * [[XWiki On Debian 4 (Etch) - Tomcat - PostgreSQL (or MySQL)>>http://www.howtoforge.de/howto/xwiki-on-debian-4-etch-tomcat-mysql]] (German) | ||
| 55 | * [[XWiki On Windows - GlassFish - Oracle>>http://etvc.myxwiki.org/xwiki/bin/view/UNA/XWikiInstalation]] (Russian) | ||
| 56 | * [[XWiki on OpenSUSE - Tomcat - MySQL)>>http://geistreicher-papierkorb.blogspot.com/2011/03/setting-up-xwiki-on-opensuse-with-mysql.html]] (English) | ||
| 57 | * [[XWiki On Archlinux - Tomcat - hsql or MySQL>>https://github.com/xwiki-contrib/packaging-archlinux]] (English) | ||
| 58 | * [[Install XWiki on an Ubuntu 16.04 VPS>>https://www.rosehosting.com/blog/install-xwiki-on-an-ubuntu-16-04-vps/]] (English) | ||
| 59 | * [[Install XWiki using Docker compose>>https://zwindler.fr/wordpress/2016/09/15/installer-xwiki-8-2-1-avec-docker-compose-en-2-lignes-de-commandes]] (French) | ||
| 60 | * [[Install XWiki on a CentOS 7 VPS>>https://thishosting.rocks/how-to-build-your-own-wiki-with-xwiki-on-centos/]] (English) | ||
| 61 | |||
| 62 | = Troubleshooting = | ||
| 63 | |||
| 64 | You can verify some basic settings of your XWiki installation (on Tomcat, MySQL) using the [[Admin Tools application>>extensions:Extension.Admin Tools Application]]. Keep in mind that some of these tools only work in a Linux environment. | ||
| 65 | |||
| 66 | == Running multiple instances of XWiki in the same container == | ||
| 67 | |||
| 68 | If you get this error: | ||
| 69 | |||
| 70 | {{code}} | ||
| 71 | com.xpn.xwiki.XWikiException: Error number 3 in 0: Could not initialize main XWiki context | ||
| 72 | Wrapped Exception: Failed to get cache factory component | ||
| 73 | ... | ||
| 74 | Caused by: | ||
| 75 | org.infinispan.jmx.JmxDomainConflictException: Domain already registered org.xwiki.infinispan | ||
| 76 | {{/code}} | ||
| 77 | |||
| 78 | You need to edit ##WEB-INF/cache/infinispan/config.xml## for each instance of XWiki, and change the ##jmxDomain## value (found under the ##globalJmxStatistics## tag) to have a unique name. | ||
| 79 | |||
| 80 | == Running XWiki behind proxy-server == | ||
| 81 | |||
| 82 | Extension manager relies on remote repositories for searching and fetching available extensions, so if your XWiki is installed in a network accessing the internet through proxy-server, most likely extensions search will return you nothing and log files will contain ##connection refused## exceptions. | ||
| 83 | |||
| 84 | In such cases you should configure XWiki to know your proxy-server. | ||
| 85 | |||
| 86 | XWiki uses default Java proxy configuration through Apache httpclient. See the [[Java Networking and Proxies documentation>>http://docs.oracle.com/javase/6/docs/technotes/guides/net/proxies.html]] for more details. | ||
| 87 | The main idea is to add a set of proxy-related properties to system scope. | ||
| 88 | |||
| 89 | E.g. for Tomcat 6 it could be done in the following way: modify ##/<tomcat-home>/bin/catalina.sh## and added proxies to the ##JAVA_OPTS## variable definition: | ||
| 90 | |||
| 91 | {{code}} | ||
| 92 | JAVA_OPTS="$JAVA_OPTS -Dappserver.home=$CATALINA_HOME -Dappserver.base=$CATALINA_HOME **-Dhttp.proxyHost=proxy.mycompany.com -Dhttp.proxyPort=7777 -Dhttps.proxyHost=proxy.mycompany.com -Dhttps.proxyPort=7777** -Xmx512m -XX:MaxPermSize=196m $XWIKI_OPTS" | ||
| 93 | {{/code}} | ||
| 94 | |||
| 95 | == Unsupported major.minor version 51.0 == | ||
| 96 | |||
| 97 | This is because starting with version 6.0, XWiki requires Java 7 and you're using Java 6. You need to upgrade your Java version. | ||
| 98 | |||
| 99 | == Installing without internet connection == | ||
| 100 | |||
| 101 | === XIP package === | ||
| 102 | |||
| 103 | {{info}}Since 9.5{{/info}} a XIP package is provided for the Standard flavor. | ||
| 104 | |||
| 105 | This is actually a zip file containing the required XWiki extensions in the same format than the local extensions repository. | ||
| 106 | |||
| 107 | * download it on [[xwiki:Main.Download]] | ||
| 108 | * unzip it (rename it to ##.zip## if your zip tool does not recognize it) in the folder ##<permanentdirectory>/extension/repository## (if you have complain about already existing file don't overwrite) | ||
| 109 | * restart XWiki if it was running | ||
| 110 | |||
| 111 | === Other methods === | ||
| 112 | |||
| 113 | Several options: | ||
| 114 | |||
| 115 | * Set up a local Extension Repository, either as a Maven Repository or using the [[Extension Repository Application>>extensions:Extension.Repository Application]]. Of course you'll need to [[prefill it with all the extensions you'll wish to install when offline>>platform:AdminGuide.FillLocalMavenRepository]], which isn't something easy to do. | ||
| 116 | * [[Install the Standalone Distribution>>platform:AdminGuide.InstallationStandalone]] which contains a default set of wiki pages. | ||
| 117 | * Do not use the Distribution Wizard and [[import default wiki pages using the XAR Import feature>>AdminGuide.InstallationConcludingSteps]]. | ||
| 118 | * Use the [[Offline Packager Maven plugin>>https://github.com/xwiki-contrib/maven-plugin-offline-xwiki-repository-packager]]. | ||
| 119 | |||
| 120 | == Getting an error about SSL certificate == | ||
| 121 | |||
| 122 | If you get an error in the log telling you that it fail to access some some https website it usually means you have a too old version of Java 8 (older that update 101) and you should upgrade it (does not need to be upgraded to next major version of Java, just make sure you have at least Java 8 update 101). | ||
| 123 | |||
| 124 | {{code language="none"}} | ||
| 125 | 2017-03-14 20:40:17,494 [http://dwswiki10:8080/xwiki/bin/admin/XWiki/XWikiPreferences?editor=globaladmin§ion=XWiki.AddExtensions] ERROR aultExtensionRepositoryManager - Failed to search on repository [store.xwiki.com:xwiki:https://store.xwiki.com/xwiki/rest] with query [org.xwiki.extension.repository.search.ExtensionQuery@78b5e254]. Ignore and go to next repository. | ||
| 126 | org.xwiki.extension.repository.search.SearchException: Failed to search extensions based on pattern [] | ||
| 127 | at org.xwiki.extension.repository.xwiki.internal.XWikiExtensionRepository.search(XWikiExtensionRepository.java:434) | ||
| 128 | ... | ||
| 129 | Caused by: java.io.IOException: Failed to request [https://store.xwiki.com/xwiki/rest/repository/search?start=0&number=20&q=] | ||
| 130 | at org.xwiki.extension.repository.xwiki.internal.XWikiExtensionRepository.getRESTResource(XWikiExtensionRepository.java:246) | ||
| 131 | ... | ||
| 132 | Caused by: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target | ||
| 133 | at sun.security.ssl.Alerts.getSSLException(Alerts.java:192) | ||
| 134 | ... | ||
| 135 | Caused by: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target | ||
| 136 | at sun.security.validator.PKIXValidator.doBuild(PKIXValidator.java:387) | ||
| 137 | ... | ||
| 138 | Caused by: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target | ||
| 139 | at sun.security.provider.certpath.SunCertPathBuilder.build(SunCertPathBuilder.java:145) | ||
| 140 | ... | ||
| 141 | {{/code}} | ||
| 142 | |||
| 143 | == "File path too long" on Windows when unzipping == | ||
| 144 | |||
| 145 | The Windows Operating System imposes a [[file path limit to around 260 characters>>https://msdn.microsoft.com/en-us/library/aa365247(VS.85).aspx#maxpath]]. XWiki's zip file can, in some cases, reach paths as long a 182 characters, or even longer. To avoid such errors you could do one of the following: | ||
| 146 | |||
| 147 | * Install in a folder that is as close to the root of the drive as possible and uses a small name, e.g. ##C:\xwiki## | ||
| 148 | * Install XWiki using the [[cygwin>>https://www.cygwin.com/]] environment that overcomes this limitation | ||
| 149 | * Starting with Windows 10, you can set or create the ##EnableLongPaths## with a value of ##1## in the in the ##HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem## Windows Registry in order to activate support for long paths. More details and step-by-step instructions are available in various online tutorials such as [[this one>>https://www.howtogeek.com/266621/how-to-make-windows-10-accept-file-paths-over-260-characters/]]. |
