Установка и настройка XWiki - Windows+Oracle+Glassfish

Редактировал(а) Eugen Colesnicov 2012/08/29 13:06

Вступление

Данная инструкция содержит последовательное описание процесса первоначальной установки и оптимальной настройки XWiki Enterprise в варианте под Windows + GlassFish + OracleXE.

Исходным материалом послужили инструкции по инсталляции с сайта xwiki.org. Однако они являются более абстрактными и часто не учитывают специфики настроек под русские условия. Именно это и послужило стимулом к написанию данной инструкции.

Инструкция делалась "под себя" - для обеспечения простой возможности повторить быстрое развертывание системы (в т.ч. другими администраторами). Инструкция составлена не по принципу "если - то" (как например, составлены инструкции по инсталляции на xwiki.org), а более жестко - "делать так" - поэтому многие вещи указываются без подробных объяснений, почему именно так.

Имеется старая версия данной инструкции, которая начинала писаться еще когда XWiki была версией 2.0 или 2.1 и под Jetty, потом туда добавился GlassFish. Но все равно там осталось много не используемого сейчас. Новый вариант инструкции писался под версию XWiki - 2.7, 3.0.

Из нового варианта инструкции убрано много лишнего, в 1-ую очередь - все что касается Jetty. Изначально я пытался развертывать XWiki в варианте Windows + Jetty + OracleXE, но потом понял, что Jetty не годится для рабочей эксплуатации. Из принципиальных минусов - зависания сервиса и медленная скорость работы с аттачами.

Потом стал искать что-то вместо Jetty - и остановился на GlassFish. Понравилось - web-интерфейс настройки, то что не надо так сильно тюннить его как Jetty, ну и конечно скорость - файлы аттачились почти со скоростью, как если бы они копировались в локалке (jetty раз в 10 хуже)!

Новый вариант инструкции пока не полный. Еще будут добавляться разделы касаемо настройки LDAP, настройки соединения со сторонней базой Oracle и пр. Также планируется перевод на английский и румынский языки.

ПО, необходимое для загрузки

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

Установка базового набора приложений

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

OracleXE (если будем использовать локальную БД).
  • просто инсталлируем через Setup.
    В 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.
  • дальше все автоматически

Установка 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;
      Можно не назначать полные привилегии, а оставить по умолчанию. Полные привилегии могут потребоваться для режима multi-wiki (когда устанавливается XEM) (пока в точности не известно).
  • Копируем файл JDBC-драйвера (ojdbc5.jar) в \xwiki\WEB-INF\lib (подпапка в папке приложений GlassFish для домена1).
  • Редактируем файл настроек соединения XWiki с БД \xwiki\WEB-INF\hibernate.cfg:
    • Закомментировать строки не относящиеся к Oracle (general database).
    • Разкомментировать ту часть, где касается Oracle.
    • Указываем параметры коннекта к базе (SID и host).
      Если локально установлен 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.
  • В случае проблем с запуском OracleXE, проявляемых в виде ошибки ORA-12514 можно попробовать стартовать instance вручную. Для этого выполните следующие команды:
    ** sqlplus /nolog
    ** conn / as sysdba
    ** startup
Дополнительная настройка GlassFish и запуск как windows-сервис

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

  • Следует добавить дополнительную опцию для JVM -Xrs
    Данная настройка необходима, т.к. в противном случае, 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.
    Для выполнения этой команды на компьютере должен быть установлен Net Framework v.2. 
  • И запустить GlassFish через стандартную оснастку windows - управление сервисами.
    Помимо 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.
    - 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-файла следует залогиниться для продолжения работы.
    первоначально логиниться следует под пользователем Admin, а пароль admin.
Начальные настройки wiki
  • Для группы, куда входит юзер Admin (это группа XWikiAdminGroup) следует дать права на programming (в разделе Administration, Rights)
  • Также следует настроить XWiki на работу в MultiLanguage режиме.
    • Выберите раздел Administration, General
    • На открывшейся странице установите true для опции Multilingual
    • В поле languages установите перечень желаемых языков через запятую, например en,ru,ro

Установка и настройка сервера OpenOffice.org

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.

Дополнительный тюннинг XWiki

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

Настройка длинны имен прикрепленных файлов
  • Если требуется чтобы имена прикрепленных файлов показывались полностью (по умолчанию показывается только 1-ые 25 символов), следует в attachmentsinline.vm в папке templates добавить первую строку #set($maxnamelength = 256)
Настройка элементов в Print preview
  • Для того, чтобы в Print preview показывалось только собственно содержимое страницы и ничего более следует открыть файл print.css в папке с используемым скином и в раздел /* Hide unneeded stuff */, после строки #globallinks, #footerglobal, добавить строку:
#headerglobal, #navigationMenu, #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.
    В версии 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)
Отключение кэша аттачей

В некоторых случаях (например IE 7.0) происходит следующее. пользователь сделал attach файлу к странице XWiki, после чего другой пользователь также выполнил аттач этого файла к этой же странице XWiki (измененная версия файла). Сценарий вполне типичен для совместной работы с документами. У 1-го пользователя в этом случае, при попытке download-а загружается старая (1-ая) версия файла. Так происходит, вследствие того, что файл был запомнен в кэше браузера.

Следует отключить кэш браузера, поменяв в файле attachmentsinline.vm в папке templates строку (22 строка в оригинальном файле)
<span class="name"><a href="$doc.getAttachmentURL(${attach.filename}, 'download')" title="$msg.get('core.viewers.attachments.download')">$escapetool.xml($attach.filename)</a></span>

на строку
<span class="name"><a href="$doc.getAttachmentURL(${attach.filename}, 'download', "t=$util.getDate().getTime()")" title="$msg.get('core.viewers.attachments.download')">$escapetool.xml($attach.filename)</a></span> ## the 't=' part of the URL is a IE7 hack (see http://jira.xwiki.org/browse/XWIKI-106 or http://extensions.xwiki.org/xwiki/bin/view/Extension/Disable+browser+cache+for+attachments)

Источник: http://extensions.xwiki.org/xwiki/bin/view/Extension/Attachments+Macro

Дополнительный тюннинг SMTP

В некоторых случаях стандартных возможностей настройки SMTP-опций, описанных в документации может не хватать.

Дело в том, что отправка email-ов производиться от адреса "no-reply@<xwiki hostname>". Чтобы это исправить, следует в файле shareinline.vm (папка templates), в соответствующем месте, расскоментировать соответствующие строки (которые почему-то закомментированы) и тогда отправка будет производиться от email-а администратора, указанного в настройках XWiki.

Настройка соединения со сторонней базой Oracle

Сторонняя база данных может использоваться, например, как источник информации, для визуализации на страницах 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 (так настроили в нашем примере).

Дополнительные макросы и приложения

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

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

Обычно макросы и приложения для платформы 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 - добавляет панельку, с деревом разделов и страниц в них