Принципы

Приложение работает с использованием программного каркаса Ruby on Rails версии 3.2. Приложение располагается в одной директории на сервере (в стандартной инсталляции это /opt/hydra/rails/hupo). В этой директории есть символьная ссылка current, которая указывает на текущую версию приложения. При установке обновления в директории releases появляется новая версия, и символьная ссылка обновляется. Это означает, что все локальные изменения в приложении не сохраняются при обновлении. Специально для этого случая ЛК позволяет подгружать исходный код из других директорий.

Приложение запускается с помощью веб-сервера Unicorn, который открывает unix-сокет по адресу /opt/hydra/rails/hupo/shared/unicorn.sock (в стандартной инсталляции). Для эффективной отдачи статических файлов также запускается веб-сервер nginx с нужными настройками. Он проксирует запросы к приложению на открытый сокет, а статические файлы отдает самостоятельно (JavaScript-код, изображения, стили). В инсталляции по умолчанию nginx прослушивает порт 8001. Для перезапуска приложения необходимо перезапускать Unicorn, поскольку именно он ответственен за работу приложения. nginx необходимо перезапускать лишь при изменениях в его файлах конфигурации (обычно они располагаются в директории /etc/nginx).

Переменная окружения HYDRA_CONFIG_PATH указывает на директорию, в которой лежит конфигурационный файл приложения (его имя hupo_configuration.yml). В установке по умолчанию этот конфигурационный файл располагаются в директории /etc/hydra/hupo. Нужно иметь в виду, что эта переменная должна быть установлена при запуске Unicorn, иначе при запуске приложения возникнет ошибка об отсутствующем файле конфигурации (обычно для запуска, останова и перезапуска Unicorn используется инициализационный скрипт /etc/init.d/hupo, который самостоятельно устанавливает корректные переменные окружения). Файл hupo_configuration.yml хранит конфигурацию в формате YAML, удобном для хранения несложных программных структур.

ЛК подгружает программные файлы из директорий в следующем порядке (относительно директории с версией):

1. Сначала подгружаются основные файлы приложения, расположенные в директории приложения. В первую очередь это файлы в директориях app/assests (стили, картинки, JavaScript-код) и config/locales (файлы локализации).
2. Затем подгружаются файлы из директории lib/clients-stuff/lib/clients_stuff/hupo/default (в дальнейшем обозначается переменной $latera_default). Это настройки инсталляции по умолчанию.
3. После этого, если в конфигурационном файле установлен ключ client, отличный от default, то будут подгружены файлы из директории lib/clients-stuff/lib/clients_stuff/hupo/%config.client% (далее $latera_client). Здесь хранятся файлы, которые были созданы Латерой для настройки ЛК под нужды клиента.
4. Наконец, последними подгружаются файлы из поддиректории %config.client% директории, указанной в конфигурационном файле в ключе shared_path. В стандартной инсталляции это /etc/hydra/hupo/local/%config.client% (далее $server_client). Здесь могут храниться пользовательские настройки и программный код, которого нет в репозиториях Латеры. Эти файлы имеют наибольший приоритет.

Структура директорий

Директории $latera_default, $latera_client и $server_client имеют одинаковую структуру:

1. Директория assets может содержать в себе четыре поддиректории:
   images — изображения;
   javascripts — JavaScript-файлы (в формате CoffeeScript, расширение .js.coffee);
   stylesheets — CSS-стили (в формате SASS, расширение файлов .sass);
   templates — hamlc-шаблоны.
   Для сборки статичных файлов используется Assets Pipeline.
2. Директория locales содержит файлы локализации. Для интернационализации в проекте используются библиотеки i18n, R18n и i18n-js. Весь отображаемый в приложении текст берется из файлов локализации (директория config/locales в директории с версией приложения). Для добавления пользовательского текста следует создавать дополнительные файлы в директориях $latera_client и $server_client. Для замены существующего текста достаточно в этих файлах переопределить перевод по нужному ключу (таким образом можно изменить любой текст в приложении).
3. Директория widgets хранит настройки виджетов — настраиваемых программных сущностей приложения. Все элементы, требующие настройки, настраиваются через виджеты. Настройки виджетов хранятся в YAML. Содержимое всех файлов в директориях widgets объединяется при загрузке.

Добавление файлов

1. Для добавления изображений достаточно поместить их в директорию images.
2. Добавление стилей и JavaScript-кода должно начинаться с добавления файлов custom в корне директории (файлы custom.sass и custom.js.coffee соответственно, для формы входа в ЛК - custom_login.sass). В этих файлах можно подключить остальные пользовательские файлы (с любыми именами, см. документацию по Assets Pipeline). Пользовательские файлы будут иметь больший приоритет при подключении, поэтому их названия не должны совпадать с названиями файлов приложение (исключая случай, когда требуется пропустить загрузку каких-то файлов приложения). При выборе имен файлов надо учитывать, что сборщик статичных файлов отбрасывает расширение и файлы с одинаковым именем, но разным расширением могут конфликтовать, в этом случае сборщик выберет какой-то один файл.
3. Для добавления файлов локализации достаточно поместить их в директорию locales. Крайне желательно соблюдать при этом соглашение о наименовании. В начале файла должно находиться название локали. Например, ru.yml или ru.widgets.yml.

Сборка файлов

Файлы из директорий assets для использования в приложении должны быть скомпилированы. Компиляция их также необходима после изменения файлов локализации. Компиляция запускается с помощью инициализационного скрипта:

root@server:~# /etc/init.d/hupo recompile_assets

В редких случаях, когда появляются файлы с одинаковыми именами, может потребоваться перед компиляцией сбросить кэш скомпилированных файлов:

root@server:~# rm -rf /opt/hydra/hupo/tmp/cache/assets

Перезапуск приложения

Перезапуск приложения требуется для загрузки новых файлов. Перезапустить приложение можно несколькими способами:

1. Отправка USR2-сигнала master-процессу сервера Unicorn. PID процесса можно узнать в файле /var/run/hydra/hupo/unicorn.pid. Спустя какое-то время после отправки сигнала сервер перезапустится, вместе с ним перезапустится и приложение. Если при перезапуске не произошло ошибок, то PID master-процесса изменится. Иначе следует проверить файл /var/log/hydra/hupo/unicorn_error.log на наличие ошибок.

2. Перезапуск Unicorn инициализационным скриптом /etc/init.d/hupo:

   root@server:~# /etc/init.d/hupo restart