Wiki source code of Installation

Version 57.2 by Vincent Massol on 2011/03/02

version	line-number	content
48.1	1	{{box cssClass="floatinginfobox" title="Contents"}}
	2	{{toc/}}
	3	{{/box}}
28.1	4
31.5	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.
13.1	6
1.96	7	There are 2 solutions when installing XWiki:
36.1	8
28.1	9	* Use the [[Standalone distribution>>xwiki:Main.Download]] which already packages a Servlet Container (Jetty) and a database (HSQL). 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>>xwiki:Main.Download]] and configure both your container and your database to work with it.
31.5	11
28.1	12	If you're instead upgrading an existing XWiki install check the [[Upgrade instructions>>#HUpgradinganXWikiInstallation]] below.
31.5	13
14.3	14	Pick one of the trails in the outline on the right to get started.
31.5	15
28.1	16	Once you've finished the installation check the other topics in the [[Admin Guide>>AdminGuide.WebHome]] for configuring and [[securing>>Security]] your wiki.
31.5	17
48.1	18	{{info}}
52.4	19	If you want to make manual installation or need to migrate an existing XWiki installation, check the [[Release Notes>>xwiki:ReleaseNotes.WebHome]].
48.1	20	{{/info}}
1.112	21
31.5	22	= Tutorials =
1.95	23
14.3	24	Tutorials are step by step procedures to install XWiki for a specific configuration. You can choose to follow one of them or follow the instructions in the sections below.
36.1	25
48.1	26	{{warning}}
	27	Tutorials external to the xwiki.org site have not been validated for correctness by the XWiki dev team and it's also possible that they are out of date.
	28	{{/warning}}
