# Настройка и запуск приложения "Первая Форма" в Docker Compose

## Введение в архитектуру приложения и ключевые сервисы

Первая Форма — это приложение, состоящее из нескольких взаимодействующих сервисов. Основу архитектуры составляют два главных контейнера — 1f-spa и 1f-core, а также дополнительные вспомогательные сервисы и интеграции. Ниже перечислены ключевые компоненты системы:

[1F-CORE (Backend)](https://help.1forma.ru/maintenance_guide/system-services/1f-core.md) — сервер приложений на .NET, реализующий API и бизнес-логику системы. Он обрабатывает запросы от фронтенда, взаимодействует с базой данных и выполняет фоновые задачи (при включении режима job-сервера).

[1F-SPA (Frontend)](https://help.1forma.ru/maintenance_guide/system-services/1f-spa.md) — одностраничное веб-приложение (Angular) с интерфейсом системы. Поставляется вместе с веб-сервером Nginx для раздачи статического контента (HTML, JS, CSS) и, при необходимости, проксирования запросов к backend. SPA может работать в двух режимах: Standalone (только статика, без прокси) и Reverse Proxy (статика + проксирование API на Core).

[1F-DBDeploy (Migration Service)](https://help.1forma.ru/maintenance_guide/system-services/1f-dbdeploy.md) — вспомогательный сервис миграции базы данных. Однократно запускается перед стартом backend, читает SQL-скрипты обновлений из заданной директории и применяет их к базе данных (MSSQL или PostgreSQL). Обеспечивает актуальное состояние схемы БД для 1F-CORE.

База данных — СУБД, используемая приложением для хранения данных. Поддерживаются Microsoft SQL Server или PostgreSQL. Вы можете развернуть СУБД в контейнере (например, официальный образ Postgres) либо использовать существующую серверную базу.

Опционально: [OnlyOffice Docs](https://help.1forma.ru/maintenance_guide/office/onlyofficedocs.md) — сервер совместного редактирования документов (OnlyOffice Document Server) для онлайн-просмотра и редактирования файлов из "Первой Формы". Интегрируется через REST API и проксируется фронтендом. Требует отдельного контейнера или сервера с настроенным JWT-секретом (см. раздел ниже).

Опционально: [Matomo](https://help.1forma.ru/maintenance_guide/integrations/matomo.md) — платформа веб-аналитики с открытым кодом. Может использоваться для сбора статистики использования "Первой Формы" (просмотры страниц, действия пользователей и т.д.). Интеграция осуществляется через добавление соответствующих настроек Matomo в конфигурацию приложения (CustomSettings) и деплой сервиса Matomo.

Опционально: MinIO/S3 хранилище — объектное хранилище, совместимое с AWS S3, для сохранения загружаемых файлов.

Опционально: [Redis](https://help.1forma.ru/maintenance_guide/system-services/redis.md) — для масштабирования SignalR в .NET-приложении (бэкенде) "Первая Форма" необходимо использовать Redis как бэкплейн.

Ниже приведена подробная инструкция по настройке каждого компонента в Docker Compose, включая конфигурацию переменных окружения, сетевых подключений, томов данных и последовательность запуска сервисов.

> **Важно!** Для корректной работы приложения "Первая Форма" необходимо опубликовать его по HTTPS. При использовании единственной ноды необходимо настроить frontend для доступа по HTTPS. При использовании нескольких нод и балансировщика нагрузки можно опубликовать приложение по HTTP на веб-серверах и настроить SSL-терминирование на балансировщике. Для балансировки нагрузки рекомендуется использовать Nginx.

## Минимальные требования к серверу Linux

- 4 vCPU

- 8GB RAM

- 35GB Storage

- Операционная система Linux с поддержкой Docker Engine версии 24 и выше

- Docker Compose версии 2.17 и выше

Подготовка сервера Linux включает установку последней версии Docker и Docker Compose. Рекомендуется использовать инструкцию официального сайта Docker.

## Настройка доступа и получение файлов конфигурации

Необходимые для запуска приложения образы Docker находятся в приватном Docker Registry. Для получения доступа к данному registry необходимо пройти авторизацию. Учётные данные для входа запросите у сотрудников компании "Первая Форма".

Для авторизации используйте команду docker login и введите полученные учётные данные:

`docker login docker.1forma.ru`

После успешной авторизации появится сообщение: Login Succeeded. Компания "Первая Форма" распространяет комплект необходимых файлов в виде архива

(например, `1forma-compose.zip` ).

Вы можете скачать архив с конфигурационными файлами с ресурсов "Первая Форма" по ссылке: [https://download.1forma.ru/raw-1f-app/configurations/1forma-compose.zip](https://download.1forma.ru/raw-1f-app/configurations/1forma-compose.zip).

Например:

`wget --user USERNAME --ask-password https://download.1forma.ru/raw-1f-app/configurations/1forma-compose.zip`

## Запуск приложения

Прежде чем запускать Docker Compose, необходимо подготовить файлы конфигурации и окружение. Содержимое архива нужно распаковать в целевой каталог на сервере. Рекомендуемый путь — /opt/1forma, но вы можете выбрать и другой:

`unzip 1forma-compose.zip -d /opt/1forma`

Файл docker-compose.yml содержит описание всех контейнеров, сетей и томов. Файл env.example — шаблон с переменными окружения и описаниями, предоставленный разработчиками. На основе него необходимо создать рабочий файл .env. Создайте файл .env: перейдите в папку проекта и выполните команду:

`cp env.example .env`

Внутри .env могут быть перечислены десятки параметров настройки. Многие имеют значение по умолчанию — достаточно настроить ключевые, остальные можно оставить без изменений.

Обязательные к настройке переменные (минимум для успешного запуска):

- Версии образов: CORE\_VERSION и SPA\_VERSION — укажите версии Docker-образов бэкенда и фронтенда, которые вы собираетесь запускать. Эти версии должны соответствовать скачанным/доступным образам в registry.

- Параметры базы данных: CORE\_DB\_TYPE, CORE\_DB\_SERVER, CORE\_DB\_NAME, DB\_NAME, CORE\_DB\_USER, CORE\_DB\_PASSWORD. Эти параметры должны быть выставлены согласно вашей базе данных.

- Параметры Rebus: REBUS\_DB\_USER, REBUS\_DB\_PASSWORD.

- Имя экземпляра: CORE\_APPLICATION\_INSTANCE\_ID — уникальный идентификатор экземпляра (без пробелов и дефисов, можно буквы, цифры, \_ ).

- Параметры подключения к БД dbDeploy.

- Режим работы 1f-spa и URL проксирования при необходимости: SPA\_STANDALONE  SPA\_PROXY\_CORE\_URL  SPA\_PROXY\_ONLYOFFICE\_URL.

Обратитесь к документации сервисов для получения расширенного описания.

Запустите приложение:

`docker compose up -d`

Для остановки Docker Compose выполните команду:

`docker compose down`

Для обновления приложения укажите соответствующие версии CORE\_VERSION и SPA\_VERSION и запустите приложение:

`docker compose up -d`

После этого Docker загрузит новые образы из Registry "Первой Формы" и перезапустит контейнеры автоматически.

Для загрузки Docker Image вручную используйте команду docker pull.

## Удаление старых образов

После обновления приложения "Первой Формы" на сервере могут оставаться неиспользуемые старые Docker Images.

Для просмотра всех образов на сервере выполните команду:

`docker images`

Для удаления неиспользуемых образов выполните:

`docker rmi IMAGE\_ID`