9F.Sphynkx.Org.Ua: In GNU We Trust

Для 9front доступны по крайней мере два приложения для организации веб-контента - Acme Wiki и WERC. Acme Wiki весьма ограничена в возможностях и морально устарела, поэтому к использованию не рекомендуется. Для организации веб-сайта 9front предлагает собственную разработку - WERC.

WERC

Это многофункциональная CMS, разработанная командой 9front. Написана на rc и awk, в качестве веб-сервера использует rc-httpd также созданный участниками проекта 9front. WERC предоставляет возможности обслуживания нескольких виртуальных доменов, хостинга веб-контента, несколько встроенных приложений (wiki, сервис блогов, генератор каталога manpages из содержимого системы). Возможно написание и своих приложений - в составе имеется простейший пример. WERC дает возможность настраивать собственные стили страниц, менять организацию элементов на странице, настраивать их. Страницы создаются в формате Markdown, допустимо использование HTML-разметки.

Установка

Установка сводится к скачиванию и распаковке CMS, и настройке виртуального хоста в веб-сервере.

Скачиваем и распаковываем, и сразу создаем каталог, соответствующий желаемому виртуальному домены (в данном примере 9f.sphynkx.org.ua):

cd /sys/www
hget https://code.9front.org/hg/werc/archive/644b64e3f6a5.tar.bz2| tar zxv
mv werc-1.5.0 werc
mkdir /sys/www/werc/sites/9f.sphynkx.org.ua

Затем надо в lib/profile прописать aux/listen -q -t /rc/bin/service.auth -d /rc/bin/service tcp, а также убедиться в наличии файла /rc/bin/service/tcp80. Если его нет, делаем:

cp /rc/bin/service/!tcp80 /rc/bin/service/tcp80

Затем настраиваем конфигурацию доменов в /bin/rc-httpd/select-handler. Вот рабочий файл для единственного виртхоста:

#!/bin/rc

PLAN9=/
PATH_INFO=$location

switch($SERVER_NAME) {
case 9f.sphynkx.org.ua
FS_ROOT=/sys/www/werc/sites/$SERVER_NAME
exec static-or-cgi /sys/www/werc/bin/werc.rc

case *
error 503
}

Тут указывается переменная PLAN9, к которой хранится значение корня, относительно которого будут работать все скрипты WERC. В конструкции switch указывается домен и путь к основному обработчику. Случай использования IP-адреса при доступе к сайту будет рассмотрен ниже. На данном этапе сайт должен отвечать на внешние запросы.

Внутренняя организация

Каталог WERC содержит ряд подкаталогов общего назначения.

В каталоге apps расположены приложения, которые можно подключить в конфигурации домена.

• blagh - приложение блога
• bridge - движок форума. Может подключаться к другим приложениям для реализации в них функционала комментариев
• dirdir - wiki-движок
• duckduckgo - поисковый сервис, настроенный на https://duckduckgo.com/
• hello - простейший пример приложения, скелет для создания собственных
• paste - bastebin-сервис ??
• wman - сервис для генерации страниц мануала из manpages системы

Для подключения приложения необходимо в каталоге сайта создать каталог с именем приложения (либо в подкаталоге, напр. apps). В нем создать подкаталоги _werc, в котором файл config со строкой conf_enable_XXXX.

В каталоге bin несколько скриптов, которые и являются движком WERC.

• bin/werc.rc - Основной скрипт. Он производит инициализацию всех приложений, конфигурации доменов, подключает дополнительные модули и далее общается непосредственно с веб-сервером.
• bin/cgilib.rc и bin/wercconf.rc - различные вспомогательные функции.
• bin/corehandlers.rc - генератор общего шаблона страницы, подключение других шаблонов
• bin/werclib.rc - подключение стилей страниц, передача markdown-странички перекодировщику, авторизация пользователей.
• bin/aux/adduser.rc добавление пользователя, групп пользователей.
• bin/contrib/md2html.awk - конвертер markdown-разметки в HTML.

