Study & DevО программировании и не только

Создание wiki-сайта вместе с Confluence

Компания atlassian.com давно зарекомендовала себя как ведущий разработчик различных программных продуктов ориентированных на помощь в управлении проектами разработки ПО и поддержку связанных с ними процессов. Так, из под крыла atlasian вышла JIRA - инструмент управления проектом и составляющими его заданиями. Для JIRA есть множество плагинов, поддерживающих различные аспекты управления проектами. Так одно из самых мощных дополнений для JIRA – это GreenHopper (продается как отдельный продукт) давно перерос рамки “простого плагина” и превратился в мощный инструмент для управления заданиями и их жизненным циклом. С помощью FishEye – инструмента для управления хранилищем версий документов (cvs, svn), вы сможете просматривать код, контролировать историю ревизий, а также получать отчеты о состоянии репозитория и активности разработчиков. Для анализа качества покрытия кода тестами используется Clover. Сервер Bamboo служит для управления сборками проекта.

Но, тема сегодняшней статьи будет носить не столь специальный характер и может быть применима не только в сфере разработке ПО, но и любой другой, где возникает задача коллективной работы над документами (создание техдокументации, правка статей). Confluence считается одной из самых известных и совершенных в мире wiki-систем. По своему определению wiki – это веб-приложение или сайт, информация на котором может быть создана или отредактирована множеством участников. Каждая из правок, внесенных в страницы, сохраняется в архиве. Так что впоследствии можно просмотреть эту историю правок, чтобы узнать то, кто внес то или иное изменение и в случае необходимости отменить ошибочную правку. Таким образом, вики-системы идеально подходят для создания документации, обмена знаниями, ведения обсуждений и т.д.

Сначала я кратко опишу процедуру установки и настройки confluence. Confluence далеко не единственная известная wiki-система, так есть mediawiki, tikiwiki, wackowiki и т.д. Большая часть функциональности confluence пересекается с возможностями той же mediawiki, но компания atlasian сделала ставку на тесную интеграцию всех выпускаемых ею продуктов (JIRA, confluence, crowd, bamboo, clover) в единое отлаженное рабочее пространство, т.е. confluence может обмениваться информацией с другими приложениями. Поскольку confluence это веб-приложение, написанное на java, то у нее требования к хостингу более серьезные, чем у вики-проектов, написанных на php (mediawiki). Немного утешает то, что поддержка выполнения java-приложений сегодня входит во многие “нижние” тарифные планы на хостинг. Хотя, откровенно говоря, здесь все очень не гладко, т.к. для работы confluence требуется большой объем оперативной памяти. Например, я выделил для своей инсталляции java почти гигабайт оперативной памяти, и не стоит надеяться на то, что такой объем ресурсов будет доступным для дешевого виртуального хостинга за 50 у.е. в год, а значит вам, наверняка, придется покупать выделенный сервер. С другой стороны, если вы хотите развернуть confluence на сервере в локальной сети организации, то вопрос нехватки ресурсов перед вами не встанет. Как вариант компания atlasian предлагает возможность размещения своих продуктов той же jira или confluence на своем сервере в internet (модель подписки) и этот вариант может быть полезен, если вы не хотите заниматься вопросами установки и настройки confluence на своем сервере. Также следует знать то, что confluence является платным продуктом и довольно дорогим. Но к счастью, существует несколько возможных видов лицензий, которые позволят пользоваться confluence или бесплатно или “за смешные деньги”. Во-первых, компания atlasian предлагает многие из своих продуктов для бесплатного использования некоммерческим организациям, либо тем, кто занимается созданием свободного П.О. Для получения такой лицензии вам нужно будет оформить соответствующую заявку на сайте atlasian, указав реальные данные о своей организации или сайте. После чего с вами свяжутся и, возможно, удовлетворят вашу просьбу. Другим вариантом является покупка “Starter 10” лицензии стоимостью ровно в 10 у.е. И которая предполагает, что купленная редакция confluence будет использоваться не более чем 10 пользователями.

Теперь давайте пройдемся кратко по основным шагам настройки confluence и ее использованию. Начнем с того, что с сайта http://www.atlassian.com/software/confluence/ConfluenceDownloadCenter.jspa вы скачаете дистрибутив confluence в одном из двух видов. Либо архив с настроенным сервером tomcat и интегрированным в него confluence. Либо все тот же набор tomcat + confluence, но оформленный в виде windows-инсталлятора. В процессе установки которого можно настроить номер порта, который будет обслуживать tomcat, а также то, будет ли сервер запускаться автоматически как служба windows (этот вариант предпочтителен, если вы не знакомы с java). В моем случае у меня уже был в локальной сети java сервер (oracle weblogic), и я хотел просто добавить confluence к списку других веб-приложений. Поэтому сначала скачал zip-архив и распаковал из него только папку confluence. Фактически эта папка представляет собой “все, что нужно” и может быть инсталлирована как веб-приложение в любой другой java веб-сервер. Например, для tomcat и jetty эту папку нужно скопировать в подкаталог webapps. Перед тем как запустить tomcat веб-сервер, следует отредактировать конфигурационный файл “confluence/WEB-INF/classes/confluence-init.properties” и указать в нем значением переменной “confluence.home” полный путь к каталогу, где confluence будет хранить свою базу данных и временные файлы. После этого можно уже запускать tomcat. Когда вы откроете адрес http://localhost:8080/confluence, то увидите страницу-приглашение, где следует пройти через пять шагов мастера установки. Первым делом вам потребуется ввести в текстовое поле код купленной подписки на confluence (здесь же вы можете зайти на сайт atlasian.com с тем, чтобы получить пробную лицензию на 30 дней). Вторым шагом установки является выбор базы данных, в которой confluence будет хранить всю информацию. Здесь у вас есть два возможных пути: во-первых, можно настроить confluence на использование встроенной СУБД HSQL. Нельзя сказать, что HSQL плохая СУБД (у меня есть опыт ее использования в довольно серьезных java-проектах и без каких-либо нареканий), но, все же, предпочтительнее хранить информацию во внешней СУБД. Confluence поддерживает Postgres, Mysql, Oracle, Ms sql server, db2, равно как и любую другую базу данных, для которой есть jdbc-драйвера. Третий шаг мастера позволяет указать то, откуда будет взято первоначальное информационное наполнение сайта. Так, если вы не знакомы с confluence и хотите просто “поиграть” с ней, то можно выбрать команду “Example Site”, которая создаст сайт с демонстрационным набором статей. Здесь же стоит упомянуть, что atlasian предлагает продукт Universal Wiki Converter, предназначенный для переноса в среду confluence информации из других wiki-систем (той же mediawiki). Второй вариант выбора “Restore From Backup” пригодится, если у вас раньше была установлена confluence более ранней версии. Так вы сможете выполнить перенос старой информации на более свежую версию confluence. Оставшийся третий вариант “Empty Site” служит для создания “пустой инсталляции” confluence, информацию в которую вы будете заносить самостоятельно и “с нуля”. Я выбираю вариант “Example Site” и попадаю на четвертую страницу “Setup System Administrator ” мастера настройки confluence, где мне нужно указать имя и пароль для администратора confluence. В терминологии confluence это так называемый системный администратор, в то время как есть еще и администраторы “пространств”, но об этом позже. Пройдя все шаги мастера установки, мы получим полностью готовую к работе среду confluence (см. рис. 1).



Здесь же на первой странице (под заголовком “ Welcome to your Confluence wiki”) вы можете увидеть меню перехода к обучающим материалам по confluence.

Перед тем как начать “экспериментировать” с confluence, давайте рассмотрим основные возможности панели управления. Дело в том, что в конфигурации по-умолчанию confluence не сможет эффективно работать с большим количеством статей, а еще нам нужно разобраться с правами доступа иначе наполняемые нами материалы, просто, никто не сможет просмотреть. Для того, чтобы попасть в панель управления нужно сразу после входа от имени администратора в confluence выбрать меню “Browse -> Confluence Admin” (или же вы можете ввести в адресной строке браузера следующий адрес http://localhost:8080/confluence/admin/). Настроек в панели управления не очень много, да и, по правде говоря, все по-умолчанию работает как нужно, так что нам придется внести совсем небольшие корректировки. Во-первых, заходим в раздел “General Configuration”, где нужно изменить значение для конфигурационной переменной “Server Base Url:” с “http://localhost:8080/confluence” на внешний ip или dns-адрес, например “http://myserver.com:8080/confluence”. Затем вам нужно зайти в раздел “Daily Backup Admin”, с тем, чтобы отключить там функцию “Perform daily backups”. Дело в том, что по-умолчанию confluence настроена делать ежедневно в два часа ночи резервную копию всех статей и загруженных файлов (изображений и других видов attachment-ов). Делается эта копия в виде архива с гигантским xml-файлом и занимает процедура копирования достаточно времени. Создатели confluence рекомендуют отключать встроенную в confluence систему бэкапов как только ваш размер confluence перейдет хотя бы пару сотен статей. А вместо него использовать стандартные для используемой вами внешней СУБД инструменты резервного копирования, а что касается файлов с картинками, то для их резервирования достаточно архивировать и сохранять в безопасное место все содержимое каталога, определенного вами в файле “confluence/WEB-INF/classes/confluence-init.properties”. Следующим шагом настройки confluence будет раздел “Mail Servers”. Дело в том, что confluence содержит развитые средства оповещения системного администратора (равно как и других заинтересованных пользователях) об изменениях, происходящих с confluence, например, о добавлении и редактировании статей. Одним словом, после того как вы нажали кнопку “Add a new SMTP mail server”, то вы попадаете на страницу регистрации почтового сервера, где указываете имя сервера и учетные данные того пользователя, от имени которого confluence будет рассылать письма. К слову, администратор всегда может просмотреть список писем, которые попали в очередь для рассылки, но еще не успели быть отправлены (раздел “Mail Queue”). Разработчики confluence активно использовали для формирования внешнего вида, как электронных писем, так и внешнего вида самих html-страничек известных (в java-мире) движок шаблонов velocity. К примеру, зайдите в каталог “webapps/confluence” и там вы увидите множество файлов с расширением “.vm” – это и есть шаблоны velocity. Таким образом, вы можете изменить внешний вид confluence-сайта практически до не узнаваемости. Надо сказать, что работать с настройками внешнего вида confluence, можно не только “хакерскими” правками файлов-шаблонов, но и вполне “цивилизованно” через панель управления. Во-первых, обратите внимание на раздел “Global Templates”, где вы можете определить новые шаблоны страниц. Впоследствии, при заполнении confluence информацией и добавлении новой страницы вы можете выбрать один из созданных вами шаблонов страниц. Упрощает создание страниц и функция “User Macros”. В той или иной форме подобный механизм часто встречается в других wiki-система и заключается в том, что можно определить список “подстановок”. Например, поставить в соответствии кодовой фразе “MACRO_ABOUT_COMPANY” вставку определенного html-текста. Для глобального изменения внешнего вида confluence служит набор функций, объединенных под заголовком “Look and Feel”. Так страница “Themes” панели управления позволяет выбрать тему оформления confluence, и хотя идущие в стандартной поставке три варианта оформления не впечатляют (отличаются, по сути, только размещением меню). Но механизм настройки внешнего вида есть; и вы можете либо создать собственную схему, либо загрузить какой-то из понравившихся вам вариантов из internet с сайта atlasian. Следующий раздел “Colour Scheme” служит для настройки цветов используемых для оформления различных элементов confluence страниц (меню, ссылки, линии разделители и т.д.). Раздел “Site Layouts” представляет возможности по редактированию тех самых velocity шаблонов, из которых и выполняется сборка страниц (равно как и email-шаблонов). Для небольших правок, например, изменения стилевого оформления текста, служит функция “Stylesheet”, там вы сможете определить новые css-стили. Раздел “Global Logo” позволяет загрузить в confluence файл с картинкой, которая будет играть роль логотипа сайта, и будет везде показываться взамен стандартной картинки, размещаемой в самом верху страниц сайта. Раздел “Custom HTML” служит для вставки произвольных кусочков html-кода внутрь html-страничек (например, так я подключал библиотеку jquery для реализации пары визуальных эффектов). Больше я не буду углубляться в детали настройки внешнего вида confluence, просто помните, что в confluence можно легко изменить внешний вид сайта и сделать это можно множеством частично пересекающихся средств, начиная от простейшего изменения стилевого оформления текста, до кардинальной переделки шаблонов страниц.

В практике управления confluence важную роль занимают задачи создания резервных копий, и хотя мы недавно отключили встроенный механизм создания таких копий по расписанию. Но, тем не менее, вы можете в любой момент на странице “Backup & Restore” либо запустить процедуру создания копии сайта (потом ее можно загрузить на свой компьютер как zip-архив), либо загрузить файл архива обратно на сайт, с тем, чтобы восстановить confluence из бэкапа. Раздел панели управления “Content Indexing” служит для управления поисковыми индексами. Confluence самостоятельно поддерживает актуальность поискового индекса, создавая задания на переиндексацию по мере того, как на сайте появляется новая информация. Но и вы можете просматривать эту очередь заданий и принудительно инициировать пересоздание поискового индекса. Остальные раздели панели управления связаны либо с работой со списками учетных записей и правами пользователей, либо носят крайне специфический характер и нужны для настройки системных журналов, наблюдения за “внутренним миром” confluence и, в случае сбоев, отправки отчетов в службу технической поддержки. Здесь может пригодиться только возможность увидеть то, сколько оперативной памяти было выделено java-машине и сколько из нее используется (раздел “System Information”).

Теперь давайте подробно рассмотрим раздел панели управления “Users”. Там вы увидите список всех пользователей, зарегистрированных в confluence (напоминаю, что предельное значение этого числа определяется тем, какую лицензию на confluence вы приобрели). Для каждого пользователя создается “профиль”, куда вносится информация о нем лично, а также о том, какое содержимое он создал в confluence, т.е. какие страницы и когда редактировал, за какими страницами он установил “отслеживание и оповещение об изменениях”. Следующий раздел панели управления “Global Permissions” служит для настройки глобальных прав доступа. Дело в том, что в confluence все права распределены на трех уровнях: глобальном, уровне отдельного пространства (space) и права для конкретной страницы. Естественно, что эти права могут уточнять друг друга по схеме от более общих к более конкретным. Так я советую вам включить вам функцию “can use” для анонимного пользователя. В противном случае, если пользователь просто откроет сайт с confluence, то ему потребуется аутентифицироваться иначе он не сможет не только редактировать информацию, но и просто просматривать ее. На этом я завершаю краткий обзор панели управления и перехожу к, собственно, наполнению confluence информацией.

И первым шагом для этого нам нужно создать пространство (space). Дело в том, что информация внутри confluence организована внутри логических и административных единиц “пространств” (space в терминологии confluence). Каждое пространство можно воспринимать как отдельный сайт с собственным независимым набором страниц. Для создания “пространства” вы заходите на главную страницу сайта и выбираете команду “Create a space”. На форме добавления space вы указываете его название, используемый шаблон внешнего вида и то какие пользователи будут иметь право работы со space (можно раздельно настроить права на создание новых страниц, а также на просмотр и комментирование статей). Следует также знать, что пользователь, который создает space, автоматически назначается администратором именно этого space и занимает в иерархии прав confluence второе место после “всемогущего” системного администратора. После того как space был создан, вы попадаете на его главную страницу (см. рис. 2)



и можете начать наполнять space информацией. Условно, информация может быть разделена на страницы и записи в блоге. Выбрав в меню пункт “Add Content -> Add Page” вы попадете на форму создания новой страницы. Там все интуитивно понятно: вверху формы вы указываете название страницы, а в большом текстовом поле внизу – текст статьи. Текст статьи может быть не только “простым” текстом, но и содержать не очень сложное форматирование. Все wiki-системы построены на использовании специального синтаксиса для пометки того какой текст нужно выделить жирным шрифтом, вставить таблицу или установить размер заголовка. Краткая сводка по основным командам этой “как бы” html-разметки приводится на панели справа. В confluence очень удобно добавлять к тексту статьи картинки. Для этого создано специальное диалоговое окно, где вы можете загрузить на сервер изображение со своего компьютера или же выбрать для вставки в страницу, одну из ранее загруженных картинок. Ключевое отличие confluence от других вики-систем в том, что здесь созданы рабочие механизмы вставки внутрь страничек сложных элементов управления. Так по нажатию на кнопку “Insert macro” вы увидите всплывающее диалоговое окно, в котором предлагается вставить в страничку одну из заготовок (см. рис. 3).



Среди макросов-шаблонов есть как простенький “раскрашенный текст”, так и более сложные “график”, “галерея изображений”, “интерактивный просмотр pdf-документа”, также вам доступны макросы, умеющие импортировать информацию из rss и импортировать список заданий из JIRA. Вы можете в любую секунду проверять то, что у вас получается в ходе редактирования статьи с помощью закладки “Preview” (см. рис. 4).



Каждая из создаваемых вами страниц, существует не просто так, а занимает определенное место в общей иерархии, т.е. у каждой страницы есть список дочерних страниц. Для того, чтобы указать подобное место для создаваемой вами страницы, используйте кнопку “ Location:” (см. рис. 5).



Как я уже упоминал ранее для каждой страницы можно индивидуально настроить права доступа, указав каким группам пользователей разрешено просматривать страницу, а также ее редактировать (кнопка “Restrictions:”). В качестве средства группировки создаваемых страниц по категориям предназначен механизм “Labels”, который заключается в том, что к странице можно привязать произвольный список ключевых слов-тегов. А впоследствии мы всегда можем выполнить поиск и показать на экране те страницы, что помечены каким-то из этих тегов. После создания страницы пользователи могут комментировать текст статьи (см. рис. 6),



используя wiki-редактор с такими же функциями, как и редактор, использованный при создании самой статьи (различное форматирование, вставка картинок и т.д.). Я завершу рассказ о наполнении confluence информацией, рассказав о работе с блогами. Фактически запись в блоге – это та же самая страница, но дополнительно привязанная к определенной дате в календаре и пользователю, который ее создал. При создании записей в блоге, вы можете использовать все те же механизмы (wiki-разметка, вставка изображений и макросов), что и ранее, при создании страниц.

Рассказ о confluence получился не слишком большим, т.к. я уверен, что вам не составит сложности в том, чтобы разобраться с основными функциями confluence: благо все вики-системы очень похожи друг на друга. Основной выигрыш от использования confluence получат те, кто планирует ее использовать вместе с остальными продуктами от компании atlasian. Использование же confluence как платформы для небольшого домашнего сайта или блога, хоть и возможно, но малоцелесообразно из-за большого числа “бюджетных” ограничений (специальный хостинг, стоимость).

« Работаем в online-офисе вместе с Manymoon.com