14.3	29
28.1	30	* [[XWiki On Windows (French)>>http://agoncalves.developpez.com/tutoriels/xwiki/creer-un-site-associatif/]]
	31	* [[XWiki On Debian 4 (Etch) - Tomcat - PostgreSQL (or MySQL) (English)>>http://www.howtoforge.com/xwiki-tomcat-mysql-debian-etch]]
	32	* [[XWiki On Debian 4 (Etch) - Tomcat - PostgreSQL (or MySQL) (German)>>http://www.howtoforge.de/howto/xwiki-on-debian-4-etch-tomcat-mysql]]
54.1	33	* [[XWiki On Windows - GlassFish - Oracle (Russian)>>http://etvc.myxwiki.org/xwiki/bin/view/UNA/XWikiInstalation]]
57.2	34	* [[XWiki on OpenSUSE - Tomcat - MySQL (English)>>http://geistreicher-papierkorb.blogspot.com/2011/03/setting-up-xwiki-on-opensuse-with-mysql.html]]
14.3	35
31.5	36	= Prerequisites =
14.3	37
31.1	38	* Java 5 or greater installed.
53.1	39	* A minimum of 200MB of heap memory and 70MB of permGen. Recommended value are 512MB for the heap and 128MB for the permGen (##-Xmx512m -XX:MaxPermSize=128m##)
50.5	40	* (((
	41	{{include document="Features.WysiwygEditorPrerequisites"/}}
	42	)))
1.96	43
31.2	44	{{warning}}
	45	Note that attachments are currently very memory intensive and if you manipulate large attachments you'll need a lot more heap memory (roughly 30 times the size of your attachment). We're working on fixing this.
	46	{{/warning}}
31.1	47
31.5	48	= Installing the Standalone distribution =
1.96	49
1.104	50	This is by far the easiest way to install XWiki. We are offering 3 packaging for ease of installation:
28.1	51
31.6	52	* A Windows exe. Simply execute it and follow the instructions. Do not close the DOS Windows that shows up. This is the XWiki server running, instead point your browser to {{{http://www.localhost:8080/}}}.
1.124	53	* A generic Installer that works on all platforms. It requires Java to be installed on your system. Simply double-click on it and follow the instructions.
31.6	54	* A zip version. Unzip it in any ##XWIKIHOME## directory of your choice.
31.5	55
32.1	56	The Windows installer creates shortcuts to start and stop XWiki in your Windows start menu. Launch the Wiki using "start".
31.5	57
33.1	58	If you've used the zip file or generic Installer, go to the directory where you've installed XWiki (##XWIKIHOME##) and run ##start_xwiki.bat## in Windows or ##start_xwiki.sh## on Unix. To stop it, run the ##stop_xwiki.bat## script on Windows and ##stop_xwiki.sh## on Unix or Mac. On Mac you will need to use "Open with Terminal" or run this script from the Terminal.
31.5	59
32.1	60	Once XWiki is started point your browser to {{{http://localhost:8080/xwiki/bin/view/Main/WebHome}}} and the go to the [[User's Guide>>enterprise:UserGuide.WebHome]] to learn how to use XWiki.
	61
34.1	62	In some cases, you might already have a Web Server running on port 8080. If this happens you have to pass another the port to the start script (e.g. by using the port 8081, as in ##start_xwiki.sh 8081##).
32.1	63
48.1	64	{{info}}
	65	You can log in using the default ##Admin## user (first letter is capitalized). The default password is ##admin## (lowercase).
	66	{{/info}}
1.96	67
31.5	68	= Installing the XWiki WAR manually =
1.96	69
	70	You'll need to perform 2 mandatory steps:
36.1	71
1.96	72	* Install and configure a Servlet Container
	73	* Install and configure a relational database
31.5	74
48.1	75	{{info}}
52.4	76	If your database is empty this will result in a minimal empty wiki installation. You may want to use the [[Import/Export tool>>AdminGuide.ImportExport]] to import some pages in your wiki. We recommend that you import the [[provided default XAR>>xwiki:Main.Download]]. If you're upgrading from an existing installation your database should already contain the pages you had before. If you're using the new XWiki 1.0 skin you might want to install the [[Panels Application>>extensions:Extension.Panels Application]].
48.1	77	{{/info}}
31.5	78
48.1	79	{{info}}
50.5	80	If you are installing in a linux/unix environment you have to setup the //xwiki.upload.tempdir// parameter as explained in the JIRA entry ([[http://jira.xwiki.org/jira/browse/XWIKI-530]]) before importing anything into XWiki.
48.1	81	{{/info}}
1.96	82
31.5	83	== Install and configure a Servlet Container ==
1.96	84
35.1	85	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.
1.96	86
28.1	87	* [[Tomcat installation>>AdminGuide.InstallationTomcat]]
	88	* [[Jetty installation>>AdminGuide.InstallationJetty]]
	89	* [[GlassFish installation>>AdminGuide.InstallationGlassFish]]
	90	* [[WebSphere installation>>AdminGuide.InstallationWebSphere]]
	91	* [[JBoss Installation>>AdminGuide.InstallationJBoss]]
	92	* [[Oracle OC4J Installation>>AdminGuide.InstallationOC4J]]
50.2	93	* [[Apache Geronimo>>AdminGuide.InstallationGeronimo]]
31.5	94
35.4	95	Some containers have the Java Security Manager turned on. In this case, XWiki needs to be granted some permissions. Here's below a sample policy file if you want to run your container with the Security Manager active. Depending on the version of XWiki Enterprise that you use and on the plugins/extensions that you use the permissions might need to be adjusted to your needs:
35.1	96
35.3	97	{{code language="none"}}
35.1	98	grant codeBase "file:<full-path-here>/webapps/xwiki/WEB-INF/lib/-" {
	99	permission java.util.PropertyPermission "file.encoding", "read";
	100	// Needed by Hibernate -> antlr
	101	permission java.util.PropertyPermission "ANTLR_DO_NOT_EXIT", "read";
	102	permission java.util.PropertyPermission "ANTLR_USE_DIRECT_CLASS_LOADING", "read";
	103	// Needed by Hibernate and others
	104	permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
	105	permission java.lang.RuntimePermission "createClassLoader";
	106	permission java.lang.RuntimePermission "setContextClassLoader";
	107	// Needed by commons-logging
	108	permission java.util.PropertyPermission "org.apache.commons.logging.LogFactory.HashtableImpl", "read";
	109	// Needed for connecting to the database
	110	permission java.net.SocketPermission "127.0.0.1:3306", "connect,resolve";
	111	// Needed by the scheduler plugin -> quartz, but works without (maybe except scheduling? should be checked)
	112	// permission java.util.PropertyPermission "org.quartz.properties", "read";
	113	};
35.2	114	{{/code}}
35.1	115
1.96	116	You're now ready to install and configure your relational database.
	117
31.5	118	== Install and configure a Relational Database ==
1.96	119
	120	XWiki can work with a lot of relational databases. We're only listed those that we have tested it on.
31.5	121
1.96	122	The general strategy is the following:
	123
	124	* Install your favorite RDBMS
	125	* Create a xwiki database
	126	* Create a user with all privileges on that xwiki database
31.7	127	* Copy your RDBMS Java drivers to the XWiki webapp's ##WEB-INF/lib## directory
	128	* 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. Also make sure that your ##xwiki.cfg## file has an entry that points to your ##WEB-INF/hibernate.cfg.xml## file (##xwiki.store.hibernate.path=/WEB-INF/hibernate.cfg.xml##) as otherwise your settings won't be used.
18.1	129	* (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... hopefully one day Xwiki will allow you to override hibernate.cfg.xml without needing to change the app itself.
31.7	130	** Do not add your JDBC library to the web app. Install it to the container classpath instead, like to ##$CATALINA_HOME/common/lib##.
36.1	131	** 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. (You should leave the provider_class unset, since Xwiki's implementation doesn't handle container-managed data sources).
	132	** 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.
15.1	133
1.96	134	Install and configure the database you wish to use:
	135
28.1	136	* [[HSQL Installation>>AdminGuide.InstallationHSQL]]
	137	* [[MySQL Installation>>AdminGuide.InstallationMySQL]]
	138	* [[PostgreSQL Installation>>AdminGuide.InstallationPostgreSQL]]
	139	* [[Oracle Installation>>AdminGuide.InstallationOracle]]
	140	* [[DB2 Installation>>AdminGuide.InstallationDB2]]
	141	* [[Derby Installation>>AdminGuide.InstallationDerby]]
	142	* [[Microsoft SQL Server Installation>>AdminGuide.InstallationMSSQL]]
50.3	143	* [[H2 Installation>>AdminGuide.InstallationH2]]
1.96	144
56.1	145	{{warning}}XWiki does not create automatically the Database Indexes. You can use the [[Admin Tools Application>>extensions:Extension.AdminTools]] for that or [[create them manually>>AdminGuide.Database Administration]]{{/warning}}
55.1	146
	147
31.5	148	== Concluding Step ==
1.96	149
28.1	150	At this stage you have finished configuration XWiki. If you start your database and container and point your browser to http://localhost:8080/xwiki/ you'll have a working, albeit minimal, wiki (without any page loaded). The next step is either to create new pages by hand or import the default Wiki that we are providing as a [[XAR file>>xwiki:Main.Download]], by using the [[Import feature>>AdminGuide.ImportExport]].
1.96	151
31.5	152	= Installing the eXo Enterprise WebOS integration WAR =
1.96	153
48.1	154	{{warning}}
	155	The integration with eXo is still very experimental and the instructions below are not finalized yet. Proceed with caution!
	156	{{/warning}}
1.96	157
31.5	158	== Install eXo WebOS ==
1.96	159
1.124	160	* Download the latest version of eXo Portal on http://forge.objectweb.org/projects/exoplatform/ (version 2.0-Alpha-2 or greater is required).
1.96	161	* Follow the eXo installation instructions located inside the Portal ZIP and try to login in the portal.
	162
31.5	163	== Install XWiki inside eXo ==
1.96	164
	165	* Stop eXo Portal.
28.1	166	* Download the [[latest XWiki eXo WAR>>xwiki:Main.Download]]. You'll need version 1.0-beta-6 or above.
	167	* Create a directory //exo-tomcat/webapps/xwiki//.
	168	* Unzip the WAR in //exo-tomcat/webapps/xwiki// and rename the exploded directory to "xwiki".
	169	* Move the //ehcache.jar// from //xwiki/WEB-INF/lib// to //exo-tomcat/common/lib// (There are some conflicts with it that both XWiki/eXo will need to fix in future versions).
	170	* Remove all the eXo jars from //xwiki/WEB-INF/lib//
	171	* Configure XWiki's database as explained [[above>>#HInstallandconfigureaRelationalDatabase]].
	172	* Change in //xwiki.cfg//: xwiki.exo=1 to xwiki.exo=0. TODO: Explain why this is required as it is very counter-intuitive!
1.96	173	* Restart eXo Portal.
	174	* You can now either import XWiki as a Portlet inside the Portal as described below or access XWiki directly by using the usual URL.
28.1	175	* [[Change the skin to use the XWiki 1.0 skin>>AdminGuide.Skins#HChangingtheskin]]. This skin is compatible with the Portlet mode and specifically with eXo WebOS.
	176	* Import the [[default wiki XAR>>xwiki:Main.Download]] or use your own XWiki database.
1.96	177	* Give the admin right to XWikiGuest
	178	* To be continued...
	179
31.5	180	== Use XWiki inside the WebOS ==
1.96	181
	182	Inside the WebOS, XWiki is seen as a Portlet and therefore must be imported in eXo through the PortletRegistry application. To do so you need to login as exoadmin / exo in eXo and go to the Administration desktop and use the PortletRegistry application. Click on the "Import Portlet Category" icon, you should now see XWiki in the list. You can now add the Portlet in your desktop page though the "Add Application" icon in the desktop dock.
1.113	183
31.5	184	= Installing the Default Wiki XAR =
1.96	185
	186	The default wiki is a fully configured wiki that you can use as a starting point for creating your own wiki content. It provides the following:
28.1	187
1.96	188	* A Blog
48.1	189	* A Recent Changes page
52.4	190	* The [[Panels Application>>extensions:Extension.Panels Application]]
1.96	191	* Search
	192	* Administration page (Access rights, Group and users management, etc)
	193	* ... and much more
31.5	194
28.1	195	It comes configured with an "Admin" user (password is "admin" in lowercase). You'll need that username/password to log in once you've imported the default wiki.
31.5	196
28.1	197	To install the XAR, use the [[Import/Export tool>>AdminGuide.ImportExport]].
31.5	198
48.1	199	{{warning}}
	200	If you're upgrading an existing wiki be careful that the XAR import operation will replace the content of the existing pages of your wiki with the content of the XAR (New pages that you have created will not be modified). As a consequence it's critical that you [[perform a backup>>platform:AdminGuide.Backup]] first.
	201	{{/warning}}
1.96	202
31.5	203	= Upgrading an XWiki Installation =
1.96	204
1.126	205	There are different parts of XWiki that you may want to upgrade:
1.96	206
28.1	207	* [[XWiki Core>>#HUpgradingXWikiCore]]
	208	* [[Documents provided with the default XWiki XAR>>#HUpgradingwikidocuments]]
31.5	209
48.1	210	{{info}}
	211	If you're upgrading an XWiki 0.9 installation refer to [[this guide>>UpgradeXWiki09Installation]].
	212	{{/info}}
1.113	213
31.5	214	== Upgrading XWiki Core ==
9.7	215
52.3	216	The general strategy is to [[download the WAR distribution>>xwiki:Main.Download]] and to replace your current installed WAR. Make sure you don't copy on top since this could leave some old files around which would make XWiki fail (like if old JARs are lying around in ##WEB-INF/lib##). Before replacing your current WAR, make sure you back it up and more specifically that you copy the ##hibernate.cfg.xml##, ##xwiki.cfg## and ##xwiki.properties## files which you'll need to copy in your newly installed WAR since they container your XWiki configuration. Make sure you also copy any plugins you may have added or any template files you may have modified.
31.5	217
52.5	218	Some additional operations may be required for upgrading and you must check the [[release notes>>xwiki:ReleaseNotes.WebHome]] for all the versions from the version you're upgrading from up to the new version you're installing. It's also possible that new features are available and that your ##xwiki.cfg## file needs to be modified. If this is the case then it'll be specified in the release notes.
1.113	219
37.1	220	Note that the database schema is automatically upgraded when needed. All you need to do is to ensure your ##xwiki.cfg## file is correctly configured to perform the migration. Here's a relevant excerpt from the ##xwiki.cfg## file:
	221
	222	{{code language="none"}}
	223	#-# Whether migrations are enabled or not. Should be enabled when upgrading, but for a better startup time it is better to
	224	#-# disable them in production.
	225	xwiki.store.migration=1
	226
	227	#-# Whether to exit after migration. Useful when a server should handle migrations for a large database, without going
	228	#-# live afterwards.
	229	# xwiki.store.migration.exitAfterEnd=0
	230
	231	#-# Indicate the list of databases to migrate.
	232	#-# to upgrade all wikis database set xwiki.store.migration.databases=all
	233	#-# to upgrade just some wikis databases set xwiki.store.migration.databases=xwiki,wiki1,wiki2
	234	#-# Note: the main wiki is always migrated whatever the configuration.
	235	# xwiki.store.migration.databases=
	236	{{/code}}
	237
31.5	238	== Upgrading wiki documents ==
1.113	239
28.1	240	You may want to upgrade to a newer version of the Default Wiki XAR in order to benefit from the latest changes. As mentioned above in the [["Installing the Default Wiki XAR" section>>#HInstallingtheDefaultWikiXAR]] you should be very careful and when doing the import make sure you selectively decide what pages you wish to import. More specifically the following pages should be imported with great care:
1.113	241
1.96	242	* XWiki.XWikiPreferences: This page contains the configuration of your wiki (it overrides the configuration defined in xwiki.cfg). If you import a new version of this page you'll loose any customization you may have made such as the skin to use, the rights for your wiki, etc.
	243	* XWiki.WebPreferences, Main.WebPreferences, and all other spaces WebPreferences pages: Same as XWiki.XWikiPreferences but at the level of a space.
	244	* XWiki.XWikiAllGroup (list of registered users) and XWiki.AdminGroup (list of Admins): If you have existing users and import a new version of these pages, you'll find that your users do not belong to these groups anymore and thus may not be able to edit pages, log in, etc. You'll need to add them again to the right groups.
50.1	245	* XWiki.Admin: This page contains the Admin user with the default password. If you import it you'll create a security hole. Thus it's very important not to import this page.
1.96	246	* Any other page you have modified, such as Main.WebHome, a modified Panel, etc.
	247
31.5	248	=== Let's clean it up ===
1.133	249
52.2	250	* Expand the XWiki WAR that you installed in your servlet container (the one that contains the JDBC drivers to access your database) into a new folder, using ##jar xvf xwiki-1.1-enterprise.war##, or avoid this step if you performed an export/import data migration (you already expanded it)
	251	* Copy your old ##xwiki.cfg##, ##xwiki.properties## and ##hibernate.cfg.xml## file to the ##WEB-INF## folder. Take care that if some changes were already made (probably because of database configuration when you installed the JDBC drivers) could be lost, so take care to add these changes
28.1	252	* Rename the skins/albatross folder to albatross.original, and copy the skins/default folder from XWiki 0.9 to skin/albatross. (//WARNING: this is an optional step, in case you don't want to use the default skin for 1.1x and want to retain your current skin in the new version//)
1.125	253	* Install this new folder as the xwiki application in your servlet container (may be by copying the folder to the servlet filesystem space or by packing it in a WAR file and deploying it)
37.2	254
36.1	255	At this point all is set, you can experience our old wiki data over the new XWiki core !!!
1.126	256
31.5	257	= Troubleshooting =
1.125	258
31.5	259	== Verify your installation ==
1.128	260
55.1	261	You can verify some basic settings of your XWiki install (on Tomcat, MySQL) using the [[Admin Tools application>>extensions:Extension.AdminTools]].
1.130	262
36.1	263	== Field 'XWD_ARCHIVE' doesn't have a default value ==
1.131	264
31.7	265	If you get an error like the one below it probably means you had an old XWiki version installed (most likely a 0.9 version) which had a wrong schema. We're normally automatically fixing schemas at startup when you set the ##xwiki.store.hibernate.updateschema## configuration parameter in ##xwiki.cfg## (it's set to on by default). However it's currently not done for this error.
1.111	266
28.1	267	{{code language="none"}}
1.111	268	Wrapped Exception: Could not execute JDBC batch update
1.124	269	[...]
1.111	270	Wrapped Exception:
28.1	271	java.sql.BatchUpdateException: Field 'XWD_ARCHIVE' doesn't have a default value
	272	{{/code}}
1.111	273
	274	To fix this run the following SQL command on your database:
	275
48.1	276	{{code language="sql"}}
	277	alter table xwikidoc modify column XWD_ARCHIVE mediumtext null;
	278	{{/code}}
1.111	279
31.5	280	== Failure to log in ==
1.111	281
	282	Check that you don't have some old cookies and try deleting them.

Wiki source code of Installation

Quick Links

Navigation

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected