Быстрый старт: Docker

Эта инструкция — для администратора, который ставит Portal на один Linux-сервер через Docker Compose из готового архива (bundle).

Читайте сверху вниз. На каждом шаге есть команда «что ввести» и способ проверить, что шаг удался.

Если ещё не уверены, что нужен именно Docker — сначала выберите канал.

---

0. Что вы получите в итоге

После всех шагов:

1. На сервере работают контейнеры Portal (сайт, API, база, файлы и т.д.).
2. В браузере открывается Portal по адресу сервера (часто http://localhost или ваш домен).
3. Можно войти логином admin и паролем из файла .env.
4. На корневом узле есть страница приветствия welcome.

---

1. Что понадобится заранее

Что	Минимум	Зачем
Linux-сервер	с доступом по SSH	куда ставим
Docker 24 или новее	docker --version	запуск контейнеров
Docker Compose v2	docker compose version	команда docker compose
Оперативная память	4 GB минимум; 8 GB рекомендуется, если нужен Portal Office	иначе контейнеры будут падать
Архив дистрибутива	файл вида portal-1.0.0-docker-bundle.tar.gz	от поставщика

Шаг 1.1. Проверьте Docker

docker --version
docker compose version

Как проверить, что шаг удался: обе команды печатают номер версии, без ошибки command not found.

Если Docker не установлен — установите его по инструкции вашей ОС (Docker Engine + Compose plugin) и повторите команды.

---

2. Распакуйте bundle

Bundle — это архив с готовым Portal: образы контейнеров, portal-cli (программа-установщик), шаблоны конфигов и документация.

Имя файла может отличаться версией. Подставьте своё:

# перейдите в каталог, куда положили архив, например /opt
cd /opt
tar xzf portal-1.0.0-docker-bundle.tar.gz
cd portal-1.0.0-docker-bundle
pwd
ls -la

Что должны увидеть в списке файлов (имена могут слегка отличаться):

• каталог portal-cli/ — установщик;
• каталог images/ — файл с Docker-образами;
• portal.config.example.yaml — шаблон настроек (его копируют, оригинал не правят);
• docker-compose.yml — описание контейнеров.

Как проверить: pwd показывает путь к каталогу bundle; ls показывает перечисленные файлы.

Дальше все команды выполняйте из этого каталога (пока не указано иное).

---

3. Загрузите Docker-образы

Образы — «снимки» программ Portal. Их нужно один раз загрузить в Docker на сервере:

docker load -i images/portal-images.tar

Команда может идти несколько минут (файл большой).

Как проверить:

docker images | grep portal

Должны появиться строки с образами вроде portal/…. Если пусто — проверьте путь к images/portal-images.tar (ls -la images/).

---

4. Создайте файл настроек

Шаг 4.1. Скопируйте шаблон

cp portal.config.example.yaml portal.config.yaml
ls -la portal.config.yaml

Файл	Что это
portal.config.example.yaml	Пример «как должно быть». Его не редактируют.
portal.config.yaml	Ваша рабочая конфигурация. Её читает установщик.
.env	Появится после install. Секреты и порты для Docker Compose.

Шаг 4.2. Откройте конфиг в редакторе

На сервере удобен редактор nano (простой текстовый редактор в терминале):

nano portal.config.yaml

Как пользоваться nano:

1. Двигайтесь стрелками к нужной строке.
2. Правьте текст как в блокноте.
3. Сохранить: Ctrl+O, затем Enter.
4. Выйти: Ctrl+X.

(Можно vim или любой другой редактор — суть та же.)

Шаг 4.3. Что обязательно поправить

В начале файла найдите блок portal: и задайте свои значения. Пример:

portal:
  version: "1.0.0"
  domain: portal.company.local
  httpPort: 80
  httpsPort: 443
  timezone: Europe/Moscow

Правила простыми словами:

Поле	Что писать
domain	Имя сайта, по которому сотрудники откроют Portal (DNS или запись в /etc/hosts)
httpPort / httpsPort	Обычно 80 и 443. Если нет прав на привилегированные порты — см. §8
timezone	Часовой пояс организации в формате IANA: Europe/Moscow, Asia/Yekaterinburg, UTC и т.п.

Пустые секреты (jwtSecret, пароли) можно оставить пустыми — установщик сгенерирует их сам и запишет в .env.

Сохраните файл (Ctrl+O, Enter, Ctrl+X).

Как проверить:

grep -E 'domain:|timezone:' portal.config.yaml

Должны увидеть ваши значения, не случайный мусор.

---

5. Запустите установку

chmod +x portal-cli/portal-cli
./portal-cli/portal-cli install --mode docker

Установщик по шагам:

1. Читает portal.config.yaml.
2. Создаёт файл .env с секретами (пароли, ключи).
3. Запускает docker compose up -d (поднимает контейнеры).
4. Ждёт, пока ответит проверка здоровья /health.

Первый запуск может занять несколько минут.

Production-профиль (по желанию)

Если нужна повышенная нагрузка (добавляется PgBouncer и связанные настройки):

./portal-cli/portal-cli install --mode docker --prod

Используйте либо обычный install, либо с --prod — не запускайте оба подряд «на всякий случай» без понимания, что уже установлено. Если Portal уже стоит, для обновления используйте upgrade, а не повторный install.

Как проверить, что установка удалась — переходите к §6.

---

6. Проверка: службы живы

Шаг 6.1. Статус через portal-cli

./portal-cli/portal-cli status

Ожидание: команды завершаются без ошибки, контейнеры в рабочем состоянии (не сплошные Exit / Restarting).

Шаг 6.2. Проверка «здоровья» HTTP

curl -sS http://localhost/health
curl -sS http://localhost/api/v1/system/version
curl -sS http://localhost/api/v1/system/license-status

Что значит успех:

Команда	Ожидание
/health	Ответ без ошибки соединения (часто JSON или короткий OK)
/api/v1/system/version	JSON с версией продукта
/license-status	JSON со статусом лицензии (до активации ключа запись может быть ограничена — это нормально)

Если curl: (7) Failed to connect — контейнеры ещё стартуют: подождите 30–60 секунд и повторите. Смотрите также:

docker compose --env-file .env ps
docker compose --env-file .env logs --tail=80

---

7. Первый вход в браузере

Шаг 7.1. Узнайте пароль администратора

Пароль первого админа лежит в файле .env (его создал установщик). Это обычный текстовый файл с переменными ИМЯ=значение.

grep SEED_ADMIN_PASSWORD .env

Скопируйте значение после = — это пароль. Не публикуйте его в чатах и тикетах без необходимости.

Логин по умолчанию: admin (если не меняли seed.adminLogin в конфиге).

Шаг 7.2. Откройте сайт

В браузере откройте:

• http://localhost — если вы на том же компьютере;
• или http://ВАШ_ДОМЕН / IP сервера — как задали в portal.domain.

Войдите: логин admin, пароль из SEED_ADMIN_PASSWORD.

Как проверить успех:

• Открылась главная Portal, вы залогинены.
• На корневом узле есть страница приветствия welcome.
• Списки и библиотеки документов создаёт администратор сам (их может ещё не быть — это нормально).

---

8. Если порты 80/443 заняты или нет прав

Порты 80 и 443 на Linux часто требуют повышенных привилегий. Для пилота можно сменить HTTP-порт.

Откройте .env:

nano .env

Найдите или добавьте:

PORTAL_HTTP_PORT=8080
PORTAL_HTTPS_PORT=8443

Сохраните, пересоздайте стек:

docker compose --env-file .env up -d

Проверка:

curl -sS http://localhost:8080/health

В браузере: http://localhost:8080 (или http://IP:8080).

---

9. Активация лицензии

Без активированного LICENSE.key запись в Portal недоступна (можно смотреть, нельзя полноценно работать). Ключ выдаёт поставщик: коммерческий или trial на 30 дней.

Вариант A — через админку (проще)

1. Войдите как admin.
2. Откройте Админка портала → Настройки → Продукт и лицензия.
3. Скопируйте Привязку (нужна поставщику, чтобы выпустить ключ под вашу инсталляцию).
4. Получите файл LICENSE.key.
5. Загрузите файл или вставьте ключ → нажмите Активировать лицензию.

Права на модули (modules в ключе) отображаются в том же разделе.

Вариант B — через командную строку

Положите LICENSE.key в каталог bundle (или укажите полный путь):

./portal-cli/portal-cli license activate --file LICENSE.key
./portal-cli/portal-cli upgrade --mode docker

Как проверить:

curl -sS http://localhost/api/v1/system/license-status

В админке статус лицензии должен быть действительным. Подробнее: Лицензии и тарифы.

---

10. Внешнее S3 вместо встроенного хранилища (по желанию)

По умолчанию файлы хранит встроенный SeaweedFS. Если нужен корпоративный S3, задайте его до установки в portal.config.yaml (или согласуйте с Внешними сервисами для уже стоящего стенда).

Пример блока storage::

storage:
  endpoint: s3.corp.local
  port: 443
  useSsl: true
  accessKey: portal-rw
  secretKey: "ваш_секрет"
  bucket: portal-files

Либо после генерации .env: очистите COMPOSE_PROFILES (чтобы не поднимать встроенный профиль хранилища) и задайте переменные S3_*. Подробности: Внешние сервисы.

---

11. Часовой пояс

В portal.config.yaml поле portal.timezone установщик записывает в .env как TZ для контейнеров API и Worker.

Модули (бронирование переговорных, дни рождения, службы по расписанию) используют локальное время процесса — оно совпадает с TZ.

Если даты в модулях «сдвинуты»:

1. Проверьте timezone в portal.config.yaml.
2. Проверьте TZ в .env: grep ^TZ= .env.
3. Перезапустите контейнеры:

docker compose --env-file .env up -d --force-recreate backend worker

Пример фрагмента конфига:

portal:
  domain: portal.company.local
  timezone: Europe/Moscow

---

12. Обновление

1. Получите у поставщика новый bundle той же линии (Docker).
2. Сделайте резервную копию (см. админский бэкап).
3. Загрузите новые образы:

docker load -i images/portal-images.tar

4. Из каталога нового bundle (сохранив ваш .env / portal.config.yaml):

./portal-cli/portal-cli upgrade --mode docker

Upgrade применяет миграции БД (db-init) и перезапускает контейнеры.

Обновление из админки (если есть интернет до korport.ru)

1. Поднимите сервис update-runner (при обычной установке он уже в compose):

docker compose --env-file .env up -d update-runner
docker compose --env-file .env ps update-runner

2. В админке: Настройки → Продукт и лицензия → Обновить.

Подробности: Обновление Portal.

Проверка после обновления:

./portal-cli/portal-cli status
curl -sS http://localhost/health
curl -sS http://localhost/api/v1/system/version

Версия должна совпасть с ожидаемой из нового bundle / файла RELEASE.

---

13. Остановка

Остановить контейнеры, данные сохранить:

docker compose --env-file .env down

Остановить и удалить тома с данными (БД и файлы пропадут — необратимо):

docker compose --env-file .env down -v

---

14. Какие файлы за что отвечают

Файл / каталог	Назначение
portal.config.example.yaml	Шаблон конфигурации
portal.config.yaml	Активная конфигурация для установщика
.env	Переменные для Docker Compose (создаётся install)
docker-compose.yml	Описание сервисов
portal-cli/	Команды install / status / upgrade / license
PORTAL_DATA_DIR (в .env)	Каталог данных инсталляции: install.id, license.key

Ключевые переменные лицензии в .env:

• PORTAL_LICENSE_KEY — лицензионный токен;
• PORTAL_LICENSE_FILE — путь к файлу LICENSE.key;
• PORTAL_DATA_DIR — каталог с install.id и сохранённым ключом.

---

15. Разработка расширений (кратко)

WebPart и другие пакеты ставятся в уже работающий Portal (hot deploy). Штатные образы Api/Worker — Production: отладка с брейкпоинтами из IDE внутрь контейнера не входит в поставку. Смотрите логи и цикл переустановки пакета: Отладка расширений.

---

16. Если что-то пошло не так

Симптом	Что сделать
docker: command not found	Установите Docker Engine, повторите §1
Cannot connect to the Docker daemon	Запустите службу Docker / добавьте пользователя в группу docker, перелогиньтесь
/health не отвечает	docker compose --env-file .env ps и logs; подождите старт БД
Не знаете пароль admin	grep SEED_ADMIN_PASSWORD .env
Сайт открывается, но нельзя сохранять	Активируйте LICENSE.key (§9)
Время в модулях «не то»	§11 (timezone / TZ)

Общий разбор: Устранение неполадок.

---

17. Связанные документы

• Какой вариант установки выбрать
• Лицензии и тарифы
• Быстрый старт: Kubernetes
• Portal Office
• Обновление Portal
• Внешние сервисы
• Корпоративный чат