XWiki step-by-step installation guide Windows+GlassFish+Oracle

Last modified by Eugen Colesnicov on 2011/02/26 18:18
Contents
Warning

translation to English not finished yet!

Introduction

This instruction contains the step-by-step description of XWiki Enterprise initial installation and optimal tuning under Windows+GlassFish+OracleXE. 

I used as my starting point the installation instructions from xwiki.org site. However they are more abstract and, frequently, do not take into accout the pecularitites of installation in Russian (and other non-English) conditions.

I wrote this instructions primariuly for my personal use: to be able to repeat the installation quickly (and, possibly, by other administrators). The instruction does not describe "if -  then" like the instructions from xwiki.org but more decisevely "to do this and that". That's why I omit long reasoning.

There is and old (Russian) version ot this instruction. That old version was initiated for XWiki  version 2.0 or 2.1 under Jetty, and later I added Glassfish. Many recommendations from there are now inapplicable. The new (current) variant of the Instruction supposes XWiki 2.7 and 3.0. 

I deleted from the old variant many things, mainly those concerning Jetty. From the very beginning I tried to install XWiki under Windows+Jetty+OracleXE, but later I realized that Jetty is not a proper tool for industrial use. The main shortcomings are the service hang and slow work with attachments.  

Searching for replacement for Jetty, I selected Glassfish. I was positively impressed by the Web interface for the configuration, relatively small tuning, and the speed. The file can be attached almost as quick as local copying (Jetty is ten times slower).

This new variant of the Instruction is not finished. I will add sections on LDAP tuning, on configuring the connection with an external Oracle database, etc. I plan also translations in English and Romanian. 

Downloading the necessary software

  • XWiki Enterprise:
    • берем war-файл - собственно само приложение,
    • и также xar-файл - содержит начальные настройки и базовые страницы wiki.
  • Для работы приложения "импорт офисных документов" требуется:
  • В случае, если СУБД Oracle будет устанавливаться локально, то также будет необходимо Oracle Database Express Edition.
    InformationСледует закачивать т.н. Universal-версию OracleXE для обеспечения поддержки UTF-8 (мультиязычности) на уровне БД.

Installing the base application set

Оглавление раздела:

OracleXE (если будем использовать локальную БД).
  • просто инсталлируем через Setup.
    InformationВ OracleXE, при инсталляции, отсутствуют возможности настройки языковых параметров БД. А для XWiki, для обеспечения мультиязычности, нужно чтобы они были настроены в UTF8 (например, NLS_CHARACTERSET должен быть AL32UTF8). Для этого необходимо чтобы OracleXE устанавливалась на версию Windows, где изначально все языковые настройки были сделаны в English. При этом недостаточно, чтобы эти настройки были настроены перед установкой OracleXE - они должны быть изначально такими именно при инсталляции Windows. Попытки настройки "по ходу дела" не дали результата.
Java Development Kit (JDK)
  • Запускаем installer
  • JavaDB можно отключить
  • дальше все автоматически
GlassFish application server
  • запускаем installer 
  • должен найти установленную версию JDK
  • дополнительный компонент Update Tool выбираем
  • меняем порт по умолчанию, т.к. он пересекается с портом web-консоли Oracle (8080). Ставим, например - 8008.
  • дальше все автоматически

Installing XWiki Enterprise

Оглавление раздела:

Установка XWiki в GlassFish
  • запускаем GlassFish командой C:\glassfishv3\bin\asadmin start-domain (останавливать командой stop-domain).
  • В браузере набираем http://localhost:4848 и заходим в админ-консоль GlassFIsh (имя и пароль задаются при инсталляции, например, как в XWiki - Admin/admin).
  • Выбираем в дереве слева Applications а в правой части - Deploy.
  • Открываем с диска war-файл XWiki.
  • Устанавливаем: Type = Web Application, Context Root = xwiki, Application name = xwiki.
  • Остальные параметры можно не менять и жмем OK.