В каталоге etc хранится информация о пользователях, группах, сохраняются пароли. В файле etc/initrc настраиваются глобальные установки WERC. Для доменов их можно переопределять в конфиге домена.

lib хранит общие для всех доменов шаблоны частей страниц. Их трогать не надо. Если необходимо видоизменить существующие шаблоны для своего сайта, их надо скопировать в каталог домена и редактировать уже там.

pub - CSS-стили и фавиконка. Также, для собственных видоизменений скопировать в каталог домена и редактировать эти копии.

sites - местоположение доменов, обслуживаемых WERC. В качестве образца изначально там присутствуют несколько доменов. В каждом домене должен присутствовать подкаталог sites/domainname/_werc, в котором хранятся настройки домена и индивидуальные шаблоны, стили.

tpl - некоторые вспомогательные шаблоны.

Настройки домена

WERC обеспечивает глобальные настройки и оформление для всех доменов, которые он обслуживает. Для отдельных доменов возможны индивидуальные настройки. Настройки домена и элементы оформления хранятся в каталоге sites/domainname/_werc. В файле sites/domainname/_werc/config можно прописать название сайта, слоган, а также подключить приложения:

masterSite=9F.sphynkx.org.ua
siteTitle='9F.Sphynkx.Org.Ua: '
siteSubTitle='In GNU We Trust'
conf_enable_wiki

Оформление сайта

Для создания собственного оформления необходимо создать в каталоге sites/domainname/_werc подкаталоги sites/domainname/_werc/lib и sites/domainname/_werc/pub. В sites/domainname/_werc/lib скопировать нужные шаблоны из глобального каталога WERC lib, в sites/domainname/_werc/pub - соответственно из pub/style файлы CSS-стилей. Можно добавить и свой CSS-файл, разместив его в sites/domainname/_werc/pub. Затем его надо подключить в шаблоне sites/domainname/_werc/lib/headers.tpl, указав перед имеющимся шаблоном строку со своим:

<link rel="stylesheet" href="/_werc/pub/light.css" type="text/css" media="screen, handheld" title="default">

Для установки своей фавиконки ее изображение должно быть png-файлом с размером 32x32 и именем favicon.ico. Файл надо поместить в корень сайта.

Wiki

После подключения приложения и создания страницы создается каталог, в котором она хранится в виде файла вида pagename.md. Также создается каталог pagename.md_werc, в котором сохраняется история правок. Создаваемые странички отображаются в боковом меню в виде подпунктов wiki. Можно создавать вложенные страницы - они создадутся внутри каталога. При этом сам каталог будет отображать список содержащихся в нем страниц, либо, если содержит index.md, его содержимое. Каталоги начинающиеся с подчеркивания интерпретируются как скрытые и в меню не отображаются.

Изменение расположения

Указав в конфиге conf_enable_wiki в глобальном меню появится пункт apps/dirdir. Содержимое wiki будет располагаться в sites/domainname/apps/dirdir. Но это можно изменить - если создать каталог sites/domainname/wiki. Если другие приложения подключать не планируется, каталог apps можно удалить.

Кнопка удаления страницы

По умолчанию в wiki нет возможности удаления страницы, но ее легко добавить. Для этого в файле шаблона apps/dirdir/sidebar_controls.tpl после строки с "Edit page" добавляем строку:

<input type="submit" name="dirdir_delete" value="Delete page" />

В apps/dirdir/app.rc отредактируем функцию dirdir_init. Между строкой handler_body_main=(tpl_handler *{get_lib_file dirdir/edit.tpl apps/dirdir/edit.tpl}) и следующей if not if(...) добавляем:

