Установка и первый запуск

Как скачать готовую поставку, пройти мастер настройки и настроить платформу через админ-панель. Для интеграции приложений см. раздел Public API или быстрый старт.

1. Системные требования

Компонент	Требование
ОС	Linux x86_64 (Ubuntu 20.04+, CentOS 8+ и др.), Windows 10+, macOS 12+
ОЗУ	от 512 МБ (рекомендуется 2 ГБ)
Диск	от 500 МБ свободного места
СУБД	MySQL 8.0+ или PostgreSQL 14+ (можно поднять отдельно или в Docker)

2. Установка и запуск

Рекомендуемый способ для Linux — готовый дистрибутив ядра.

2.1. Скачивание

На сервере доступны релизы 1.0.8–1.0.13. Версии 1.0.0–1.0.7 сняты с публикации; история — в журнале версий.

Debian / Ubuntu (.deb, рекомендуется):

wget https://cascad360.ru/downloads/core/1.0.13/cascad360_1.0.13_amd64.deb
sudo dpkg -i cascad360_1.0.13_amd64.deb
sudo apt-get install -f

Прямая ссылка: cascad360_1.0.13_amd64.deb

Универсальный архив (tar.gz):

wget https://cascad360.ru/downloads/core/1.0.13/cascad360-1.0.13-linux-x86_64.tar.gz

# или
curl -LO https://cascad360.ru/downloads/core/1.0.13/cascad360-1.0.13-linux-x86_64.tar.gz

Прямая ссылка: cascad360-1.0.13-linux-x86_64.tar.gz

2.1.1. Новая установка с медиатекой (два шага)

1. Шаг 1 — ядро 1.0.13: скачайте и установите пакет выше, пройдите мастер ./cascad360 --setup.
2. Шаг 2 — модуль «Медиатека файлов» 1.0.0: скачайте и установите пакет модуля, настройте config.yml — §2.1.2. При обновлении с 1.0.12 — также обновление с 1.0.12.

2.1.2. Установка модуля «Медиатека файлов» 1.0.0

Пакет cascad360-module-files собирается и ставится отдельно от ядра. Выполняйте этот раздел после установки ядра 1.0.13 (§2.1–2.3 или пакет .deb) и при необходимости мастера /setup.

Предусловия: ядро ≥ 1.0.13; типичный каталог установки — /opt/cascad360. Перед обновлением с более ранней версии сделайте backup config.yml и каталога local storage.

Debian / Ubuntu (.deb, рекомендуется):

wget https://cascad360.ru/downloads/modules/cascad360-module-files/1.0.0/cascad360-module-module-files_1.0.0_all.deb
sudo dpkg -i cascad360-module-module-files_1.0.0_all.deb
sudo apt-get install -f

Прямая ссылка: cascad360-module-module-files_1.0.0_all.deb

Пакет размещает модуль в каталоге модулей установки (обычно /opt/cascad360/modules/cascad360-module-files/). Ядро при старте сканирует modules/.

Универсальный архив (tar.gz):

wget https://cascad360.ru/downloads/modules/cascad360-module-files/1.0.0/cascad360-module-module-files-1.0.0.tar.gz

# или
curl -LO https://cascad360.ru/downloads/modules/cascad360-module-files/1.0.0/cascad360-module-module-files-1.0.0.tar.gz

sudo tar xzf cascad360-module-module-files-1.0.0.tar.gz -C /opt/cascad360/modules/
ls /opt/cascad360/modules/cascad360-module-files/module.json

Прямая ссылка: cascad360-module-module-files-1.0.0.tar.gz

Если ядро установлено не в /opt/cascad360, укажите свой каталог: tar xzf … -C /путь/к/cascad360/modules/.

Конфигурация (config.yml в каталоге установки):

modules:
  installed:
    - cascad360-module-files
files:
  enabled: true
storage:
  type: local
  path: /var/lib/cascad360/files

Полный перечень ключей files и storage — в справочнике config.yml. Для S3 задайте storage.type: s3 и bucket в конфиге; ключи доступа — только через переменные окружения (AWS_* / CASCAD360_S3_*), не в git.