Настройка соединения с Oracle

 

  • создаем схему для XWiki:
    • подключаемся к Oracle dba-юзером
    • создаем схему create user xwiki identified by xwiki;
    • назначаем привелегии grant all privileges to xwiki;
      InformationМожно не назначать полные привилегии, а оставить по умолчанию. Полные привилегии могут потребоваться для режима multi-wiki (когда устанавливается XEM) (пока в точности не известно).
  • Копируем файл JDBC-драйвера (ojdbc5.jar) в \xwiki\WEB-INF\lib (подпапка в папке приложений GlassFish для домена1).
  • Редактируем файл настроек соединения XWiki с БД \xwiki\WEB-INF\hibernate.cfg:
    • Закомментировать строки не относящиеся к Oracle (general database).
    • Разкомментировать ту часть, где касается Oracle.
    • Указываем параметры коннекта к базе (SID и host).
      InformationЕсли локально установлен OracleXE можно ничего не менять - а только разкомментировать и закомментировать соответствующие места.
  • Возможно еще следует включить UTF-8 для Oracle (точно не известно насколько это нужно или нет)
    • Открываем файл настроек соединения XWiki с БД \xwiki\WEB-INF\hibernate.cfg
    • перед строкой <mapping resource="xwiki.oracle.hbm.xml"/> добавляем 2 строки:
      <property name="connection.useUnicode">true</property>
      <property name="connection.characterEncoding">UTF-8</property>
  • Перезапускаем GlassFish командами stop-domain и start-domain.
Дополнительная настройка GlassFish и запуск как windows-сервис

Дополнительная настройка GlassFish

  • Следует добавить дополнительную опцию для JVM -Xrs
    InformationДанная настройка необходима, т.к. в противном случае, GlassFish windows-сервис будет завершаться всегда при logout пользователя на сервере.
    • Заходим в админ-консоль GlassFish
    • В дереве слева выбираем Configuration, JVM Settings
    • На открывшейся страничке выбираем закладку вверху JVM Options
    • Откроется страница с параметрами JVM. Нажимаем кнопку вверху списка параметров Add JVM Options
    • В добавленном поле пишем -Xrs и нажимаем на Save
  • Еще одна необходимая вещь - настройка UTF-8 в GlassFish
    • Также из admin-консоли, в дереве слева выбираем Enterprise Server
    • На открывшейся странице выбираем закладку вверху Advanced, a потом подзакладку Domain attributes
    • В поле Locale пишем en_US.UTF-8

Установка GlassFish как windows-сервиса

  • Останавливаем GlassFish командой stop-domain
  • Затем установить GlassFish как windows-сервис командой asadmin create-service.
    InformationДля выполнения этой команды на компьютере должен быть установлен Net Framework v.2. 
  • И запустить GlassFish через стандартную оснастку windows - управление сервисами.
    InformationПомимо windows-оснастки, управление сервисом можно осуществлять из командной строки, следующими командами:
    Start Command:  C:\glassfishv3\glassfish\domains\domain1\bin\domain1Service.exe  start
    Stop Command:   C:\glassfishv3\glassfish\domains\domain1\bin\domain1Service.exe  stop
    Uninstall Command:  C:\glassfishv3\glassfish\domains\domain1\bin\domain1Service.exe  uninstall
    Install Command:  C:\glassfishv3\glassfish\domains\domain1\bin\domain1Service.exe  install
  • Пробуем открыть xwiki: http://localhost:8008/xwiki.  Если все нормально, то откроется начальная страница xwiki.
    Information- GlassFish в реальности запускается не сразу после старта windows-сервиса - следует подождать еще 2-5 минут.
    - Если вместо начальной страницы XWiki открылась страница с сообщениями об ошибках - то следует устранить ошибку и обязательно перезапустить GlassFish.
    - Из типовых проблем можно выделить: а) забыли jdbc-драйвер Oracle; b) неправильно отредактировали файл настроек соединения с БД; c) не так как нужно для XWiki настроены языковые параметры (NLS) Oracle (см. комменты по этому поводу выше).     