if not if(~ 1 $#post_arg_dirdir_delete)
rm $dirdir_file

Прикрепление изображений и файлов

Средств для загрузки в wiki изображений и файлов не предусмотрено, поэтому осуществляется в командной строке. Для порядка желательно организовать отдельный каталог, где будут храниться прикрепляемые файлы. Чтобы этот каталог не отображался в боковом меню, ему надо дать имя, начинающееся со знака подчеркивания. Загруженные изображения встраиваются в wiki-страницу следующим образом:


<img src="_files/image.jpg" alt="Alt Title" title="Title" width="300px">

Тут _files - каталог с изображениями. Если страница находится в подкаталоге, надо учесть это и поправить путь на ../_files (относительно страницы).

Отладка

Имеются некоторые встроенные возможности для отладки. В etc/initrc параметр debug=true включает логирование в /sys/log/www. Запись в лог осуществляется функцией dprint, которую можно также расставить в коде в желаемых местах.

Параметр debug_shell=true включает консоль отладки, доступную по URLу http://sitename/_debug/

Баги и ограничения

Работа по IP

Работа WERC подразумевает, что обслуживаемый хост обладает именем, идентичным названию каталога, в котором расположен сайт. Это имя WERC определяет из настроек rc-httpd и пытается найти каталог с таким же именем в sites. Однако в случае если обращение к сайту происходит по IP-адресу, WERC показывает сообщение о ненайденной странице. Переменную $FS_ROOT WERC не учитывает. В данном случае каталогу сайта можно дать в качестве имени IP-адрес. Но в случае динамических IP-адресов сайт может оказаться недоступен. В этом случае можно внести поправку. Копируем файл etc/initrc в etc/initrc.local и объявляем дополнительную переменную $site=sitename где sitename - имя каталога с обслуживаемым сайтом. Затем в bin/werc.rc в функции werc_exec_request строку site=$SERVER_NAME меняем на site=$SERVER_NAME|$site

Неработающее Preview в wiki

Неработающее превью можно исправить изменением в app/dirdir/edit.tpl строки:

% echo $post_arg_edit_text | $formatter

на

% echo $post_arg_edit_text | md2html.awk

Нелатинские имена файлов и директорий

По крайней мере проблема присутствует у wiki. Это связано с тем, при создании и редактировании страниц передается URL, который в случае non-ASCII символов перекодирует их в urlencoded-форму, а затем фильтрует в нем знаки %. Для решения этой проблемы пришлось бы пересматривать логику работы WERC, поэтому в ближайшее время поддержки нелатинских названий страниц ожидать не стоит.

Отсутствие TOC

В WERC (и в wiki в частности) отсутствует такая полезная вещь, как содержание страницы, основанное на заголовках в тексте. Также нельзя ссылаться в гиперссылках на отдельные заголовки, если их не обозначить якорями явно.

Для добавления этой возможности необходимы небольшие модификации, описанные тут.

Рендеринг спецсимволов в тексте

Когда в тексте встречаются спецсимволы (напр. в именах переменных, типа $SERVER_NAME), они будут интерпретироваться парсером и ломать конечную разметку страницы. Эта проблема нерешаема, поскольку рендер не может угадывать контекст употребления спецсимволов. Избежать ненужной интерпретации можно экранируя спецсимволы обратным слешем, либо охватывая участок текста тегами <pre>...</pre>, либо заменяя их на соответствующие HTML-коды. Некоторые полезные символы и коды для замены:

Символ	Код	Название		Символ	Код	Название
<	&lt;	Левая угл.скобка		>	&gt;	Правая угл.скобка
(	&#40;	Откр.круглая скобка		)	&#41;	Закр.круглая скобка
[	&#91;	Откр.кв.скобка		]	&#93;	Закр.кв.скобка
{	&#123;	Откр.фиг.скобка		}	&#125;	Закр.фиг.скобка
/	&#47;	Прямой слеш		\	&#92;	Обратный слеш
|	&#124;	Вертикальная черта (Пайп)		`	&#96;	Апостроф
'	&#39;	Одинарная кавычка		"	&#34;	Двойная кавычка
#	&#35;	Решетка		*	&#42;	Звездочка
$	&#36;	Знак доллара		_	&#95;	Подчеркивание
	&nbsp;	Неразрывный пробел		¶	&#182;	swap device
σ	&#963;	share devive		¤	&#164;	cap device
æ	&#230;	aoe		Δ	&#916;	dtracy

Неправильный рендеринг

md-парсер неправильно генерирует тег blockquote при обработке цитат (угловой скобкой в markdown) результирующая цитата не разбивается на строки. Можно явно указывать тег <br> в конце строки.

В случае двойной цитаты (>> текст) на странице этот участок рендерится во вложенный blockquote. Если перед двойной цитатой присутствует одинарная, рендер отрабатывает нормально. Но если цитата только двойная, участок в blockquote не рендерится и отображается простым текстом. Можно исправлять, вставляя пробел между угловыми скобками (> > текст).

Неправильная интерпретация ** ... ** - в результирующем HTML коде получается
<strong></strong> ... <strong></strong>

Acme Wiki

Это штатный wiki-движок, появившийся еще в оригинальном Plan9. Как движок, обладает весьма скудными возможностями - можно создавать и редактировать простые текстовые странички в формате упрощенного Markdown. Вставку картинок не поддерживает, удаления страниц нет. В странице можно использовать HTML-теги и таким образом немного расширить возможности wiki. Шаблоны страниц для создания и редактирования в стандартной поставке отсутствуют и их необходимо организовать самостоятельно.

Настройка

Создаем каталог в /sys/www/9wiki.sphynkx.org.ua/wiki. В нем создаем каталог d - там хранится история страниц, кеши, лок-файлы..

Создаем отсутствующие страницы, их можно скачать с сервера Bell-labs.. который нынче уже не работает. Поэтому выкачиваем через веб-архив:

cd /sys/www/9wiki.sphynkx.org.ua/wiki
hget https://web.archive.org/web/20010512142627/http://plan9.bell-labs.com/wiki/plan9/create.html > create.html
hget https://web.archive.org/web/20010711223106/http://plan9.bell-labs.com/wiki/plan9/1/index.html > index.html
hget https://web.archive.org/web/20010719203207/http://plan9.bell-labs.com/wiki/plan9/about.html > about.html

В lib/profile корректируем сервисы в следующий вид:

wikifs -p 666 -s wiki.plan9 -a tcp!*!wiki /sys/www/9wiki.sphynkx.org.ua/wiki
mount -b /srv/wiki.plan9 /sys/www/9wiki.sphynkx.org.ua/wiki
ip/httpd/httpd -w /sys/www/9wiki.sphynkx.org.ua

Перегружаемся. Убеждаемся, что работают https://9wiki.sphynkx.org.ua/ и https://9wiki.sphynkx.org.ua/wiki/edit.html. Корректируем шаблоны:

<input type="hidden" name="service" value="plan9">
<input type="hidden" name="base" value="wiki">

и проверяем через https://9f.sphynkx.org.ua/wiki/create.html как создается страничка. В параметре поля с name="service" value="plan9" значение должно соответствовать параметру, указанному при запуске wikifs (часть после точки - plan9). Второе поле с name="base" value="wiki" содержит имя подкаталога поднятого веб-сервиса. Если веб-сервис организовывается иначе, данные поля должны быть соответствующим образом откорректированы.

Как видно из кода формы <form action="magic/wikipost" method="post">, редактируемая форма передает содержимое утилите wikipost - это CGI-обработчик, предназначенный исключительно для этой wiki. Возможно написание и собственных CGI-обработчиков, они должны вызываться из формы с префиксом magic.

Для этой вики существует сервис, подключающийся к внешнему серверу и расшаривающий локальные страницы подключающихся пользователей. Изначальная идея была в том, чтобы создать единое wiki-пространство из содержимого пользователей. Запускается командой 9fs wiki. Каталог страничек появляется в /mnt/wiki. Страниц много, но содержимое старое, по большей части бесполезное и неактуальное. Данной викой видимо уже никто не пользуется.