Wiki source code of Installation
Version 69.1 by Guillaume Fenollar on 2012/01/25
Hide last authors
| author | version | line-number | content |
|---|---|---|---|
 |
48.1 | 1 | {{box cssClass="floatinginfobox" title="**Contents**"}} |
| 2 | {{toc/}} | ||
| 3 | {{/box}} | ||
| |
28.1 | 4 | |
 |
31.5 | 5 | XWiki is a Java-based wiki and runs on a Servlet Container such as Tomcat, Jetty, JBoss, WebLogic, WebSphere, etc. It also uses a relational database to store its content. It can run on almost any database (HSQL, MySQL, etc) but XWiki and the database need to be setup correctly. |
| |
13.1 | 6 | |
| |
1.96 | 7 | There are 2 solutions when installing XWiki: |
| |
36.1 | 8 | |
| |
28.1 | 9 | * Use the [[Standalone distribution>>xwiki:Main.Download]] which already packages a Servlet Container (Jetty) and a database (HSQL). This is the recommended option for first time XWiki users and for users who wish to quickly try out XWiki. |
| 10 | * Use the [[WAR distribution>>xwiki:Main.Download]] and configure both your container and your database to work with it. | ||
| |
31.5 | 11 | |
| |
28.1 | 12 | If you're instead upgrading an existing XWiki install check the [[Upgrade instructions>>#HUpgradinganXWikiInstallation]] below. |
| |
31.5 | 13 | |
| |
14.3 | 14 | Pick one of the trails in the outline on the right to get started. |
| |
31.5 | 15 | |
| |
28.1 | 16 | Once you've finished the installation check the other topics in the [[Admin Guide>>AdminGuide.WebHome]] for configuring and [[securing>>Security]] your wiki. |
| |
31.5 | 17 | |
| |
48.1 | 18 | {{info}} |
| |
52.4 | 19 | If you want to make manual installation or need to migrate an existing XWiki installation, check the [[Release Notes>>xwiki:ReleaseNotes.WebHome]]. |
| |
48.1 | 20 | {{/info}} |
| |
1.112 | 21 | |
| |
31.5 | 22 | = Tutorials = |
| |
1.95 | 23 | |
| |
14.3 | 24 | Tutorials are step by step procedures to install XWiki for a specific configuration. You can choose to follow one of them or follow the instructions in the sections below. |
| |
36.1 | 25 | |
| |
48.1 | 26 | {{warning}} |
| 27 | Tutorials external to the xwiki.org site have not been validated for correctness by the XWiki dev team and it's also possible that they are out of date. | ||
| 28 | {{/warning}} | ||
| |
14.3 | 29 | |
| |
28.1 | 30 | * [[XWiki On Windows (French)>>http://agoncalves.developpez.com/tutoriels/xwiki/creer-un-site-associatif/]] |
| 31 | * [[XWiki On Debian 4 (Etch) - Tomcat - PostgreSQL (or MySQL) (English)>>http://www.howtoforge.com/xwiki-tomcat-mysql-debian-etch]] | ||
| 32 | * [[XWiki On Debian 4 (Etch) - Tomcat - PostgreSQL (or MySQL) (German)>>http://www.howtoforge.de/howto/xwiki-on-debian-4-etch-tomcat-mysql]] | ||
| |
54.1 | 33 | * [[XWiki On Windows - GlassFish - Oracle (Russian)>>http://etvc.myxwiki.org/xwiki/bin/view/UNA/XWikiInstalation]] |
| |
57.2 | 34 | * [[XWiki on OpenSUSE - Tomcat - MySQL (English)>>http://geistreicher-papierkorb.blogspot.com/2011/03/setting-up-xwiki-on-opensuse-with-mysql.html]] |
| |
14.3 | 35 | |
| |
31.5 | 36 | = Prerequisites = |
| |
14.3 | 37 | |
 |
63.3 | 38 | * Java 6 or greater installed. |
| |
65.1 | 39 | * A minimum of 300MB of heap memory and 96MB of permGen. Recommended value are above 512MB for the heap and 128MB for the permGen (##-Xmx512m -XX:MaxPermSize=128m##)((( |
| 40 | {{warning}} | ||
| 41 | Note that storing attachments with the default (in database) storage mechanism is very memory intensive. See the [[administrators guide to attachments>>platform:AdminGuide.Attachments]] for more information about memory cost and the alternative filesystem based attachment store. | ||
| 42 | {{/warning}} | ||
| 43 | ))) | ||
| |
66.1 | 44 | * Check the [[Release Notes>>xwiki:ReleaseNotes.WebHome]] for the version you're installing to see what Browsers are supported for it. You can also check our [[general Browser support strategy>>dev:Community.BrowserSupportStrategy]]. |
 |
64.5 | 45 | |
| |
1.96 | 46 | |
 |
69.1 | 47 | = Installation Methods = |
| 48 | |||
| 49 | |||
| 50 | ==[[Using a standalone distribution >>AdminGuide.InstallationStandalone]]== | ||
| |
68.1 | 51 | {{warning}} Standalone distribution is not recommended in a production environment. Look at the two options below {{/warning}} |
| |
28.1 | 52 | |
| |
31.5 | 53 | |
| 54 | |||
| |
69.1 | 55 | == [[Using .war package (manual installation - usable for production)>>AdminGuide.InstallationWAR]] == |
| |
31.5 | 56 | |
| |
69.1 | 57 | |
| 58 | == [[Using .deb package (usable for production)>>AdminGuide.InstallationViaAPT]] == | ||
| 59 | |||
| 60 | |||
| |
31.5 | 61 | = Upgrading an XWiki Installation = |
| |
1.96 | 62 | |
| |
1.126 | 63 | There are different parts of XWiki that you may want to upgrade: |
| |
1.96 | 64 | |
| |
28.1 | 65 | * [[XWiki Core>>#HUpgradingXWikiCore]] |
| 66 | * [[Documents provided with the default XWiki XAR>>#HUpgradingwikidocuments]] | ||
| |
31.5 | 67 | |
| |
48.1 | 68 | {{info}} |
| |
64.1 | 69 | If you're upgrading a pre-1.0 XWiki installation refer to [[this guide>>UpgradeXWiki09Installation]]. |
| |
48.1 | 70 | {{/info}} |
| |
1.113 | 71 | |
| |
31.5 | 72 | == Upgrading XWiki Core == |
| |
9.7 | 73 | |
 |
58.1 | 74 | The general strategy is to [[download the WAR distribution>>xwiki:Main.Download]] and to replace your current installed WAR. Make sure you don't copy on top since this could leave some old files around which would make XWiki fail (like if old JARs are lying around in ##WEB-INF/lib##). Before replacing your current WAR, make sure you back it up and more specifically that you copy the ##hibernate.cfg.xml##, ##xwiki.cfg## and ##xwiki.properties## files which you'll need to copy in your newly installed WAR since they contain your XWiki configuration. Make sure you also copy any plugins you may have added or any template files you may have modified. |
| |
31.5 | 75 | |
| |
52.5 | 76 | Some additional operations may be required for upgrading and you must check the [[release notes>>xwiki:ReleaseNotes.WebHome]] for all the versions from the version you're upgrading from up to the new version you're installing. It's also possible that new features are available and that your ##xwiki.cfg## file needs to be modified. If this is the case then it'll be specified in the release notes. |
| |
1.113 | 77 | |
| |
37.1 | 78 | Note that the database schema is automatically upgraded when needed. All you need to do is to ensure your ##xwiki.cfg## file is correctly configured to perform the migration. Here's a relevant excerpt from the ##xwiki.cfg## file: |
| 79 | |||
| 80 | {{code language="none"}} | ||
| 81 | #-# Whether migrations are enabled or not. Should be enabled when upgrading, but for a better startup time it is better to | ||
| 82 | #-# disable them in production. | ||
| 83 | xwiki.store.migration=1 | ||
| 84 | |||
| 85 | #-# Whether to exit after migration. Useful when a server should handle migrations for a large database, without going | ||
| 86 | #-# live afterwards. | ||
| 87 | # xwiki.store.migration.exitAfterEnd=0 | ||
| 88 | |||
| 89 | #-# Indicate the list of databases to migrate. | ||
| 90 | #-# to upgrade all wikis database set xwiki.store.migration.databases=all | ||
| 91 | #-# to upgrade just some wikis databases set xwiki.store.migration.databases=xwiki,wiki1,wiki2 | ||
| 92 | #-# Note: the main wiki is always migrated whatever the configuration. | ||
| 93 | # xwiki.store.migration.databases= | ||
| 94 | {{/code}} | ||
| 95 | |||
| |
31.5 | 96 | == Upgrading wiki documents == |
| |
1.113 | 97 | |
| |
28.1 | 98 | You may want to upgrade to a newer version of the Default Wiki XAR in order to benefit from the latest changes. As mentioned above in the [["Installing the Default Wiki XAR" section>>#HInstallingtheDefaultWikiXAR]] you should be very careful and when doing the import make sure you selectively decide what pages you wish to import. More specifically the following pages should be imported with great care: |
| |
1.113 | 99 | |
| |
59.1 | 100 | * XWiki.XWikiPreferences: This page contains some 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. |
| 101 | * XWiki.RegistrationConfig: Contains Registration configuration of your wiki. | ||
| |
60.1 | 102 | * Invitation.InvitationConfig: Configuration for the [[Invitation Application>>extensions:Extension.Invitation Application]]. |
| |
1.96 | 103 | * XWiki.WebPreferences, Main.WebPreferences, and all other spaces WebPreferences pages: Same as XWiki.XWikiPreferences but at the level of a space. |
| 104 | * XWiki.XWikiAllGroup (list of registered users) and XWiki.AdminGroup (list of Admins): If you have existing users and import a new version of these pages, you'll find that your users do not belong to these groups anymore and thus may not be able to edit pages, log in, etc. You'll need to add them again to the right groups. | ||
| |
50.1 | 105 | * XWiki.Admin: This page contains the Admin user with the default password. If you import it you'll create a security hole. Thus it's very important not to import this page. |
| |
1.96 | 106 | * Any other page you have modified, such as Main.WebHome, a modified Panel, etc. |
| 107 | |||
| |
31.5 | 108 | === Let's clean it up === |
| |
1.133 | 109 | |
| |
64.1 | 110 | * 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-enterprise-web-3.1.war##, or avoid this step if you performed an export/import data migration (you already expanded it) |
| 111 | * Merge your old ##xwiki.cfg##, ##xwiki.properties## and ##hibernate.cfg.xml## files with the new versions found in 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 | ||
| 112 | * 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 in the container's administration interface) | ||
 |
37.2 | 113 | |
| |
64.1 | 114 | At this point all is set, you can experience your old wiki data over the new XWiki core! |
| |
1.126 | 115 | |
| |
31.5 | 116 | = Troubleshooting = |
| |
1.125 | 117 | |
| |
55.1 | 118 | You can verify some basic settings of your XWiki install (on Tomcat, MySQL) using the [[Admin Tools application>>extensions:Extension.AdminTools]]. |
