Installation (XWiki.org)

1 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.

4

5

There are 2 solutions when installing XWiki:

6

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.

8

* Use the [WAR distribution>Main.Download] and configure both your container and your database to work with it.

9

10

Pick one of the following trails:

11

#toc("" "" "")

12

13

Once you've finished the installation check the other topics in the [Admin Guide>AdminGuide.WebHome] for configuring and [securing>Security] your wiki.

14

15

#info("If you want to make manual installation or need to migrate an existing XWiki installation, check the [Release Notes>Main.ReleaseNotes].")

1.1 Prerequisites

You'll need to have Java 5 installed.

20

21

1.1 Installing the Standalone distribution

22

23

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

24

* A Windows exe. Simply execute it and follow the instructions

25

* 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.

26

* A zip version. Unzip it in any <tt>\[XWIKIHOME\]</tt> directory of your choice.

27

28

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.

29

30

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.

31

32

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

33

1.1 Installing the XWiki WAR manually

34

35

You'll need to perform 2 mandatory steps:

36

37

* Install and configure a Servlet Container

38

* Install and configure a relational database

39

40

#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].")

41

42

#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.")

43

44

1.1.1 Install and configure a Servlet Container

45

46

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.

47

48

* [Tomcat installation>AdminGuide.InstallationTomcat]

49

* [Jetty installation>AdminGuide.InstallationJetty]

50

* [GlassFish installation>AdminGuide.InstallationGlassFish]

51

* [WebSphere installation>AdminGuide.InstallationWebSphere]

52

* [JBoss Installation>AdminGuide.InstallationJBoss]

53

* [Oracle OC4J Installation>AdminGuide.InstallationOC4J]

54

55

You're now ready to install and configure your relational database.

56

57

1.1.1 Install and configure a Relational Database

58

59

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

60

61

The general strategy is the following:

62

63

* Install your favorite RDBMS

64

* Create a xwiki database

65

* Create a user with all privileges on that xwiki database

66

* Copy your RDBMS Java drivers to the XWiki webapp's <tt>WEB-INF/lib</tt> directory

67

* 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.

68

69

Install and configure the database you wish to use:

70

71

* [HSQL Installation>AdminGuide.InstallationHSQL]

72

* [MySQL Installation>AdminGuide.InstallationMySQL]

73

* [PostgreSQL Installation>AdminGuide.InstallationPostgreSQL]

74

* [Oracle Installation>AdminGuide.InstallationOracle]

75

* [DB2 Installation>AdminGuide.InstallationDB2]

76

* [Derby Installation>AdminGuide.InstallationDerby]

77

78

1.1.1 Concluding Step

79

80

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].

81

82

83

1.1 Installing the eXo Enterprise WebOS integration WAR

84

85

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

86

87

1.1.1 Install eXo WebOS

88

89

* Download the latest version of eXo Portal on http://forge.objectweb.org/projects/exoplatform/ (version 2.0-Alpha-2 or greater is required).

90

* Follow the eXo installation instructions located inside the Portal ZIP and try to login in the portal.

91

92

1.1.1 Install XWiki inside eXo

93

94

* Stop eXo Portal.

95

* Download the [latest XWiki eXo WAR>Main.Download]. You'll need version 1.0-beta-6 or above.

96

* Create a directory ~~exo-tomcat/webapps/xwiki~~.

97

* Unzip the WAR in ~~exo-tomcat/webapps/xwiki~~ and rename the exploded directory to "xwiki".

98

* 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).

99

* Remove all the eXo jars from ~~xwiki/WEB-INF/lib~~

100

* Configure XWiki's database as explained [above>#HInstallandconfigureaRelationalDatabase].

101

* Change in ~~xwiki.cfg~~: xwiki.exo=1 to xwiki.exo=0. TODO: Explain why this is required as it is very counter-intuitive!

102

* Restart eXo Portal.

103

* You can now either import XWiki as a Portlet inside the Portal as described below or access XWiki directly by using the usual URL.

104

* [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.

105

* Import the [default wiki XAR>Main.Download] or use your own XWiki database.

106

* Give the admin right to XWikiGuest

107

* To be continued...

108

109

1.1.1 Use XWiki inside the WebOS

110

111

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.

112

1.1 Installing the Default Wiki XAR

113

114

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>Code.PanelsApplication]

119

* Search

120

* Administration page (Access rights, Group and users management, etc)

121

* ... and much more

122

123

*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.*

124

125

To install the XAR, use the [Import/Export tool>AdminGuide.ImportExport].

126

127

#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.")

128

129

1.1.1 Upgrading an existing wiki

130

131

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 you should be very careful about that 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:

132

* 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.

133

* XWiki.WebPreferences, Main.WebPreferences, and all other spaces WebPreferences pages: Same as XWiki.XWikiPreferences but at the level of a space.

134

* 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.

135

* Any other page you have modified, such as Main.WebHome, a modified Panel, etc.

1.1 Troubleshooting

1.1.1 Field 'XWD_ARCHIVE' doesn't have a default value

140

141

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.

142

143

{code:none}

144

Wrapped Exception: Could not execute JDBC batch update

145

[...]

146

Wrapped Exception:

147

java.sql.BatchUpdateException: Field 'XWD_ARCHIVE' doesn't have a default value

148