Импорт xar-файла с базовыми страницами XWiki
  • На открывшейся после установки XWiki Enterprise странице, вверху, выбираем меню Wiki, а затем Administration. 
  • Откроется страница Import, с возможностью выбора файла с диска. Выбираем с диска xar-файл от xwiki и нажимаем Upload.
  • Ваш xar-пакет с начальными страницами XWiki появиться в списке Available packages. Кликаем на него.
  • После клика, через некоторое время, в правой части будет открыт список страниц, содержащихся внутри xar-пакета, а внизу него кнопка Import. Жмем на нее.
  • После завершения импорта начального xar-файла следует залогиниться для продолжения работы.
    Informationпервоначально логиниться следует под пользователем Admin, а пароль admin.
Начальные настройки wiki
  • Для группы, куда входит юзер Admin (это группа XWikiAdminGroup) следует дать права на programming (в разделе Administration, Rights)
  • Также следует настроить XWiki на работу в MultiLanguage режиме.
    • Выберите раздел Administration, General
    • На открывшейся странице установите true для опции Multilingual
    • В поле languages установите перечень желаемых языков через запятую, например en,ru,ro

Installing and tuning OpenOffice.org server

Warning

XWiki поддерживает работу с версиями OpenOffice.org 3.0x, 3.1x, 3.2x. Версия 3.3 на текущий момент не поддерживается.

Установка OpenOffice.org и настройка на работу с XWiki возможна 2 способами:

  • internal - XWiki непосредственно работает с установленной версией OpenOffice.org
  • external - OpenOffice.org запускается как windows-сервис, а XWiki работает уже с ним

Каждый из этих способов следует рассматривать отдельно. Нами будет приведен internal-вариант, как более простой.

Установка OpenOffice.org и настройка для XWiki в варианте internal
  • Запускаем инсталлятор, отвечаем на вопросы, путь по умолчанию лучше не менять.
  • После завершения запускаем Openoffice хотя бы один раз, чтобы выполнился мастер регистрации.
  • Заходим в опции OpenOffice.org, раздел Open/Save, дальше HTML Compatibility
  • Устанавливаем параметр Character set в UTF-8 и сохраняем
  • Открываем файл \xwiki\WEB-INF\xwiki.properties, разкоментируем и меняем в нем следующие переменные:
    • переменную openoffice.autoStart=true
    • а также openoffice.profilePath=C:/Documents and Settings/Administrator/Application Data/OpenOffice.org/3 - это путь куда пишутся настройки для текущего пользователя - именно они и будут использоваться в дальнейшем.
  • Теперь надо перезапустить GlassFish и в XWiki, Administration открыть раздел OpenOffice Server. Если все нормально - в поле server state будет стоять Connected.

Additional XWiki tuning

Оглавление раздела:

Настройка длинны имен прикрепленных файлов
  • Если требуется чтобы имена прикрепленных файлов показывались полностью (по умолчанию показывается только 1-ые 25 символов), следует в attachmentsinline.vm в папке templates добавить первую строку #set($maxnamelength = 256)
Настройка элементов в Print preview
  • Для того, чтобы в Print preview показывалось только собственно содержимое страницы и ничего более следует открыть файл print.css в папке с используемым скином и в раздел /* Hide unneeded stuff */, после строки #globallinks, #footerglobal, добавить строку:
#headerglobal, #hierarchy, #document-title, #document-info, #xdocFooter, #docextrapanes,
Настройка иконок в wysiwyg-редакторе
  • Для того, чтобы вывести все иконки на тулбар в wysiwyg-редакторе необходимо:
    • открываем templates\macros.vm
    • находим строку plugins: '$xwiki.getXWikiPreference("wysiwyg.plugins", - в этой строке указываются те плагины, которые будут подгружаться, но сам вид тулбаров настраивается ниже.
    • в найденную строку добавляем через пробелы (место не имеет значения) - color font justify - только этих трех плагинов нету в варианте по умолчанию.
    • Теперь в строке toolbar: '$xwiki.getXWikiPreference("wysiwyg.toolbar" добавляем сами иконки. Вот полный вариант:
bold italic underline strikethrough teletype | subscript superscript | justifyleft justifycenter justifyright justifyfull | unorderedlist orderedlist |
outdent indent | undo redo | format | fontname fontsize forecolor backcolor | hr removeformat symbol | paste

- символ "|" означает строчный разделитель, символ "/" - разбивает тулбар на несколько строк.

Настройка сортировки прикрепленных файлов
  • Для того, чтобы обеспечить сортировку прикрепленных файлов по дате изменения, следует в файле attachmentsinline.vm в папке templates после строки #set($attachments = $doc.attachmentList) (и соответственно перед <div id="attachmentscontent" class="xwikiintracontent">) добавить:
#set($attachmentsMap = $util.hashMap)
#foreach($a in $attachments)
  #if(!$attachmentsMap.containsKey($a.date))
    #set($discard = $attachmentsMap.put($a.date, $util.arrayList))
  #end
  #set($discard = $attachmentsMap.get($a.date).add($a))
#end
#set($dates = $util.arrayList)
#foreach($date in $attachmentsMap.keySet())
  #set($discard = $dates.add($date))
#end
#set($dates = $util.sort($dates))
#set($dates = $util.reverseList($dates))
#set($attachments = $util.arrayList)
#foreach($date in $dates)
  #set($discard = $attachments.addAll($attachmentsMap.get($date)))
#end 
Настройка совместимости в IE для форматов MSOffice2007 и OpenOffice.org
  • Аттачи-файлы MS Office 2007 и OpenOffice в IE сохраняются как zip-архивы (с расширением zip). Проблема имеет место только в IE. Решение такое - в файл web.xml, который лежит в папке WEB-INF приложения добавить в соответствующем месте (поискать по mime) содержимое из приложенного текстового файла. В XWiki последних версий в файле web.xml уже вставлены MIME-типы под некоторые форматы файлов, но далеко не под все.
  • Проблемы с импортом xar-файлов, проявляющиеся на версиях XWiki 2.3, 2.4 на Glassfish v.3 (выдается ошибка: number 0 in 11: Uncaught exception Wrapped Exception: org.apache.commons.codec.binary.Base64), связаны с тем, что Glassfish и XWiki имеют разные версии одной и той же библиотеки. Для решения проблемы следует скопировать файл commons-codec-1.4.jar из \xwiki\WEB-INF\lib в папку \glassfishv3\glassfish\modules а оттуда удалить commons-codec-repackaged.jar.
    InformationВ версии XWiki 3.0 данной проблемы уже не возникло.
Настройка максимального размера прикрепляемых файлов
  • Ограничение в 10MB для upload-а. В XWiki имеется ограничение на upload. Для его регулирования следует:
    • edit the XWiki.XWikiPreferences class and add a NumberProperty field of type long, named upload_maxsize; if the field already exists, you can skip this step
    • edit the XWiki.XWikiPreferences object and specify the desired maximum attachment size (in bytes)

Connecting to the external Oracle datasource

Information

Сторонняя база данных может использоваться, например, как источник информации, для визуализации на страницах XWiki (при необходимости можно выполнять и update данных).

