ermnvldmr.com/services/docs/content/ru/apex/guides/service-composition.md

title, description, weight

title	description	weight
Добавление композиции сервисов	Подключите новый проект к узлу: якорный IP, сети, уровни и линтинг.	23

Контекст: проект присоединяется к узлу как один каталог в compositions/, содержащий написанный вручную файл compose. Контракт фреймворка для этого файла невелик: статический якорный IP в сети direct, ссылки на внешние сети по ключу и пути к данным относительно уровней.

{{% steps %}}

Выделите якорный адрес

Выберите следующий свободный адрес .20 или выше в /24 узла и запишите его в compositions/ADDRESSING.md. Адреса .10–.19 зарезервированы для базовой композиции (см. Concept: Fleet addressing scheme).

Напишите файл compose

name: <project>
services:
  <anchor>:
    image: ...
    container_name: <project>-<anchor>
    user: "${APEX_UID?error}:${APEX_GID?error}"
    group_add:
      - "${APEX_SHARED_GID?error}"
    volumes:
      - ./@tier1/<anchor>/config:/config
      - ./@tier2/<anchor>/data:/data
    networks:
      direct:
        ipv4_address: 198.18.16.20
      enclave: {}
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.<project>.rule=Host(`...`)"
      - "traefik.http.services.<project>.loadbalancer.server.port=8080"
      # намерение резервного копирования (resticontainer, определяется из меток restic.*)
      - "restic.enable=true"
      - "restic.backup.paths=/config"
    restart: unless-stopped

  <sidecar>:
    image: ...
    network_mode: "service:<anchor>"

networks:
  direct:
    external: true
  enclave:
    external: true

Применяемые соглашения:

• Один якорь на проект держит статический ipv4_address в direct; sidecar-контейнеры разделяют его сетевое пространство имён через network_mode: service:<anchor>.
• На сети ссылаются по ключу (direct, enclave, socket) с external: true — их определения принадлежат базовой композиции.
• Членство в enclave плюс метки traefik публикуют сервис через граничный прокси; прокси обнаруживает его через socket-прокси, никогда через опубликованные порты.
• Пути к данным относительны уровням (./@tierN/...) и разрешаются через симлинки, создаваемые tiers/link.
• Резервное копирование включается по выбору через метки restic.*. apex backup/run управляет resticontainer, который определяет, что снимать, из меток compose: restic.enable=true помечает сервис, restic.backup.paths=<container-path> называет монтирования для резервного копирования (resticontainer разрешает их в пути хоста). Сервис без меток restic.* просто не резервируется. Резервируйте конфигурацию только там, где данные восстановимы.
• Тройка ${APEX_UID...} берётся из .env проекта, поддерживаемого tiers/useradd.

Обеспечьте хранилище и идентичность

apex tiers/link <tier1> <tier2> <tier3>
apex tiers/useradd
apex tiers/chown

Повторный запуск тройки идемпотентен; он подхватывает новый проект, создаёт его каталоги уровней и .env, обеспечивает его пользователя noroot-<project> и применяет матрицу владения.

Линтинг

apex utils/lint-docker-compose

Проверяет каждый якорный IP (корректность формы, уникальность, нахождение внутри подсети узла) и запускает линтер compose по репозиторию. Pre-commit-хук обеспечивает тот же линтинг для staged-файлов compose.

Разверните

apex compose up

Базовая композиция уже поднята; новый проект стартует в своём алфавитном слоте. Проверьте с помощью docker ps и, если сервис проксируется, через его маршрут на границе.

{{% /steps %}}

Заметки

• Внутренние секреты сервиса (например, пароль базы данных) размещаются в собственном .env проекта в хранилище уровня 1, рядом с автоматически внедряемым блоком UID.
• Никогда не определяйте direct/enclave/socket внутри файла проекта — второе определение будет конкурировать с базовой композицией за владение сетью.

---

См. также:

• Concept: Compositions and the shared core
• Concept: Tiered storage and privilege isolation
• Concept: Fleet addressing scheme