Архитектурно приложение "Первая Форма" состоит из двух контейнеров: frontend и backend. В контейнере frontend используется веб-сервер Nginx для предоставления статических файлов фронтенда и проксирования запросов к контейнеру backend. В свою очередь, контейнер backend содержит приложение на платформе .NET, которое обрабатывает запросы и взаимодействует с базами данных. С момента выхода релиза 2.257 Орион используется версия .NET 8.0.
Для корректной работы приложения Первая Форма, необходимо опубликовать его по https. При использовании единственной ноды, важно настроить frontend для доступа по https. При использовании нескольких нод и балансировщика нагрузки, можно опубликовать приложение по http на веб-серверах и настроить SSL-терминирование на балансировщике. Для балансировки нагрузки рекомендуется использовать Nginx.
Минимальные требования к серверу Linux
•4 vCPU.
•4 GB RAM.
•35GB Storage.
•Операционная система Linux с поддержкой Docker Engine версии 24 и выше.
•Docker Compose версии 2.17 и выше.
Подготовка Linux сервера
Настройка сервера Linux
Проверьте и, при необходимости, отредактируйте настройки времени и часовой зоны. В операционной системе Ubuntu вы можете изменить часовой пояс с помощью команды:
timedatectl set-timezone Europe/Moscow
Установите необходимые пакеты для установки и диагностики работы приложения "Первая Форма":
apt-get update
apt-get install curl wget vim ca-certificates zip
Установка Docker и Docker Compose v2
Подготовка сервера Linux включает установку последней версии Docker и Docker Compose. Рекомендуется использовать инструкцию с официального сайта Docker.
Ниже приведен пример установки Docker и Docker Compose на операционную систему Ubuntu 22.04 LTS.
Добавьте официальный ключ GPG Docker:
apt-get update
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc
Добавьте репозиторий в источники Apt:
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
Установите пакеты Docker:
apt-get update
apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Проверьте версии Docker и Docker Compose:
docker version
docker compose version
Настройка доступа и получение файлов конфигурации
Необходимые для запуска приложения образы Docker находятся в приватном Docker Registry. Для получения доступа к даннному registry необходимо пройти авторизацию. Учетные данные для входа запросите у сотрудников компании "Первая Форма".
Для авторизации используете команду docker login и введите полученные учетные данные:
docker login docker.1forma.ru
Вы должны получить сообщение: Login Succeeded.
Архив с файлами конфигурации для приложения "Первая Форма" доступен для скачивания с внутренних ресурсов по ссылке. Для доступа к архиву запросите логин и пароль у сотрудников компании "Первая Форма".
Для загрузки архива из консоли рекомендуется использовать утилиту wget. Введите полученные учетные данные:
wget -O 1forma-compose.zip --user=USER_NAME --ask-password https://downloads.1forma.ru/1forma-compose.zip
где USER_NAME — Ваше имя пользователя.
Создайте каталог для хранения файлов конфигурации и выполните распаковку архива. Рекомендуем использовать каталог /opt/1forma:
mkdir -p /opt/1forma
unzip -d /opt/1forma 1forma-compose.zip
Настройка приложения "Первая Форма"
Подготовка конфигурационных файлов
Для запуска приложения "Первая Форма" в Docker Compose необходимо наличие файлов:
docker-compose.yml — используется для описания многоконтейнерных приложений. В нем указываются параметры и настройки для запуска и конфигурирования контейнеров, их сетей, томов и других связанных с ними ресурсов.
.env — содержит переменные окружения для конфигурации приложения. Хранит секретные ключи, пароли, адреса серверов и другие данные, а так же параметры работы приложения.
Перейдите в созданный каталог приложения "Первая Форма":
cd /opt/1forma
Создайте .env файл из шаблона env.example:
cp env.example .env
Изменение параметров работы приложения осуществляется путем редактирования файлов .env и docker-compose.yml.
Для редактирования можете использовать любой текстовый редактор, в котором вам удобно работать. Конфигурационные файлы содержат множество редактируемых параметров. В данной инструкции мы не будем перечислять их все, но отметим несколько необходимых для успешного запуска значений. Каждый параметр в файле .env сопровождается описанием. Некоторые параметры имеют значения по умолчанию (Default).
Настройки .NET приложения определяются в файле appsettings.json. При запуске Docker контейнера Backend файл appsettings.json генерируется из шаблона согласно параметрам, описанным в .env файле.
Общие настройки приложения
Параметр |
Описание |
|---|---|
APP_NAME |
Название приложения. Этот префикс будет добавлен к названиям Docker контейнеров. Данная настройка полезна при запуске нескольких экземпляров приложения "Первая Форма" на сервере. Если значение не указано, будет использовано значение по умолчанию: "1forma". |
BACKEND_VERSION |
Версия .NET приложения (Backend). Версия сборки backend контейнера. Пример значения: release 2.258.2.3 |
FRONTEND_VERSION |
Версия Spa (Frontend). Версия сборки frontend контейнера. Пример значения: release-2.258.9 |
|
|---|
Настройка подключения к базе данных
Для настройки подключения к базе данных укажите следующие параметры в .env файле:
Параметр |
Описание |
|---|---|
DB_TYPE |
Тип базы данных: postgres или mssql |
DB_SERVER |
IP или Доменное имя сервера БД |
DB_PORT |
Порт подключения к серверу БД. Только для PostgreSQL |
DB_NAME |
Название БД |
DB_USER |
Пользователь подключения к БД |
DB_PASSWORD |
Пароль пользователя БД |
DB_REBUS_SERVER |
IP или Доменное имя сервера БД, который используется для работы REBUS. Зачастую совпадает с сервером БД |
DB_REBUS_PORT |
Порт подключения к серверу БД REBUS. Только для PostgreSQL |
DB_REBUS_NAME |
Название БД REBUS |
DB_REBUS_USER |
Пользователь подключения к БД REBUS |
DB_REBUS_PASSWORD |
Пароль пользователя БД REBUS |
DISABLE_REBUS |
Если вы не используете подключение к REBUS, установите значение данного параметра true. Значение по умолчанию: false. |
Настройка шины сообщений
Выполните настройку шины сообщений, указав параметры в .env файле:
Параметр |
Описание |
|---|---|
INSTANCE_ID |
Название очереди. Уникальное значение |
MESSAGE_BUS |
Провайдер сообщений. Возможные значения: •None •Redis •RebusSQL •RebusPostgre |
Другие настройки .NET приложения
В .env файле присутствует множество иных параметров для настройки .NET приложения. Указав переменные в .env вы можете менять значения ключей в appsettings.json.
Настройка https
По умолчанию приложение работает по http. Для работы приложения по https необходимо в файле .env настроить следующие параметры:
Параметр |
Значение |
Описание |
|---|---|---|
SSL_CERT_PATH |
/some_path_to_crt |
Абсолютный путь к сертификату |
SSL_KEY_PATH |
/some_path_to_key |
Абсолютный путь к приватному ключу |
ENABLE_HTTP_REDIRECT |
true |
Включить редирект с http на https с кодом ответа 301 |
ENABLE_HTTPS |
true |
Включить https |
В docker-compose.yml указать настройки volumes. Выполняется для того, чтобы пробросить файлы сертификата внутрь Docker контейнера:
volumes:
- '${SSL_CERT_PATH}:${SSL_CERT_PATH}'
- '${SSL_KEY_PATH}:${SSL_KEY_PATH}'
Проксирование запросов на WebForms утилиту администрирования
Чтобы настроить reverse_proxy для запросов на утилиту администрирования, укажите следующие параметры в .env:
Параметр |
Значение |
Описание |
|---|---|---|
PROXY_ADMIN |
true |
Включить проксирование на WebForms утилиту администрирования |
PROXY_ADMIN_URL |
admin_url |
URL WebForms утилиты администрирования |
Использования custom configs
Для отладки и тестирования работы приложения "Первая Форма" предусмотрена возможность использования готовых кастомных файлов appsettings.json и Nlog.config. При таком сценарии параметры в .env файле будут проигнорированы.
Для использования кастомных файлов конфигурации .NET необходимо создать каталог и поместить туда файлы appsettings.json и/или Nlog.config.
Названия должны быть именно такими с учетом регистра:
mkdir -p /opt/1forma/custom-configs
vim opt/1forma/custom-configs/appsetting.json
vim opt/1forma/custom-configs/NLog.config
В .env указать путь к этому каталогу в параметре CUSTOM_CONFIGS_DIR.
CUSTOM_CONFIGS_DIR=/opt/1forma/custom-configs
В docker-compose.yml указать настройки volumes:
volumes:
- '${CUSTOM_CONFIGS_DIR}:/custom-configs'
При старте backend контейнера вместо генерации файлов из шаблона, приложение будет использовать конфигурационные файлы размещенные в указанном каталоге.
Запуск и обновление приложения "Первая Форма"
Запуск и остановка приложения
При завершении редактирования настроек приложения "Первая Форма" необходимо выполнить запуск Docker Compose. Для этого, находясь в каталоге приложения, выполните команду:
docker compose up -d
или
docker compose -f docker-compose.yml -d
Дождитесь, пока Docker выполнит загрузку образов из Registry "Первой Формы" и запустит приложение. Проверьте локальную работу приложения утилитой curl:
curl http://localhost
curl -k https://localhost
Для остановки Docker Compose выполните команду:
docker compose down
Отладка работы приложения
Для просмотра логов работы выполните команду docker compose logs. Вы можете просмотреть логи работы всех контейнеров или конкретного сервиса. Например:
docker compose logs -f --tail 100
docker compose logs -f --tail 100 backend
docker compose logs -f --tail 100 frontend
Обновление
Для загрузки Docker Image вручную используйте команду docker pull.
docker pull docker.1forma.ru/1forma/frontend:FRONTEND_VERSION
docker.1forma.ru/1forma/backend:BACKEND_VERSION
Для обновления приложения "Первая Форма" укажите новые версии Backend и Frontend в .env файле:
BACKEND_VERSION
FRONTEND_VERSION
После этого выполните команду:
docker compose up -d
После этого Docker загрузит новые образы из Registry "Первой Формы" и перезапустит контейнеры автоматически.
|
|---|
Удаление старых образов
После обновления приложения "Первой Формы" на сервере могу оставаться неиспользуемые старые Docker Images.
Для просмотра всех образов на сервере выполните команду:
docker images
Для удаления неиспользуемых образов выполните:
docker rmi IMAGE_ID
