Wiki source code of Installation

Version 3.1 by Tianlan on 2007/11/26

version	line-number	content
1.96	1	1 Installation
1.95	2
1.124	3	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.
1.95	4
1.96	5	There are 2 solutions when installing XWiki:
1.95	6
1.100	7	* Use the [Standalone distribution>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.
1.96	8	* Use the [WAR distribution>Main.Download] and configure both your container and your database to work with it.
1.95	9
1.113	10	If you're instead upgrading an existing XWiki install check the [Upgrade instructions>#HUpgradinganXWikiInstallation] below.
	11
1.112	12	#info("There's a [nice tutorial>http://agoncalves.developpez.com/tutoriels/xwiki/creer-un-site-associatif/] (in French) contributed by an XWiki user for getting started with XWiki with step by step instructions for installing it.")
	13
1.96	14	Pick one of the following trails:
	15	#toc("" "" "")
1.95	16
1.96	17	Once you've finished the installation check the other topics in the [Admin Guide>AdminGuide.WebHome] for configuring and [securing>Security] your wiki.
1.95	18
1.96	19	#info("If you want to make manual installation or need to migrate an existing XWiki installation, check the [Release Notes>Main.ReleaseNotes].")
1.95	20
1.96	21	1.1 Prerequisites
1.95	22
1.96	23	You'll need to have Java 5 installed.
	24
	25	1.1 Installing the Standalone distribution
	26
1.104	27	This is by far the easiest way to install XWiki. We are offering 3 packaging for ease of installation:
	28	* A Windows exe. Simply execute it and follow the instructions
1.124	29	* 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.
	30	* A zip version. Unzip it in any <tt>\[XWIKIHOME\]</tt> directory of your choice.
1.96	31
1.124	32	The Windows installer creates shortcuts to start and stop XWiki. 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.
1.96	33
	34	Once XWiki is started point your browser to http://localhost:8080/xwiki/bin/view/Main/WebHome and the go to the [User's Guide>UserGuide.WebHome] to learn how to use XWiki. To change the port, edit the start script and replace 8080 by the number you want.
	35
	36	#info("You can log in using the default Admin user (first letter is capitalized). The default password is 'admin' (lowercase).")
	37	1.1 Installing the XWiki WAR manually
	38
	39	You'll need to perform 2 mandatory steps:
	40
	41	* Install and configure a Servlet Container
	42	* Install and configure a relational database
	43
	44	#info("If your database is empty this will results 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>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>Code.PanelsApplication].")
	45
1.124	46	#info("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.")
1.96	47
	48	1.1.1 Install and configure a Servlet Container
	49
	50	XWiki will work with any Servlet Container. We're only listing instructions for a few containers but you can adapt these instructions for your favorite container.
	51
	52	* [Tomcat installation>AdminGuide.InstallationTomcat]
	53	* [Jetty installation>AdminGuide.InstallationJetty]
	54	* [GlassFish installation>AdminGuide.InstallationGlassFish]
	55	* [WebSphere installation>AdminGuide.InstallationWebSphere]
	56	* [JBoss Installation>AdminGuide.InstallationJBoss]
1.103	57	* [Oracle OC4J Installation>AdminGuide.InstallationOC4J]
1.96	58
	59	You're now ready to install and configure your relational database.
	60
	61	1.1.1 Install and configure a Relational Database
	62
	63	XWiki can work with a lot of relational databases. We're only listed those that we have tested it on.
	64
	65	The general strategy is the following:
	66
	67	* Install your favorite RDBMS
	68	* Create a xwiki database
	69	* Create a user with all privileges on that xwiki database
1.124	70	* Copy your RDBMS Java drivers to the XWiki webapp's <tt>WEB-INF/lib</tt> directory
	71	* Configure XWiki to use the created database. This involves modifying the <tt>WEB-INF/hibernate.cfg.xml</tt> file as is described in the tutorials for each database below. Also make sure that your <tt>xwiki.cfg</tt> file has an entry that points to your <tt>WEB-INF/hibernate.cfg.xml</tt> file (<tt>xwiki.store.hibernate.path=/WEB-INF/hibernate.cfg.xml</tt>) as otherwise your settings won't be used.
1.96	72
	73	Install and configure the database you wish to use:
	74
	75	* [HSQL Installation>AdminGuide.InstallationHSQL]
	76	* [MySQL Installation>AdminGuide.InstallationMySQL]
	77	* [PostgreSQL Installation>AdminGuide.InstallationPostgreSQL]
	78	* [Oracle Installation>AdminGuide.InstallationOracle]
	79	* [DB2 Installation>AdminGuide.InstallationDB2]
	80	* [Derby Installation>AdminGuide.InstallationDerby]
1.143	81	* [Microsoft SQL Server Installation>AdminGuide.InstallationMSSQL]
1.96	82
	83	1.1.1 Concluding Step
	84
	85	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>Main.Download], by using the [Import feature>AdminGuide.ImportExport].
	86
	87	1.1 Installing the eXo Enterprise WebOS integration WAR
	88
	89	#warning("The integration with eXo is still very experimental and the instructions below are not finalized yet. Proceed with caution!")
	90
	91	1.1.1 Install eXo WebOS
	92
