Принципы
Приложение работает с использованием программного каркаса 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). В установке по умолчанию конфигурационные файлы всех веб-приложений АСР располагаются в директории /opt/hydra/rails/config. Нужно иметь в виду, что эта переменная должна быть установлена при запуске Unicorn, иначе при запуске приложения возникнет ошибка об отсутствующем файле конфигурации (обычно для запуска, останова и перезапуска Unicorn удобнее всего использовать инициализационный скрипт /etc/init.d/hydra_hupo, который самостоятельно устанавливает корректные переменные окружения). Файл hupo_configuration.yml хранит конфигурацию в формате YAML, удобном для хранения несложных программных структур.
ЛК подгружает программные файлы из директорий в следующем порядке (относительно директории с версией):
- Сначала подгружаются основные файлы приложения, расположенные в директории приложения. В первую очередь это файлы в директориях app/assests (стили, картинки, JavaScript-код) и config/locales (файлы локализации).
- Затем подгружаются файлы из директории lib/clients-stuff/lib/clients_stuff/hupo/default (в дальнейшем обозначается переменной $latera_default). Это настройки инсталляции по умолчанию.
- После этого, если в конфигурационном файле установлен ключ client, отличный от default, то будут подгружены файлы из директории lib/clients-stuff/lib/clients_stuff/hupo/%config.client% (далее $latera_client). Здесь хранятся файлы, которые были созданы Латерой для настройки ЛК под нужды клиента.
- Наконец, последними подгружаются файлы из директории, указанной в конфигурационном файле в ключе shared_path. В стандартной инсталляции это /opt/hydra/rails/hupo/shared/%config.client% (далее $server_client). Там клиент может хранить свои настройки и программный код, которого нет в репозиториях Латеры. Эти файлы имеют наибольший приоритет.
Структура директорий
Директории $latera_default, $latera_client и $server_client имеют одинаковую структуру:
- Директория assets может содержать в себе четыре поддиректории:
images — изображения;
javascripts — JavaScript-файлы (в формате CoffeeScript, расширение .js.coffee);
stylesheets — CSS-стили (в формате SASS, расширение файлов .sass);
templates — hamlc-шаблоны.
Для сборки статичных файлов используется Assets Pipeline. - Директория locales содержит файлы локализации. Для интернационализации в проекте используются библиотеки i18n, R18n и i18n-js. Весь отображаемый в приложении текст берется из файлов локализации (директория config/locales в директории с версией приложения). Для добавления пользовательского текста следует создавать дополнительные файлы в директориях $latera_client и $server_client. Для замены существующего текста достаточно в этих файлах переопределить перевод по нужному ключу (таким образом можно изменить любой текст в приложении).
- Директория widgets хранит настройки виджетов — настраиваемых программных сущностей приложения. Все элементы, требующие настройки, настраиваются через виджеты. Настройки виджетов хранятся в YAML. Содержимое всех файлов в директориях widgets объединяется при загрузке.
Добавление файлов
- Для добавления изображений достаточно поместить их в директорию images.
- Добавление стилей и JavaScript-кода должно начинаться с добавления файлов custom в корне директории (файлы custom.sass и custom.js.coffee соответственно). В этих файлах можно подключить остальные пользовательские файлы (с любыми именами, см. документацию по Assets Pipeline). Пользовательские файлы будут иметь больший приоритет при подключении, поэтому их названия не должны совпадать с названиями файлов приложение (исключая случай, когда требуется пропустить загрузку каких-то файлов приложения).
- Для добавления файлов локализации достаточно поместить их в директорию locales. Крайне желательно при это соблюдать при этом соглашение о наименовании. В начале файла должно находиться название локали. Например, ru.yml или ru.widgets.yml.
Сборка файлов
Файлы из директорий assets для использования в приложении должны быть скомпилированы. Компиляция запускается rake-командой (под пользователем rails):
root@server ~# sudo -u rails -i rails@server ~/hupo/current$ HYDRA_CONFIG_PATH=~/config RAILS_GROUPS=assets rake assets:precompile
В редких случаях, когда появляются файлы с одинаковыми именами, может потребоваться перед компиляцией сбросить кэш скомпилированных файлов:
rails@server ~/hupo/current$ rm -rf tmp/cache/assets
Перезапуск приложения
Перезапуск приложения требуется для загрузки новых файлов. Перезапустить приложение можно несколькими способами:
- Отправка USR2-сигнала master-процессу сервера Unicorn. pid процесса можно узнать в файле /opt/hydra/rails/shared/pids/unicorn.pid. Спустя какое-то время после отправки сигнала сервер перезапустится, вместе с ним перезапустится и приложение. Если при перезапуске не произошло ошибок, то pid master-процесса изменится. Иначе следует проверить файл log/unicron_error.log в директории с версией на наличие ошибок.
- Перезапуск Unicorn инициализационным скриптом /etc/init.d/hydra_hupo.
Ручной останов и запуск Unicorn. Для останова нужно отправить TERM-сингал master-процессу. Повторный запуск приложения выполняется командой:
rails@server ~/hupo/current$ HYDRA_CONFIG_PATH=~/config bundle exec unicorn_rails -c config/unicorn.rb -E production -D