From version < 27.2 >
edited by cpanozo
on 2009/08/17
To version < 28.1 >
edited by Ludovic Dubost
on 2009/10/09
< >
Change comment: Document converted from syntax xwiki/1.0 to syntax xwiki/2.0

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.cpanozo
1 +XWiki.LudovicDubost
Syntax
... ... @@ -1,1 +1,1 @@
1 -XWiki 1.0
1 +XWiki 2.0
Content
... ... @@ -1,80 +1,84 @@
1 +{{velocity filter="none"}}
2 +{{html clean="false" wiki="true"}}
1 1  #startfloatingbox()
2 -*Contents*
3 -#toc ("2" "3" "")
4 +**Contents**
5 +
6 +{{toc start="2" depth="3" numbered=""/}}
4 4  #endfloatingbox()
5 5  
6 -1 Installation
9 += Installation =
7 7  
8 8  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.
9 -
12 +<p/>
10 10  There are 2 solutions when installing XWiki:
11 11  
12 -* 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.
13 -* Use the [WAR distribution>xwiki:Main.Download] and configure both your container and your database to work with it.
14 -
15 -If you're instead upgrading an existing XWiki install check the [Upgrade instructions>#HUpgradinganXWikiInstallation] below.
16 -
15 +* 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.
16 +* Use the [[WAR distribution>>xwiki:Main.Download]] and configure both your container and your database to work with it.
17 +<p/>
18 +If you're instead upgrading an existing XWiki install check the [[Upgrade instructions>>#HUpgradinganXWikiInstallation]] below.
19 +<p/>
17 17  Pick one of the trails in the outline on the right to get started.
21 +<p/>
22 +Once you've finished the installation check the other topics in the [[Admin Guide>>AdminGuide.WebHome]] for configuring and [[securing>>Security]] your wiki.
23 +<p/>
24 +{{info}}If you want to make manual installation or need to migrate an existing XWiki installation, check the [[Release Notes>>xwiki:Main.ReleaseNotes]].{{/info}}
18 18  
19 -Once you've finished the installation check the other topics in the [Admin Guide>AdminGuide.WebHome] for configuring and [securing>Security] your wiki.
26 +== Tutorials ==
20 20  
21 -#info("If you want to make manual installation or need to migrate an existing XWiki installation, check the [Release Notes>xwiki:Main.ReleaseNotes].")
22 -
23 -1.1 Tutorials
24 -
25 25  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.
29 +<p/>
30 +{{warning}}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.{{/warning}}
26 26  
27 -#warning("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.")
32 +* [[XWiki On Windows (French)>>http://agoncalves.developpez.com/tutoriels/xwiki/creer-un-site-associatif/]]
33 +* [[XWiki On Debian 4 (Etch) - Tomcat - PostgreSQL (or MySQL) (English)>>http://www.howtoforge.com/xwiki-tomcat-mysql-debian-etch]]
34 +* [[XWiki On Debian 4 (Etch) - Tomcat - PostgreSQL (or MySQL) (German)>>http://www.howtoforge.de/howto/xwiki-on-debian-4-etch-tomcat-mysql]]
28 28  
29 -* [XWiki On Windows (French)>http://agoncalves.developpez.com/tutoriels/xwiki/creer-un-site-associatif/]
30 -* [XWiki On Debian 4 (Etch) - Tomcat - PostgreSQL (or MySQL) (English)>http://www.howtoforge.com/xwiki-tomcat-mysql-debian-etch]
31 -* [XWiki On Debian 4 (Etch) - Tomcat - PostgreSQL (or MySQL) (German)>http://www.howtoforge.de/howto/xwiki-on-debian-4-etch-tomcat-mysql]
36 +== Prerequisites ==
32 32  
33 -
34 -1.1 Prerequisites
35 -
36 36  You'll need to have Java 5 installed.
37 37  
38 -1.1 Installing the Standalone distribution
40 +== Installing the Standalone distribution ==
39 39  
40 40  This is by far the easiest way to install XWiki. We are offering 3 packaging for ease of installation:
43 +
41 41  * 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/.
42 42  * 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.
43 -* A zip version. Unzip it in any <tt>\[XWIKIHOME\]</tt> directory of your choice.
46 +* A zip version. Unzip it in any <tt>[[XWIKIHOME]]</tt> directory of your choice.
47 +<p/>
48 +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.
49 +<p/>
50 +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. To change the port, edit the start script and replace 8080 by the number you want.
51 +<p/>
52 +{{info}}You can log in using the default Admin user (first letter is capitalized). The default password is 'admin' (lowercase).{{/info}}
44 44  
45 -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.
54 +== Installing the XWiki WAR manually ==
46 46  
47 -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. To change the port, edit the start script and replace 8080 by the number you want.
48 -
49 -#info("You can log in using the default Admin user (first letter is capitalized). The default password is 'admin' (lowercase).")
50 -1.1 Installing the XWiki WAR manually
51 -
52 52  You'll need to perform 2 mandatory steps:
53 53  
54 54  * Install and configure a Servlet Container
55 55  * Install and configure a relational database
60 +<p/>
61 +{{info}}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>>code:Applications.PanelsApplication]].{{/info}}
62 +<p/>
63 +{{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.{{/info}}
56 56  
57 -#info("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>code:Applications.PanelsApplication].")
65 +=== Install and configure a Servlet Container ===
58 58  
59 -#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.")
60 -
61 -1.1.1 Install and configure a Servlet Container
62 -
63 63  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.
64 64  
65 -* [Tomcat installation>AdminGuide.InstallationTomcat]
66 -* [Jetty installation>AdminGuide.InstallationJetty]
67 -* [GlassFish installation>AdminGuide.InstallationGlassFish]
68 -* [WebSphere installation>AdminGuide.InstallationWebSphere]
69 -* [JBoss Installation>AdminGuide.InstallationJBoss]
70 -* [Oracle OC4J Installation>AdminGuide.InstallationOC4J]
71 -
69 +* [[Tomcat installation>>AdminGuide.InstallationTomcat]]
70 +* [[Jetty installation>>AdminGuide.InstallationJetty]]
71 +* [[GlassFish installation>>AdminGuide.InstallationGlassFish]]
72 +* [[WebSphere installation>>AdminGuide.InstallationWebSphere]]
73 +* [[JBoss Installation>>AdminGuide.InstallationJBoss]]
74 +* [[Oracle OC4J Installation>>AdminGuide.InstallationOC4J]]
75 +<p/>
72 72  You're now ready to install and configure your relational database.
73 73  
74 -1.1.1 Install and configure a Relational Database
78 +=== Install and configure a Relational Database ===
75 75  
76 76  XWiki can work with a lot of relational databases. We're only listed those that we have tested it on.
77 -
81 +<p/>
78 78  The general strategy is the following:
79 79  
80 80  * Install your favorite RDBMS
... ... @@ -82,141 +82,132 @@
82 82  * Create a user with all privileges on that xwiki database
83 83  * Copy your RDBMS Java drivers to the XWiki webapp's <tt>WEB-INF/lib</tt> directory
84 84  * 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.
85 -
86 86  * (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.
87 87  ** Do not add your JDBC library to the web app. Install it to the container classpath instead, like to <tt>$CATALINA_HOME/common/lib</tt>.
88 88  ** Do not set user, url, etc., nor connection.provider_class in <tt>hibernate.cfg.xml</tt>. The critical settings are <tt>connection.datasource</tt> (with JNDI name like "java:/comp/env/jdbc/test") and the dialect class for your DB vendor. (You should leave the provider_class unset, since Xwiki's implementation doesn't handle container-managed data sources).
89 89  ** Manage all database access settings using your container facilities, for example Tomcat admin webapp or server.xml + APPNAME.xml.
93 +<p/>
90 90  )
91 91  
92 92  Install and configure the database you wish to use:
93 93  
94 -* [HSQL Installation>AdminGuide.InstallationHSQL]
95 -* [MySQL Installation>AdminGuide.InstallationMySQL]
96 -* [PostgreSQL Installation>AdminGuide.InstallationPostgreSQL]
97 -* [Oracle Installation>AdminGuide.InstallationOracle]
98 -* [DB2 Installation>AdminGuide.InstallationDB2]
99 -* [Derby Installation>AdminGuide.InstallationDerby]
100 -* [Microsoft SQL Server Installation>AdminGuide.InstallationMSSQL]
98 +* [[HSQL Installation>>AdminGuide.InstallationHSQL]]
99 +* [[MySQL Installation>>AdminGuide.InstallationMySQL]]
100 +* [[PostgreSQL Installation>>AdminGuide.InstallationPostgreSQL]]
101 +* [[Oracle Installation>>AdminGuide.InstallationOracle]]
102 +* [[DB2 Installation>>AdminGuide.InstallationDB2]]
103 +* [[Derby Installation>>AdminGuide.InstallationDerby]]
104 +* [[Microsoft SQL Server Installation>>AdminGuide.InstallationMSSQL]]
101 101  
102 -1.1.1 Concluding Step
106 +=== Concluding Step ===
103 103  
104 -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].
108 +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]].
105 105  
106 -1.1 Installing the eXo Enterprise WebOS integration WAR
110 +== Installing the eXo Enterprise WebOS integration WAR ==
107 107  
108 -#warning("The integration with eXo is still very experimental and the instructions below are not finalized yet. Proceed with caution!")
112 +{{warning}}The integration with eXo is still very experimental and the instructions below are not finalized yet. Proceed with caution!{{/warning}}
109 109  
110 -1.1.1 Install eXo WebOS
114 +=== Install eXo WebOS ===
111 111  
112 112  * Download the latest version of eXo Portal on http://forge.objectweb.org/projects/exoplatform/ (version 2.0-Alpha-2 or greater is required).
113 113  * Follow the eXo installation instructions located inside the Portal ZIP and try to login in the portal.
114 114  
115 -1.1.1 Install XWiki inside eXo
119 +=== Install XWiki inside eXo ===
116 116  
117 117  * Stop eXo Portal.
118 -* Download the [latest XWiki eXo WAR>xwiki:Main.Download]. You'll need version 1.0-beta-6 or above.
119 -* Create a directory ~~exo-tomcat/webapps/xwiki~~.
120 -* Unzip the WAR in ~~exo-tomcat/webapps/xwiki~~ and rename the exploded directory to "xwiki".
121 -* 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).
122 -* Remove all the eXo jars from ~~xwiki/WEB-INF/lib~~
123 -* Configure XWiki's database as explained [above>#HInstallandconfigureaRelationalDatabase].
124 -* Change in ~~xwiki.cfg~~: xwiki.exo=1 to xwiki.exo=0. TODO: Explain why this is required as it is very counter-intuitive!
122 +* Download the [[latest XWiki eXo WAR>>xwiki:Main.Download]]. You'll need version 1.0-beta-6 or above.
123 +* Create a directory //exo-tomcat/webapps/xwiki//.
124 +* Unzip the WAR in //exo-tomcat/webapps/xwiki// and rename the exploded directory to "xwiki".
125 +* 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).
126 +* Remove all the eXo jars from //xwiki/WEB-INF/lib//
127 +* Configure XWiki's database as explained [[above>>#HInstallandconfigureaRelationalDatabase]].
128 +* Change in //xwiki.cfg//: xwiki.exo=1 to xwiki.exo=0. TODO: Explain why this is required as it is very counter-intuitive!
125 125  * Restart eXo Portal.
126 126  * You can now either import XWiki as a Portlet inside the Portal as described below or access XWiki directly by using the usual URL.
127 -* [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.
128 -* Import the [default wiki XAR>xwiki:Main.Download] or use your own XWiki database.
131 +* [[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.
132 +* Import the [[default wiki XAR>>xwiki:Main.Download]] or use your own XWiki database.
129 129  * Give the admin right to XWikiGuest
130 130  * To be continued...
131 131  
132 -1.1.1 Use XWiki inside the WebOS
136 +=== Use XWiki inside the WebOS ===
133 133  
134 134  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.
135 135  
136 -1.1 Installing the Default Wiki XAR
140 +== Installing the Default Wiki XAR ==
137 137  
138 138  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:
143 +
139 139  * A Blog
140 140  * Photo albums
141 141  * A What's New page
142 -* The [Panels Application>code:Applications.PanelsApplication]
147 +* The [[Panels Application>>code:Applications.PanelsApplication]]
143 143  * Search
144 144  * Administration page (Access rights, Group and users management, etc)
145 145  * ... and much more
151 +<p/>
152 +**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.**
153 +<p/>
154 +To install the XAR, use the [[Import/Export tool>>AdminGuide.ImportExport]].
155 +<p/>
156 +{{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>>platform:AdminGuide.Backup]] first.{{/warning}}
146 146  
147 -*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.*
158 +== Upgrading an XWiki Installation ==
148 148  
149 -To install the XAR, use the [Import/Export tool>AdminGuide.ImportExport].
150 -
151 -#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>platform:AdminGuide.Backup] first.")
152 -
153 -1.1 Upgrading an XWiki Installation
154 -
155 155  There are different parts of XWiki that you may want to upgrade:
156 156  
157 -* [XWiki Core>#HUpgradingXWikiCore]
158 -* [Documents provided with the default XWiki XAR>#HUpgradingwikidocuments]
162 +* [[XWiki Core>>#HUpgradingXWikiCore]]
163 +* [[Documents provided with the default XWiki XAR>>#HUpgradingwikidocuments]]
164 +<p/>
165 +{{info}}If you're upgrading an XWiki 0.9 installation refer to [[this guide>>UpgradeXWiki09Installation]].{{/info}}
159 159  
160 -#info("If you're upgrading an XWiki 0.9 installation refer to [this guide>UpgradeXWiki09Installation].")
167 +=== Upgrading XWiki Core ===
161 161  
162 -1.1.1 Upgrading XWiki Core
169 +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&#45;INF/lib). Before replacing your current WAR, make sure you back it up and more specifically that you copy the <tt>hibernate.cfg.xml</tt> and <tt>xwiki.cfg</tt> 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.
170 +<p/>
171 +Some additional operations may be required for upgrading and you must check the [[release notes>>xwiki:Main.ReleaseNotes]] 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 <tt>xwiki.cfg</tt> file needs to be modified. If this is the case then it'll be specified in the release notes.
163 163  
164 -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&#45;INF/lib). Before replacing your current WAR, make sure you back it up and more specifically that you copy the <tt>hibernate.cfg.xml</tt> and <tt>xwiki.cfg</tt> 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.
173 +=== Upgrading wiki documents ===
165 165  
166 -Some additional operations may be required for upgrading and you must check the [release notes>xwiki:Main.ReleaseNotes] 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 <tt>xwiki.cfg</tt> file needs to be modified. If this is the case then it'll be specified in the release notes.
175 +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:
167 167  
168 -1.1.1 Upgrading wiki documents
169 -
170 -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:
171 -
172 172  * 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.
173 173  * XWiki.WebPreferences, Main.WebPreferences, and all other spaces WebPreferences pages: Same as XWiki.XWikiPreferences but at the level of a space.
174 174  * 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.
175 175  * Any other page you have modified, such as Main.WebHome, a modified Panel, etc.
176 176  
177 -1.1.1.1 Let's clean it up
182 +==== Let's clean it up ====
178 178  
179 -* 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)
180 -* 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&#45;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
181 -* 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~~)
184 +* 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="font-family:courier new,courier; " %) jar xvf xwiki-1.1-enterprise.war(%%), or avoid this step if you performed an export/import data migration (you already expanded it)
185 +* Copy your old (% style="font-family:courier new,courier; " %) xwiki.cfg(%%) and (% style="font-family:courier new,courier; " %) hibernate.cfg.xml(%%) file to the WEB&#45;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
186 +* 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//)
182 182  * 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)
188 +<p/>
189 +<br/>
190 +At this point all is set, you can experience our old wiki data over the new XWiki core ~!!!
183 183  
184 -\\
185 -At this point all is set, you can experience our old wiki data over the new XWiki core !!!
192 +== Troubleshooting ==
186 186  
194 +=== Verify your installation ===
187 187  
196 +You can verify some basic settings of your XWiki install (on Tomcat, MySQL) using the [[check Config and Indexes application>>code:Applications.CheckConfigAndIndexesApplication]].
188 188  
198 +=== Field 'XWD_ARCHIVE' doesn't have a default value ===
189 189  
190 -
191 -
192 -
193 -
194 -
195 -
196 -1.1 Troubleshooting
197 -
198 -1.1.1 Verify your installation
199 -
200 -You can verify some basic settings of your XWiki install (on Tomcat, MySQL) using the [check Config and Indexes application>code:Applications.CheckConfigAndIndexesApplication].
201 -
202 -1.1.1 Field 'XWD_ARCHIVE' doesn't have a default value
203 -
204 204  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.
201 +{{/html}}
202 +{{/velocity}}
205 205  
206 -{code:none}
204 +{{code language="none"}}
207 207  Wrapped Exception: Could not execute JDBC batch update
208 208  [...]
209 209  Wrapped Exception:
210 -java.sql.BatchUpdateException: Field 'XWD_ARCHIVE' doesn't have a default value
211 -{code}
208 +java.sql.BatchUpdateException: Field 'XWD_ARCHIVE' doesn't have a default value
209 +{{/code}}
212 212  
213 213  To fix this run the following SQL command on your database:
214 214  
215 -{code:sql}
216 -alter table xwikidoc modify column XWD_ARCHIVE mediumtext null;
217 -{code}
213 +{{code language="sql"}}alter table xwikidoc modify column XWD_ARCHIVE mediumtext null;{{/code}}
218 218  
219 -1.1.1 Failure to log in
215 +=== Failure to log in ===
220 220  
221 221  Check that you don't have some old cookies and try deleting them.
222 -
XWiki.XWikiComments[0]
Comment
... ... @@ -1,2 +1,1 @@
1 -Will there be XWiki on Oracle database setup details?
2 -Xwiki 1.0 beta supports Oracle database?
1 +Will there be XWiki on Oracle database setup details? Xwiki 1.0 beta supports Oracle database?
XWiki.XWikiComments[3]
Comment
... ... @@ -1,1 +1,1 @@
1 -I think the point both the first two comments are making is that XWiki Beta 1 is meant to be capable of runing on an empty db [see blog entry >Blog.XWiki10Beta1Released]. Personally using Derby I can't get this to work (although it is not clear if the db needs to contain a set of empty tables or can be table-less). Perhaps a discussion for the maining list
1 +I think the point both the first two comments are making is that XWiki Beta 1 is meant to be capable of runing on an empty db [[see blog entry>>Blog.XWiki10Beta1Released]]. Personally using Derby I can't get this to work (although it is not clear if the db needs to contain a set of empty tables or can be table-less). Perhaps a discussion for the maining list
XWiki.XWikiComments[4]
Comment
... ... @@ -1,5 +1,3 @@
1 -Default administrator login after installation is:
2 -Username: Admin ('A' capitalized, not: admin or Administrator)
3 -Password: admin (all lowercase)
1 +Default administrator login after installation is: Username: Admin ('A' capitalized, not: admin or Administrator) Password: admin (all lowercase)
4 4  
5 5  This user is not available if you just deploy the .war on tomcat or jetty; You must also import the xwiki-1.0-beta-1.xar.xar into your XWiki instance. In which case you might need to know how to enable the superadmin user: (http://www.xwiki.org/xwiki/bin/view/FAQ/HowCanIGetBackAdminRightsWhenIDeletedThemForMeByAccident)
XWiki.XWikiComments[5]
Comment
... ... @@ -1,12 +1,7 @@
1 -I have virtual hosts setup on my machine. I'm running the standalone on port 9090. I get the following when I go to the wiki page:
1 +I have virtual hosts setup on my machine. I'm running the standalone on port 9090. I get the following when I go to the wiki page:
2 2  
3 -Error 404 - Not Found.
4 -No context on this server matched or handled this request.
5 -Contexts known to this server are:
6 -WebApplicationContext[/xwiki,xwiki]
7 -The links above may not work if a virtual host is configured.
3 +Error 404 - Not Found. No context on this server matched or handled this request. Contexts known to this server are: WebApplicationContext[[/xwiki,xwiki]] The links above may not work if a virtual host is configured.
8 8  
9 9  Is there a smaple Vhost config around that I could take a look at?
10 10  
11 -Cheers,
12 -Dave
7 +Cheers, Dave
XWiki.XWikiComments[6]
Comment
XWiki.XWikiComments[7]
Comment
... ... @@ -1,2 +1,1 @@
1 -Adel,
2 -You need to login as an admin user to do this. I used a previously-populated database and had to revert to the superadmin - this worked like a charm for me (do a search on lost admin permissions for details on how to set this up).
1 +Adel, You need to login as an admin user to do this. I used a previously-populated database and had to revert to the superadmin - this worked like a charm for me (do a search on lost admin permissions for details on how to set this up).
XWiki.XWikiComments[8]
Comment
... ... @@ -1,2 +1,1 @@
1 -from the old xwiki site I found the note for config oracle.
2 -I don't quite understand the step 4 for oracle10g, it said "Add the hibernate user type class from http://www.hibernate.org/56.html? and then ..." what that mean?, Do I need to change the java class...?
1 +from the old xwiki site I found the note for config oracle. I don't quite understand the step 4 for oracle10g, it said "Add the hibernate user type class from http://www.hibernate.org/56.html? and then ..." what that mean?, Do I need to change the java class...?
XWiki.XWikiComments[9]
Comment
... ... @@ -1,13 +1,13 @@
1 -OK, here goes -- again. I was entering a comment when an error page came up after pasting in some text from a file that apparently wasn't allowed. Anyway...
1 +OK, here goes ~-~- again. I was entering a comment when an error page came up after pasting in some text from a file that apparently wasn't allowed. Anyway...
2 2  
3 -I installed XWiki into my JBoss installation because I have already been using JBoss for other projects. After logging in with 'admin' and 'admin' for user/password I was able to import the demo .xar that was available, I expect that the personnel at XWiki are still working on the documentation. At first I had a problem with the [resource-ref] javax.sql.DataSource in the [server-dir]\deploy\xwiki.war\WEB-INF\web.xml file, something about the name not being bound and I couldn't get the site to come up.
3 +I installed XWiki into my JBoss installation because I have already been using JBoss for other projects. After logging in with 'admin' and 'admin' for user/password I was able to import the demo .xar that was available, I expect that the personnel at XWiki are still working on the documentation. At first I had a problem with the [[resource-ref]] javax.sql.DataSource in the [[server-dir]]deployxwiki.warWEB-INFweb.xml file, something about the name not being bound and I couldn't get the site to come up.
4 4  
5 5  For the database, I created an empty MySQL database with the appropriate user/pword combo and didn't have any problems with it.
6 6  
7 -I didn't want to deal with this so I commented it out temporarily to see how far I could get. The next error was a parse error in Log4J, so I removed the log4j-1.2.13.jar file in [server-dir]\deploy\xwiki.war\WEB-INF\lib because I knew that JBoss comes with this file.
7 +I didn't want to deal with this so I commented it out temporarily to see how far I could get. The next error was a parse error in Log4J, so I removed the log4j-1.2.13.jar file in [[server-dir]]deployxwiki.warWEB-INFlib because I knew that JBoss comes with this file.
8 8  
9 -After that (and adding a jboss-web.xml file in the WEB-INF dir) I uncommented the [resource-ref] I commented out before and now it seems to be running, albeit with tons of errors, but I'm sure this is because I'm using the demo .xar files.
9 +After that (and adding a jboss-web.xml file in the WEB-INF dir) I uncommented the [[resource-ref]] I commented out before and now it seems to be running, albeit with tons of errors, but I'm sure this is because I'm using the demo .xar files.
10 10  
11 -For now I think I'm going to kick back and do some reading -- what a concept (I'm impatient sometimes).
11 +For now I think I'm going to kick back and do some reading ~-~- what a concept (I'm impatient sometimes).
12 12  
13 13  Tom
XWiki.XWikiComments[10]
Comment
... ... @@ -1,11 +1,11 @@
1 -pour les français, voici de quoi démarrer pour la xwiki-1.0-beta-5 avec cette traduction du minimum:
2 -Si vous utilisez le package d'installation de Windows (.exe), il suffit de suivre les instructions. Ce dernier crée un raccourci pour démarrer/stopper XWiki.
3 -Si vous êtes sur une autre plateforme, récupérez le tar.gz et décompressez le dans le répertoire XWIKIHOME de votre choix. Cette archive procure scripts bat (windows) ou sh (linux) pour démarrer/stopper XWiki.
1 +pour les français, voici de quoi démarrer pour la xwiki-1.0-beta-5 avec cette traduction du minimum: Si vous utilisez le package d'installation de Windows (.exe), il suffit de suivre les instructions. Ce dernier crée un raccourci pour démarrer/stopper XWiki. Si vous êtes sur une autre plateforme, récupérez le tar.gz et décompressez le dans le répertoire XWIKIHOME de votre choix. Cette archive procure scripts bat (windows) ou sh (linux) pour démarrer/stopper XWiki.
4 4  
5 5  Une fois XWiki démarré allez sur http://localhost:8080/xwiki/bin/view/Main/WebHome et rendez vous sur le guide utilisateur pour apprendre comment utiliser XWiki. Pour changer le port, éditez le script de démarrage et changer 8080 par un autre nombre.
6 6  
7 7  un peu plus haut dans les commentaires, on trouve le login/pass du super utilisateur, avec attention au respect de la casse (majuscules/minuscules) :
8 -- login : Admin
9 -- pass : admin
10 10  
7 +(% style="list-style-type: square" %)
8 +* login : Admin
9 +* pass : admin
10 +
11 11  best regards ;)
XWiki.XWikiComments[11]
Comment
... ... @@ -1,2 +1,1 @@
1 -could somewone say where the french translation is ?
2 -if there is not and if an admin can activate french language i will be please to help updating the documentation's translation process...
1 +could somewone say where the french translation is ? if there is not and if an admin can activate french language i will be please to help updating the documentation's translation process...
XWiki.XWikiComments[14]
Comment
... ... @@ -2,19 +2,20 @@
2 2  
3 3  Add the following to resin.conf
4 4  
5 -{code:xml}
5 +{{code language="xml"}}
6 6  <system-property javax.xml.parsers.DocumentBuilderFactory=
7 7   "org.apache.xerces.jaxp.DocumentBuilderFactoryImpl"/>
8 8  <system-property javax.xml.parsers.SAXParserFactory=
9 9   "org.apache.xerces.jaxp.SAXParserFactoryImpl"/>
10 -{code}
10 +{{/code}}
11 11  
12 12  Also, you will need to edit the web.xml and remove the XWikiDS element:
13 -{code:xml}
14 - <resource-ref>
13 +
14 +{{code language="xml"}}
15 +<resource-ref>
15 15   <description>DB Connection</description>
16 16   <res-ref-name>jdbc/XWikiDS</res-ref-name>
17 17   <res-type>javax.sql.DataSource</res-type>
18 18   <res-auth>Container</res-auth>
19 19   </resource-ref>
20 -{code}
21 +{{/code}}
XWiki.XWikiComments[15]
Comment
XWiki.XWikiComments[16]
Comment
XWiki.XWikiComments[17]
Comment
... ... @@ -1,8 +1,5 @@
1 -Anybody successfully installed Xwiki based on ORACLE 10G database. I has created database XWIKI on ORACLE 10G with xwiki user(all privileges is granted), I copied correct version of JDBC driver in WEB-INF\lib and modified hibernate.cfg.xml to point oracle database. The error sound something like this:
2 -15:58:08,781 FATAL http-8080-Processor25 http://localhost:8080/xwiki/bin/login/XWiki/XWikiLogin DBCPConnectionProvider:configure:191 - Could not create a DBCP pool
3 -org.apache.commons.dbcp.SQLNestedException: Cannot create PoolableConnectionFactory (Io exception: The Network Adapter could not establish the connection).....
1 +Anybody successfully installed Xwiki based on ORACLE 10G database. I has created database XWIKI on ORACLE 10G with xwiki user(all privileges is granted), I copied correct version of JDBC driver in WEB-INFlib and modified hibernate.cfg.xml to point oracle database. The error sound something like this: 15:58:08,781 FATAL http-8080-Processor25 http://localhost:8080/xwiki/bin/login/XWiki/XWikiLogin DBCPConnectionProvider:configure:191 - Could not create a DBCP pool org.apache.commons.dbcp.SQLNestedException: Cannot create PoolableConnectionFactory (Io exception: The Network Adapter could not establish the connection).....
4 4  
5 -Any sugestions will be usefull....
6 -Thanks.
3 +Any sugestions will be usefull.... Thanks.
7 7  
8 8  Ghita.
XWiki.XWikiComments[19]
Comment
... ... @@ -1,4 +1,3 @@
1 1  I have installed Xwiki successfully, i am not able to login with Admin,admin(pword), even i tried with changing the xwiki configuration file. Pls any know how to set / retrieve / loggin to admin?
2 2  
3 -thanks in advance
4 -Sabarish R L
3 +thanks in advance Sabarish R L
XWiki.XWikiComments[20]
Comment
... ... @@ -4,21 +4,19 @@
4 4  
5 5  for information, the installation on Mac OS X is ok. Except when logging with theses :
6 6  
7 - * Admin
8 - * admin
7 +* Admin
8 +* admin
9 9  
10 10  any idea why ?
11 11  
12 +----
12 12  
13 ------
14 -
15 -
16 16  Bonjour,
17 17  
18 18  Pour info, l'installation sur Mac OS X se passe comme prévu. Sauf au moment de se connecter ces identifiants :
19 19  
20 - * Admin
21 - * admin
18 +* Admin
19 +* admin
22 22  
23 23  donnent en retour le message suivant : "Nom d'utilisateur erroné" !?
24 24  
XWiki.XWikiComments[21]
Comment
... ... @@ -4,21 +4,19 @@
4 4  
5 5  for information, the installation on Mac OS X is ok. Except when logging with theses :
6 6  
7 - * Admin
8 - * admin
7 +* Admin
8 +* admin
9 9  
10 10  any idea why ?
11 11  
12 +----
12 12  
13 ------
14 -
15 -
16 16  Bonjour,
17 17  
18 18  Pour info, l'installation sur Mac OS X se passe comme prévu. Sauf au moment de se connecter ces identifiants :
19 19  
20 - * Admin
21 - * admin
18 +* Admin
19 +* admin
22 22  
23 23  donnent en retour le message suivant : "Nom d'utilisateur erroné" !?
24 24  
XWiki.XWikiComments[22]
Comment
... ... @@ -1,12 +1,5 @@
1 1  I have the next error in a typical installing:
2 2  
3 -INFO: Instalando aplicaciones web en trayectoria de contexto /xwiki desde URL file:/var/lib/tomcat5/webapps/xwiki
4 -10-oct-2007 11:14:05 org.apache.catalina.core.StandardContext processTlds
5 -GRAVE: Error reading tld listeners javax.servlet.ServletException: Excepción durante el tratamiento de la TLD indicada por la trayectoria de recurso /WEB-INF/struts-logic.tld
6 -javax.servlet.ServletException: Excepción durante el tratamiento de la TLD indicada por la trayectoria de recurso /WEB-INF/struts-logic.tld
7 - at org.apache.catalina.startup.TldConfig.tldScanTld(TldConfig.java:549)
8 - at org.apache.catalina.startup.TldConfig.execute(TldConfig.java:301)
3 +INFO: Instalando aplicaciones web en trayectoria de contexto /xwiki desde URL file:/var/lib/tomcat5/webapps/xwiki 10-oct-2007 11:14:05 org.apache.catalina.core.StandardContext processTlds GRAVE: Error reading tld listeners javax.servlet.ServletException: Excepción durante el tratamiento de la TLD indicada por la trayectoria de recurso /WEB-INF/struts-logic.tld javax.servlet.ServletException: Excepción durante el tratamiento de la TLD indicada por la trayectoria de recurso /WEB-INF/struts-logic.tld at org.apache.catalina.startup.TldConfig.tldScanTld(TldConfig.java:549) at org.apache.catalina.startup.TldConfig.execute(TldConfig.java:301)
9 9  
10 -
11 -Any ideas???
12 -Thank you in advanced.
5 +Any ideas??? Thank you in advanced.
XWiki.XWikiComments[23]
Comment
... ... @@ -1,2 +1,1 @@
1 -I set to TOMCAT_SECURITY=no in /etc/default/tomcat5 and it starts!!
2 -Thank you.
1 +I set to TOMCAT_SECURITY=no in /etc/default/tomcat5 and it starts!! Thank you.
XWiki.XWikiComments[25]
Comment
XWiki.XWikiComments[26]
Comment
... ... @@ -1,7 +1,3 @@
1 -Hi.
2 -I am upgrading from 0.9. to 1.2.
3 -I tried to add the export feature to my 0.9 xwiki.
4 -I can choose a space to export, but the resulting xar file is empty.
5 -What can be wrong?
1 +Hi. I am upgrading from 0.9. to 1.2. I tried to add the export feature to my 0.9 xwiki. I can choose a space to export, but the resulting xar file is empty. What can be wrong?
6 6  
7 7  Tom
XWiki.XWikiComments[27]
Comment
... ... @@ -1,2 +1,1 @@
1 -How to integrate xwiki with the latest exo webos????
2 -It can't work with exo-eXoUltimateProduct-r23239-tomcat.
1 +How to integrate xwiki with the latest exo webos???? It can't work with exo-eXoUltimateProduct-r23239-tomcat.
XWiki.XWikiComments[28]
Comment
... ... @@ -1,1 +1,1 @@
1 -It's really crazy that (like several products products with similar design) Xwiki goes through so much trouble to properly separate their app from configuration data, then you destroy the purpose of a .war file by requiring users to extract and edit it. Just because Confluence does it that way does not mean it's good design-- it's bad design. You should do something like JTrak and use a Java system property to allow the user to override the bundled hibernate.properties.
1 +It's really crazy that (like several products products with similar design) Xwiki goes through so much trouble to properly separate their app from configuration data, then you destroy the purpose of a .war file by requiring users to extract and edit it. Just because Confluence does it that way does not mean it's good design~-~- it's bad design. You should do something like JTrak and use a Java system property to allow the user to override the bundled hibernate.properties.
XWiki.XWikiComments[30]
Comment
... ... @@ -1,7 +1,5 @@
1 -Is the section regarding Upgrading wiki documents also valid for the current versions?
2 -I had problems from version 1.4.x to version 1.5.x. i had only text-links in the top-menubar (administration and so on).
1 +Is the section regarding Upgrading wiki documents also valid for the current versions? I had problems from version 1.4.x to version 1.5.x. i had only text-links in the top-menubar (administration and so on).
3 3  
4 4  as this was only a testwiki , I did a full installation.
5 5  
6 6  but I'm not sure what todo if this were an production-wiki
7 -
XWiki.XWikiComments[31]
Comment
... ... @@ -1,2 +1,1 @@
1 -i intalled xwiki 2.0 milestone3 over Tomcat and Postgresql, but i' ve this error: "java.lang.NoSuchMethodError: org.w3c.dom.Document.adoptNode(Lorg/w3c/dom/Node;)Lorg/w3c/dom/Node;
2 -"
1 +i intalled xwiki 2.0 milestone3 over Tomcat and Postgresql, but i' ve this error: "java.lang.NoSuchMethodError: org.w3c.dom.Document.adoptNode(Lorg/w3c/dom/Node;)Lorg/w3c/dom/Node; "
Date
... ... @@ -1,1 +1,1 @@
1 -2009-08-17 03:00:36.462
1 +2009-08-17 03:00:36.0
ContentsThe [toc] macro is a standalone macro and it cannot be used inline

Installation

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.

There are 2 solutions when installing XWiki:

  • Use the Standalone distribution 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.
  • Use the WAR distribution and configure both your container and your database to work with it.

    If you're instead upgrading an existing XWiki install check the Upgrade instructions below.

    Pick one of the trails in the outline on the right to get started.

    Once you've finished the installation check the other topics in the Admin Guide for configuring and securing your wiki.

    If you want to make manual installation or need to migrate an existing XWiki installation, check the Release Notes.

Tutorials

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.

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.

Prerequisites

You'll need to have Java 5 installed.

Installing the Standalone distribution

This is by far the easiest way to install XWiki. We are offering 3 packaging for ease of installation:

  • 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/.
  • 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.
  • A zip version. Unzip it in any

    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.

    Once XWiki is started point your browser to http://localhost:8080/xwiki/bin/view/Main/WebHome and the go to the User's Guide to learn how to use XWiki. To change the port, edit the start script and replace 8080 by the number you want.

    You can log in using the default Admin user (first letter is capitalized). The default password is 'admin' (lowercase).
  • A zip version. Unzip it in any XWIKIHOME directory of your choice.

    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.

    Once XWiki is started point your browser to http://localhost:8080/xwiki/bin/view/Main/WebHome and the go to the User's Guide to learn how to use XWiki. To change the port, edit the start script and replace 8080 by the number you want.

    You can log in using the default Admin user (first letter is capitalized). The default password is 'admin' (lowercase).

Installing the XWiki WAR manually

You'll need to perform 2 mandatory steps:

  • Install and configure a Servlet Container
  • Install and configure a relational database

    If your database is empty this will result in a minimal empty wiki installation. You may want to use the Import/Export tool to import some pages in your wiki. We recommend that you import the provided default XAR. 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.

    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.

Install and configure a Servlet Container

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.

Install and configure a Relational Database

XWiki can work with a lot of relational databases. We're only listed those that we have tested it on.

The general strategy is the following:

  • Install your favorite RDBMS
  • Create a xwiki database
  • Create a user with all privileges on that xwiki 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. 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.
  • Copy your RDBMS Java drivers to the XWiki webapp's * Configure XWiki to use the created database. This involves modifying the * (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.
    • Do not add your JDBC library to the web app. Install it to the container classpath instead, like to Do not set user, url, etc., nor connection.provider_class in Manage all database access settings using your container facilities, for example Tomcat admin webapp or server.xml + APPNAME.xml.
  • (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.
    • Do not add your JDBC library to the web app. Install it to the container classpath instead, like to $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/test") and the dialect class for your DB vendor. (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.

      )

)

Install and configure the database you wish to use:

Concluding Step

Concluding Step

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, by using the Import feature.

Installing the eXo Enterprise WebOS integration WAR

Installing the eXo Enterprise WebOS integration WAR

The integration with eXo is still very experimental and the instructions below are not finalized yet. Proceed with caution!

Install eXo WebOS

Install eXo WebOS

  • Download the latest version of eXo Portal on http://forge.objectweb.org/projects/exoplatform/ (version 2.0-Alpha-2 or greater is required).
  • Follow the eXo installation instructions located inside the Portal ZIP and try to login in the portal.

Install XWiki inside eXo

Install XWiki inside eXo

  • Stop eXo Portal.
  • Download the latest XWiki eXo WAR. You'll need version 1.0-beta-6 or above.
  • Create a directory exo-tomcat/webapps/xwiki.
  • Unzip the WAR in exo-tomcat/webapps/xwiki and rename the exploded directory to "xwiki".
  • 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).
  • Remove all the eXo jars from xwiki/WEB-INF/lib
  • Configure XWiki's database as explained above.
  • Change in xwiki.cfg: xwiki.exo=1 to xwiki.exo=0. TODO: Explain why this is required as it is very counter-intuitive!
  • Restart eXo Portal.
  • You can now either import XWiki as a Portlet inside the Portal as described below or access XWiki directly by using the usual URL.
  • Change the skin to use the XWiki 1.0 skin. This skin is compatible with the Portlet mode and specifically with eXo WebOS.
  • Import the default wiki XAR or use your own XWiki database.
  • Give the admin right to XWikiGuest
  • To be continued...

Use XWiki inside the WebOS

Use XWiki inside the WebOS

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.

Installing the Default Wiki XAR

Installing the Default Wiki XAR

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:

  • A Blog
  • Photo albums
  • A What's New page
  • The Panels Application
  • Search
  • Administration page (Access rights, Group and users management, etc)
  • ... and much more

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.

To install the XAR, use the Import/Export tool.

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.

  • A Blog
  • Photo albums
  • A What's New page
  • The Panels Application
  • Search
  • Administration page (Access rights, Group and users management, etc)
  • ... and much more

    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.

    To install the XAR, use the Import/Export tool.

    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.

Upgrading an XWiki Installation

Upgrading an XWiki Installation

There are different parts of XWiki that you may want to upgrade:

If you're upgrading an XWiki 0.9 installation refer to this guide.

Upgrading XWiki Core

Upgrading XWiki Core

The general strategy is to download the WAR distribution 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.

The general strategy is to download the WAR distribution 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.

Some additional operations may be required for upgrading and you must check the release notes 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.

Some additional operations may be required for upgrading and you must check the release notes 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.

Upgrading wiki documents

Upgrading wiki documents

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 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:

  • 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.
  • XWiki.WebPreferences, Main.WebPreferences, and all other spaces WebPreferences pages: Same as XWiki.XWikiPreferences but at the level of a space.
  • 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.
  • Any other page you have modified, such as Main.WebHome, a modified Panel, etc.

Let's clean it up

Let's clean it up

  • 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) 
  • 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)
  • Copy your old  xwiki.cfg 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
  • Copy your old xwiki.cfg 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
  • 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)
  • 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)
  • 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)


    At this point all is set, you can experience our old wiki data over the new XWiki core !!!

\ At this point all is set, you can experience our old wiki data over the new XWiki core !!!

Troubleshooting

Troubleshooting

Verify your installation

Verify your installation

You can verify some basic settings of your XWiki install (on Tomcat, MySQL) using the check Config and Indexes application.

Field 'XWD_ARCHIVE' doesn't have a default value

Field 'XWD_ARCHIVE' doesn't have a default value

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.

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.

Wrapped Exception: Could not execute JDBC batch update
[...]
Wrapped Exception:
java.sql.BatchUpdateException: Field 'XWD_ARCHIVE' doesn't have a default value

To fix this run the following SQL command on your database:

alter table xwikidoc modify column XWD_ARCHIVE mediumtext null;

Failure to log in

Check that you don't have some old cookies and try deleting them.

Get Connected