1.124	93	* 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	94	* Follow the eXo installation instructions located inside the Portal ZIP and try to login in the portal.
	95
	96	1.1.1 Install XWiki inside eXo
	97
	98	* Stop eXo Portal.
1.124	99	* Download the [latest XWiki eXo WAR>Main.Download]. You'll need version 1.0-beta-6 or above.
	100	* Create a directory ~~exo-tomcat/webapps/xwiki~~.
	101	* Unzip the WAR in ~~exo-tomcat/webapps/xwiki~~ and rename the exploded directory to "xwiki".
	102	* 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).
	103	* Remove all the eXo jars from ~~xwiki/WEB-INF/lib~~
1.96	104	* Configure XWiki's database as explained [above>#HInstallandconfigureaRelationalDatabase].
1.124	105	* 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	106	* Restart eXo Portal.
	107	* You can now either import XWiki as a Portlet inside the Portal as described below or access XWiki directly by using the usual URL.
	108	* [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.
	109	* Import the [default wiki XAR>Main.Download] or use your own XWiki database.
	110	* Give the admin right to XWikiGuest
	111	* To be continued...
	112
	113	1.1.1 Use XWiki inside the WebOS
	114
	115	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	116
1.96	117	1.1 Installing the Default Wiki XAR
	118
	119	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:
	120	* A Blog
	121	* Photo albums
	122	* A What's New page
	123	* The [Panels Application>Code.PanelsApplication]
	124	* Search
	125	* Administration page (Access rights, Group and users management, etc)
	126	* ... and much more
	127
	128	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.
	129
	130	To install the XAR, use the [Import/Export tool>AdminGuide.ImportExport].
	131
	132	#warning("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 first, either by exporting your wiki or by backuping the database.")
1.126	133	1.1 Upgrading an XWiki Installation
1.96	134
1.126	135	There are different parts of XWiki that you may want to upgrade:
1.96	136
1.113	137	* [XWiki Core>#HUpgradingXWikiCore]
	138	* [Documents provided with the default XWiki XAR>#HUpgradingwikidocuments]
	139
	140	1.1.1 Upgrading XWiki Core
	141
1.126	142	The general strategy is to [download the WAR distribution>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 and xwiki.cfg 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.
1.113	143
	144	Some additional operations may be required for upgrading and you must check the [release notes>Main.ReleaseNotes] for all the versions from the version you're upgrading from up to the new version you're installing.
	145
	146	1.1.1 Upgrading wiki documents
	147
	148	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.126	149
1.96	150	* 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.
	151	* XWiki.WebPreferences, Main.WebPreferences, and all other spaces WebPreferences pages: Same as XWiki.XWikiPreferences but at the level of a space.
	152	* 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.
	153	* Any other page you have modified, such as Main.WebHome, a modified Panel, etc.
	154
1.125	155	1.1.1 Upgrading an XWiki v0.9 Installation
	156
1.131	157	The idea behind this is to install the new version in a clean environment, copy the database to the new environment, copy your skin and make some minor adjustments. Let's rock and roll !!
1.126	158
1.133	159	1.1.1.1 Base components install
	160
1.125	161	* Download the [latest XWiki WAR version>http://www.xwiki.org/xwiki/bin/view/Main/Download#HXWikiEnterprise] (the enterprise one)
	162	* Follow the instructions in [installing the XWiki WAR manually>http://www.xwiki.org/xwiki/bin/view/AdminGuide/Installation#HInstallingtheXWikiWARmanually]
1.126	163
1.125	164	\\
1.139	165	At this point you have a clean install with an empty database, so the next steps will be to fill it with you old data and settings. It's a good idea to test your fresh and clean environment by pointing your browser to it (e.g. http://server:8080/xwiki)
1.126	166
1.133	167
	168	1.1.1.1 Filling it with data
	169
1.139	170	Now you need to make your first big choice on XWiki migration path: copy your database to the new environment, or migrate the desired pages using the Import/Export mechanism. Just to give you a clue on which one to use, the characteristics of each one are:
1.131	171
1.139	172	Regarding the Database copy:
1.140	173	* All pages are copied, resulting in XWiki 0.9 code inside your XWiki 1.1 installation,
	174	* XWiki will automatically make most required adjustments to the database schema
	175	* You will need to make some remaining adjustments to the database
1.139	176	Commonly, this method is used if you have a lot of custom code inside your pages, and don't want/need/like to adapt it to the new APIs. Be careful, because is strongly recommended that you adapt this code. Certainly don't delay this until long after your initial deployment in your production environment .
1.131	177
1.140	178	Regarding the Import/Export method:
	179	* You have to add some XWiki documents (scripts) and some Java code to your v0.9 installation to support export capabilities
	180	* You have to select, manually, which pages are migrated.
	181	* The process is carried out at the application level
1.132	182	Is common practice to use this process for a cleaner migration, and when you don't have ~~ad hoc~~ code inside your pages. WARNING: as the time of this writing (October 22nd, 2007) there's a problem with [v1.1 import feature>http://jira.xwiki.org/jira/browse/XWIKI-1809]
1.131	183
1.133	184	__Database copy__
	185
1.128	186	* Copy the data in your old database using the proper procedures (backup/restore, import/export, etc.), but take care that in each database and version could exist issues about encoding, schema incompatibilities, etc.
	187	** MySQL : use {style:type=span\|font-family=courier new,courier}mysqldump xwiki > xwiki.mysqldump{style} to backup and {style:type=span\|font-family=courier new,courier}mysql xwiki --user=root -p < xwiki.mysqldump{style} to store it in the new database
1.130	188	** Oracle : use exp to export data and imp to import data onto the database.
1.125	189	* Execute the next statement in your database engine : {style:type=span\|font-family=courier new,courier}alter table xwikidoc modify column XWD_ARCHIVE mediumtext null{style} (take a look at [this bug report>http://jira.xwiki.org/jira/browse/XWIKI-1702])
1.126	190	* If you are using XWiki authentication, up to XWiki 1.0 RC the passwords were stored in clear in the database. Passwords are now hashed, so, we are providing [a tool>http://www.xwiki.org/xwiki/bin/download/Main/ReleaseNotesXWiki10RC2/CryptPasswords.xar] to automatically hash all passwords from an existing database. {style:type=span\|color=red} WARNING: Start by backing up your wiki by doing an export or backuping your database. Then import that XAR into your wiki (be sure to be logged as an Admin) and then go to the Admin.CryptPasswords and follow the instructions there. {style}
	191
1.133	192	__Export/import__
	193
1.135	194	BEWARE: all the steps below will be performed in your 0.9 XWiki
	195
1.144	196	* Add the [Export/Import utility>AdminGuide.Installation_ExportImport09] to your v0.9 wiki (see also xwiki.js and prototype.js attachments to this page). To perform this action [log-in to this site>http://www.xwiki.org/], choose to edit the page and copy/paste the code to a new page in your v0.9 XWiki
1.135	197	* Make a new folder inside your skins folder called expimp and copy inside it the two javascripts files attached to this page
	198	* Add the Package capabilities to your v0.9 wiki
	199	** 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 {style:type=span\|font-family=courier new,courier}jar xvf xwiki-1.1-enterprise.war{style}
	200	** Look for the xwiki-core-~~your_version_here~~.jar, copy it to new folder (outside the path were our extracted the WAR file) and extract it into a new folder using the jar command as shown in the previous step
	201	** Change your current folder to the one were you extracted the xwki-core file and perform the command {style:type=span\|font-family=courier new,courier}jar cvf xwiki-packaging-plugin.jar com/xpn/xwiki/plugin/packaging/Package\*{style}
	202	** copy the file xwiki-packaging-plugin.jar to the webapps/xwiki/WEB-INF/lib inside your 0.9 XWiki install (the one already running in your servlet container)
	203	** add the class com.xpn.xwiki.plugin.packaging.PackagePlugin to the entry xwiki.plugins inside webapps/xwiki/WEB-INF/xwiki.cfg config file
	204	* Restart your 0.9 XWiki
1.133	205	* Export the desired pages
	206	* Import them into your v1.1 wiki
	207
1.125	208	\\
	209	Now you have the new XWiki core and your old data we can make a new test: you must see the old data and a new interface : perhaps not the best, perhaps it looks bad, but at this point we must assure that all data is correctly migrated to the new environment.
1.126	210
1.133	211
1.139	212	1.1.1.1 Let's clean it up
1.133	213
1.135	214	* 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 {style:type=span\|font-family=courier new,courier}jar xvf xwiki-1.1-enterprise.war{style}, or avoid this step if you performed an export/import data migration (you already expanded it)
1.125	215	* Copy your old {style:type=span\|font-family=courier new,courier}xwiki.cfg{style} and {style:type=span\|font-family=courier new,courier}hibernate.cfg.xml{style} 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 car to add these changes
1.127	216	* 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	217	* 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)
1.126	218
1.125	219	\\
	220	At this point all is set, you can experience our old wiki data over the new XWiki core !!!
	221
1.128	222
1.130	223
1.131	224
1.132	225
1.133	226
1.134	227
1.135	228
1.138	229
2.1	230
3.1	231
1.111	232	1.1 Troubleshooting
1.96	233
1.124	234	1.1.1 Field 'XWD_ARCHIVE' doesn't have a default value
1.96	235
1.124	236	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 <tt>xwiki.store.hibernate.updateschema</tt> configuration parameter in <tt>xwiki.cfg</tt> (it's set to on by default). However it's currently not done for this error.
1.111	237
	238	{code:none}
	239	Wrapped Exception: Could not execute JDBC batch update
1.124	240	[...]
1.111	241	Wrapped Exception:
1.124	242	java.sql.BatchUpdateException: Field 'XWD_ARCHIVE' doesn't have a default value
1.111	243	{code}
	244
	245	To fix this run the following SQL command on your database:
	246
	247	{code:sql}
1.124	248	alter table xwikidoc modify column XWD_ARCHIVE mediumtext null;
1.111	249	{code}
	250
	251	1.1.1 Failure to log in
	252
	253	Check that you don't have some old cookies and try deleting them.
1.124	254
	255

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