Запуск модуля:

1. Перезапуск сервиса: sudo systemctl restart cascad360 (предпочтительно для production).
2. Либо без restart: админка → Модули → Включить для cascad360-module-files (после распаковки tarball на работающем инстансе).

Миграции таблиц модуля выполняются автоматически при старте модуля.

Проверка:

• Админка → раздел Файлы (/admin/files): загрузка и список.
• Files API — upload и delivery для public-файла.

2.2. Распаковка

tar -xzf cascad360-1.0.13-linux-x86_64.tar.gz
cd cascad360

# опционально: установка в /opt
# sudo mv cascad360 /opt/cascad360
# cd /opt/cascad360

2.3. Запуск

Новая установка (рекомендуется в 1.0.7+): сначала мастер первичной настройки:

./cascad360 --setup

# Откройте в браузере (порт по умолчанию — 5050):
# http://localhost:5050/setup

После завершения мастера основное приложение запускается автоматически в фоне — как systemd-сервис cascad360 (при установке от root) или фоновый процесс. Дальнейшее управление — через systemctl (рекомендуется) или команды ./cascad360.

Уже настроенная система — запуск и остановка через systemd:

sudo systemctl start cascad360
sudo systemctl stop cascad360
sudo systemctl status cascad360

Если unit не настроен (локальная отладка без root):

./cascad360 start

# если исполняемый файл в bin/:
# ./bin/cascad360 start

2.4. Управление сервисом (systemd)

После установки и завершения мастера настройки КАСКАД 360 работает как фоновый сервис под управлением systemd. Unit — cascad360.service; при установке от администратора сервера мастер может создать его и включить автозапуск автоматически.

Основные команды (от root или через sudo):

systemctl status cascad360   # статус: running / stopped, последние строки лога
systemctl start cascad360    # запуск сервиса
systemctl stop cascad360     # остановка
systemctl enable cascad360   # автозапуск при загрузке ОС

Команда	Когда использовать
status	Проверить, что платформа запущена и нет ошибок unit
start / stop	Ручной запуск и остановка — перед обновлением, правкой config.yml или диагностикой
enable	Включить автозапуск после перезагрузки сервера (если ещё не включён)

После изменения config.yml перезапустите сервис:

sudo systemctl restart cascad360

Просмотр логов в реальном времени:

journalctl -u cascad360 -f

3. Базовая конфигурация

Основной файл — config.yml в каталоге установки. При первой установке можно скопировать шаблон:

cp config.yml.example config.yml

Минимально полезные параметры перед первым запуском:

app:
  name: Контур
  version: 1.0.13
  distribution: binary       # production: только скомпилированные расширения; dev — для staging
  setup_completed: false
  setup_app_configured: false   # true после шага 3 мастера (1.0.7+)

web:
  host: 0.0.0.0
  port: 5000
  public_port: 5001
  public_api_separate: false   # true — Public API на отдельном порту
  public_api_enabled: true

plugin_ports:
  enabled: false             # true — HTTP-listener'ы плагинов (см. 3.1)

database:
  driver: mysql
  host: localhost
  port: 3306
  database: cascad360
  username: cascad_user
  password: change-me

Параметры подключения к БД можно также указать в мастере настройки (/setup) — тогда правка config.yml не обязательна до первого входа.

3.1. Настройка портов

Порты задаются в config.yml. После изменения перезапустите сервис: sudo systemctl restart cascad360 (см. раздел 2.4).

Порт / диапазон	Параметр	Назначение
5000	web.port	Основной HTTP: админ-панель, служебные функции платформы, шлюз, маршрутизация
5001	web.public_port	Public API — только при public_api_separate: true
8000–8999	plugin_ports	Диапазон HTTP-listener'ов плагинов (при enabled: true)

Основной порт платформы (web)