Настройка GlassFish
  • Необходимо скопировать ojdc-драйвер Oracle (тот же файл, что и при инсталляции XWiki - ojdbc5.jar) в папку \glassfishv3\glassfish\domains\domain1\lib\ext, а затем перезапустить GlassFish.
  • Далее открываем admin-консоль GlassFish (http://server:4848##) и выбираем в дерева справа Resources, затем JDBC, затем Connection Pools и на открывшейся странице нажимаем New.
  • Будет отрыт интерфейс добавления нового Connection Pool, где: в поле Name вводим OraclePool, в поле Resource Type выбираем javax.sql.CoonectionPoolDataSource, а в поле Database Vendor выбираем Oracle и нажимаем Next.
  • На следующем шаге настройки, следует включить Ping (даст возможность потом протестировать соединение), а в разделе Additional Properties необходимо заполнить следующие параметры: user и password - пишется имя схемы Oracle и пароль к ней, а в поле URL - пишется стринг соединения в формате jdbc (точно также он записывался и в конфигурационном файле, где настраивали базу данных для XWiki). Пример - jdbc:oracle:thin:@localhost:1521:XE. После заполнения этих полей нажимаем Finish.
  • Connection Pool создан и мы можем протестировать соединение. В дереве слева кликаем на OraclePool - и на открывшейся странице кликаем на кнопку Ping - должно появиться сообщение Ping Succeeded.
  • Если тест успешный, то слева в дереве кликаем на JDBC Resources и на открывшейся странице нажимаем New. В поле JNDI Name вводим jdbc/ora1, а в Pool Name выбираем OraclePool и нажимаем Ok. На этом конфигурирование GlassFish закончено.
Настройка XWiki

Далее необходимо выполнить настройку XWiki.

  • Необходимо добавить ссылку на созданное соединение в файл \xwiki\WEB-INF\web.xml. Почти в самом конце файла уже есть шаблон блока, который следует разкомментировать и вписать туда имя нашего JDBC-соединения:
    <resource-ref>
     <description>DB Connection</description>
     <res-ref-name>jdbc/ora1</res-ref-name>
     <res-type>javax.sql.DataSource</res-type>
     <res-auth>Container</res-auth>
    </resource-ref>
  • Следующим шагом следует добавить специальный плагин, который повышает удобство работы с внешними данными. Домашний сайт - http://xwikisql.gradsoft.ua/docs/XWikiSqlPluginGuide.html. Скачиваем плагин и копируем его в папку \xwiki\WEB-INF\lib.
  • Затем следует в файле \xwiki\WEB-INF\xwiki.cfg найти раздел с перечислением плагинов (по ключевому слову xwiki.plugins) и добавить туда строку                     ua.gradsoft.xwikisql.SqlPlugin.
  • Для завершения настройки следует перезапустить GlassFish. Подробная информация по использованию плагина для извлечения информации из сторонней базы данных и визуализации на страницах XWiki на сайте плагина - http://xwikisql.gradsoft.ua/docs/XWikiSqlPluginGuide.html. Обращение к источнику данных по имени - jdbc/ora1 (так настроили в нашем примере).

Additional applications and macros

Содержит краткий список дополнительных полезных макросов и приложений, не входящих в основную поставку XWiki Enterprise и используемых автором данного руководства. Источник большинства из них - http://extensions.xwiki.org. Устанавливать их необходимо после установки и настройки XWiki Enterprise.

Оглавление раздела:

Information

Обычно макросы и приложения для платформы XWiki реализуются в виде xar-файлов, которые следует импортировать в XWiki стандартным образом, через раздел Administration, а потом Import - для таких доп. компонентов специального описания процесса установки приводиться не будет. Также, некоторые из добавок имеют доп. компоненты или же им требуется доп. настройка - в этом случае в описании также будут приведены краткие инструкции по установке.

Admin Tools - содержит список различных добавок для администраторов: статистика, экспорт и пр.
  • http://extensions.xwiki.org/xwiki/bin/view/Extension/AdminTools
  • Установка - стандартно
  • Домашняя страница Admin.Tools
  • Ставиться в раздел Admin, для которого отсутствует WebHome. Имеет смысл создать WebHome и вынести на него другие полезные функции, связанные с администрированием (удаление разделов, копирование разделов и пр.)
LDAP Tools - содержит утилиты для работы с LDAP: а) настройка взаимодействия, job для синхронизации
  • http://extensions.xwiki.org/xwiki/bin/view/Extension/LDAP+Tools
  • Установка стандартно, но после установки обязательно открыть XWiki.AdminLdapSyncSheet или XWiki.AdminLdapSheet (не помню точно) для того чтобы в Administration добавился соответствующий раздел
  • Управлять - через Administration, где после установки будет специальный раздел LDAP-tools