• port — порт админки и служебные функции платформы (по умолчанию 5000).
• public_api_separate: false — Public API на том же порту (режим по умолчанию, как в 1.0.5).
• public_api_separate: true — служебные функции платформы на port, Public API на public_port; удобно для сетевого разделения контуров.
• public_api_enabled: false — отключить Public API полностью.

# Раздельные порты платформы и Public API
web:
  port: 5000
  public_port: 5001
  public_api_separate: true
  public_api_enabled: true

Порты расширений (plugin_ports, 1.0.6)

Для плагинов с собственным веб-интерфейсом. По умолчанию выключено — ядро остаётся компактным.

plugin_ports:
  enabled: true
  port_range_min: 8000
  port_range_max: 8999
  max_listeners: 10
  reserved_ports: [5000, 5001, 5050]  # порты, которые плагины не могут занять
  auto_start_on_boot: false
  default_host: 0.0.0.0
  hook_timeout_seconds: 30

Управление listener'ами — в админ-панели (раздел плагинов) с правами plugin_ports_view, plugin_ports_manage, plugin_ports_operate.

4. Мастер первичной настройки

При первой установке запустите ./cascad360 --setup и откройте http://localhost:5050/setup. Альтернатива: при setup_completed: false мастер доступен на основном порту — http://localhost:5000/setup.

Мастер выполняется в браузере. С версии 1.0.7 переход между шагами возможен только после реальной готовности предыдущего этапа — индикаторы прогресса отражают фактическое состояние, а не дефолты конфигурации.

1. Подключение к БД — тип (MySQL / PostgreSQL), хост, порт, имя базы, учётные данные. Кнопка «Проверить соединение» обязательна перед переходом к следующему шагу.
2. Администратор — создание первой учётной записи (логин, пароль, email). Жёсткого дефолтного пароля нет.
3. Параметры приложения — название контура и базовые настройки. После сохранения выставляется app.setup_app_configured: true.

Когда все три шага выполнены, становится активной кнопка «Завершить настройку». После нажатия:

• конфигурация сохраняется (app.setup_completed: true);
• система пытается запустить основное приложение — через systemctl start cascad360 (при root + systemd), установку unit с enable --now или фоновый процесс ./cascad360;
• при недоступном автозапуске вы получите чёткую команду для ручного запуска — без перехода на страницу, которая ещё не работает;
• после успешного запуска откроется страница входа на основном порту: http://localhost:5000/login.

После завершения откройте http://localhost:5000 и войдите с учётной записью, созданной на шаге 2.

13. Проверка установки

Убедитесь, что платформа работает:

1. Убедитесь, что сервис запущен: systemctl status cascad360 — состояние active (running) (см. раздел 2.4).
2. Убедитесь, что в config.yml установлено app.setup_completed: true.
3. Откройте http://localhost:5000/login и войдите с учётной записью администратора.
4. На главной странице панели проверьте, что статус системы отображается без ошибок.
5. Откройте БД ядра — должны отображаться таблицы основной базы.
6. Откройте Студия БД — выберите основную базу ядра, переключите таблицу и убедитесь, что данные обновляются корректно.
7. Откройте Public Swagger UI (/api/docs/public) — проверьте доступность OpenAPI spec.
8. Откройте Настройки → Почта — выполните тестовую отправку; проверьте health почты (статус ok после настройки SMTP).
9. Откройте Настройки → Public Auth — проверьте URL подтверждения email и параметры lockout.
10. Откройте Почта → Шаблоны — убедитесь, что есть system.auth.verify_email.
11. Откройте Сервисы и Маршрутизация — добавьте тестовый backend или проверьте существующие записи.
12. Откройте API-ключи — у service-ключей указаны связанный сервис и whitelist сущностей.
13. Откройте Плагины — проверьте lifecycle, логи и метрики для optional-плагинов.
14. Если установлен модуль «Медиатека файлов» 1.0.0 — откройте раздел Файлы, проверьте загрузку и список.
15. Опционально: проверка health-check с командной строки:

curl http://localhost:5000/api/health
# Ожидаемый ответ: {"status":"ok","version":"1.0.13", ...}