PlantUML Macro - макрос для построения UML-диаграмм.
  • Установка:
    • Качаем Grapviz отсуда http://www.graphviz.org/Download_windows.php и устанавливаем на сервере (нужно для некоторых типов диаграмм)
    • Добавляем в переменные окружения Windows переменную GRAPHVIZ_DOT со значением C:\Program Files\Graphviz2.26.3\bin\dot.exe (путь к файлу dot.exe)
    • Также пришлось перезагрузить сервер (возможно - будет достаточно перезапустить GlassFish) а то в дальнейшем эта переменная окружения была не видна.
    • Дальше стандартно устанавливаем xar-файл.
    • на странице Macros.plantUMLMacro можно убедиться хорошо ли все поставилось.
  • Кстати, есть даже вариант PlantUML для MS Word! (в виде word-макроса).
  • Еще кстати, есть другой макрос для рисования UML-диаграмм в XWiki, UML Macro, однако он имеет ряд недостатков: а) работает только при наличии online-соединения с сайтом http://www.yuml.me/ b) варианты диаграмм ограничены (только самые основные)
Tabs Macro - макрос для визуализации на странице табов
  • Использование:
    {{tabs idsToLabels='tabId11=My xwiki-wide tabs, tabId12=My working tabs :)' /}}
    (%id="tabId11"%)((({{box cssClass="tabId11div"}}
    First tab!
    {{/box}}
    I can post any content here
    )))

    (%id="tabId12"%)((({{box cssClass="tabId12div"}}
    Second tab!
    {{/box}}
    And here too
    )))
LiveTable Macro - макрос для удобного построения таблиц по технологии LiveTable
  • Использование:
    {{livetable classname="XWiki.XWikiUsers" fields="first_name,last_name,doc.name,address" tags="false"
      selectedColumn="first_name" defaultOrder="desc" rowCount="11" maxPages="9" resultPage="" /}}
  • В составе макроса также имеется страничка Macros.LiveTableScriptGenerator - которая позволяет сгенерировать полный скрипт построения LiveTable - что удобно для использования в собственных разработках
Calc Macro - макрос для простых подсчетов в таблицах XWiki
  • http://extensions.xwiki.org/xwiki/bin/view/Extension/Calc+Macro
  • Установка - стандартно
  • фактически состоит из 3-х макросов: calc macro, sum macro, summary macro. Синтаксис каждого из макросов - на соответствующей странице в разделе Macros.
Todo Macro - макрос для добавления прямо на страницы списков дел
Spoiler Macro - макрос для добавления на страницу скрытых элементов
Lightbox Macro - макрос создает презентацию из картинок
MBox, MCode, MNote Macros - макросы создающие специальные box-ы с красивым видом
  • http://asiri.rathnayake.org/xwiki/
  • Установка - стандартно.
  • Домашние страницы Macro.MBox, Macro.MNote, Macro.MCode
  • Использование MBox:
    {{mbox title="A Title" subTitle="An Optional **Sub-Title**"}}
    Any **xwiki** content.
    {{/mbox}}
Copy Space Snippet - данный код позволяет скопировать Раздел в другой Раздел
Delete Space Snippet - данный код позволяет выполнить удаление разделов
SpaceExplorer Panel Application - добавляет панельку, с деревом разделов и страниц в них