# Soul Stack

[English](../../README.md) · **Русский**

**Душевная система управления конфигурациями нового поколения** — полноценная
платформа, которая приводит ваш парк хостов к нужному состоянию, а не набор
скриптов. Опишите желаемое состояние один раз; центральный **Keeper** держит
долгоживущие mTLS-соединения с агентом `soul` на каждом хосте (ваши **Souls**) и
приводит каждый к его объявленной **Destiny** — и в pull, и в push. Identity,
контроль доступа, аудит, операторский web-UI, REST/MCP API и работа с секретами —
не надстройки, которые докручивают потом, а часть ядра.

[![License: BSL 1.1](https://img.shields.io/badge/license-BSL%201.1%20%E2%86%92%20Apache%202.0-blue)](../../LICENSE)
[![Status: public beta](https://img.shields.io/badge/status-public%20beta-orange)](../known-limitations.md)

> **Публичная бета.** Гарантий стабильности и SLA пока нет. API, схемы, форматы на
> диске и протокол связи могут меняться между бета-релизами. Что **не входит** в
> бету — [docs/known-limitations.md](../known-limitations.md).

## Всё в одной платформе

Soul Stack задуман полным «из коробки» — то, что обычно докручивают отдельно, здесь
часть ядра:

- **Web-UI** — полноценная операторская консоль, а не довесок к CLI.
- **Identity: LDAP / OIDC** — подключите свой каталог или SSO-провайдера напрямую.
- **RBAC** — гранулярные права с deny-by-default, ограниченные по coven / service /
  incarnation.
- **Журнал аудита** — каждое действие оператора фиксируется.
- **REST API (OpenAPI) + MCP** — API это основной интерфейс; CLI — тонкая обёртка, а
  встроенный MCP-сервер позволяет управлять системой AI-агентам.
- **Ротация сертификатов** — mTLS-личность каждого Soul (**SoulSeed**) выпускается и
  ротируется автоматически; ничего не надо класть в cron руками.
- **Наблюдаемость** — метрики Prometheus и трейсы OpenTelemetry в каждом бинаре, плюс
  встроенная ротация логов и hot-reload конфигурации.
- **…и многое другое** — список выше это база, с которой ядро поставляется сегодня, а
  не потолок.

Ничего из этого не заперто за фича-гейтом или пейволом — продукт никогда не урезают,
чтобы продавать «тарифы». На время беты лицензия даёт **внутреннее использование**
(запуск Soul Stack для управления своей или корпоративной инфраструктурой);
использование за этими рамками — например, предложение третьим лицам как
hosted/managed-сервис — требует коммерческой лицензии (см. раздел «Лицензия» ниже).

## Словарь

Метафора «души» пронизывает всю систему — короткий глоссарий:

| Термин | Что это |
|---|---|
| **Keeper** | Control-plane — хранитель, который держит парк вместе. |
| **Souls** | Управляемые агенты, по одному на хост. |
| **Destiny** | Состояние, к которому хост приводится на каждом прогоне. |
| **Soulprint** | Факты о хосте — ОС, ядро, CPU, сеть. |
| **Service vars** | Собственные параметры сервиса по умолчанию, подставляемые в Destiny. |

Если вы работали с системами управления конфигурацией, понятия ложатся
привычно: Keeper — управляющий узел, Souls — агенты на хостах, Destiny —
описание состояния, Soulprint — факты о хосте, service vars — параметры. Полный
словарь — [docs/naming-rules.md](../naming-rules.md).

## Ключевые свойства

- **HA из коробки.** Keeper — горизонтально масштабируемый stateless-кластер поверх
  общих Postgres и Redis. Любой инстанс обслуживает любой запрос; потеря одного не
  прерывает управление вашими Souls.
- **mTLS-личность Soul.** Keeper↔Soul — двунаправленный gRPC-стрим поверх mTLS. Каждый
  Soul онбордится через CSR (приватный ключ не покидает хост) и получает
  короткоживущий сертификат (**SoulSeed**), который ротируется автоматически.
  Управляемые хосты не держат открытых входящих портов — стрим всегда набирает Soul.
- **Vault как единое хранилище секретов.** Все секреты (DSN Postgres, ключ подписи
  JWT, PKI для SoulSeed) живут в Vault; на диск кластера Keeper они не выкладываются.
- **Deny by default.** Доступ оператора (**Archon**) — это JWT + строки прав; ответ по
  умолчанию — «нет».

## Архитектура в одном абзаце

Три бинаря ([ADR-004](../architecture.md)): `keeper` (центральный сервер — gRPC,
OpenAPI, MCP, фоновый Reaper), `soul` (агент-демон на управляемом хосте) и `soul-lint`
(офлайн-линтер артефактов). Стрим всегда инициирует Soul, поэтому у управляемых хостов
нет открытых входящих портов. Холодное состояние кластера живёт в Postgres; горячий
слой (presence, lease, выбор лидера) — в Redis. Обязательный инфраструктурный контур —
**Postgres + Redis + Vault** ([ADR-053](../adr/0053-dependency-tiers.md)).

## Установка

Каждый тег публикует подписанные артефакты на
[страницу релизов](https://github.com/souls-guild/soul-stack/releases); образы
контейнеров уходят в
[Packages](https://github.com/orgs/souls-guild/packages?repo_name=soul-stack). Всё
собирается и подписывается в CI — руками здесь ничего не собрано. В примерах ниже
зафиксирована `0.1.0-beta.1`; актуальный тег смотрите в релизах.

**Образы контейнеров** — `keeper` и `soul`, multi-arch (`linux/amd64` + `linux/arm64`),
distroless. Образы тегируются только версией, тега `latest` нет:

```sh
docker pull ghcr.io/souls-guild/soul-stack/keeper:0.1.0-beta.1
docker pull ghcr.io/souls-guild/soul-stack/soul:0.1.0-beta.1
```

**Нативные пакеты** — `.deb`, `.rpm` и `.apk`, по одному на бинарь, `amd64` и `arm64`.
`keeper` и `soul` несут systemd-юнит, env-файл и пример конфига, поэтому пакет кладёт
готовый к запуску демон:

```sh
curl -fsSLO https://github.com/souls-guild/soul-stack/releases/download/v0.1.0-beta.1/soul-stack-keeper_0.1.0-beta.1_linux_amd64.deb
sudo dpkg -i soul-stack-keeper_0.1.0-beta.1_linux_amd64.deb
```

Вместо `keeper` подставьте `soul`, `soul-lint`, `soulctl`, `soul-trial` или
`soul-legion`.

**Архивы** — `soul-stack_<версия>_<ос>_<арх>.tar.gz` для Linux и macOS, `.zip` для
Windows. Linux-бандл несёт все шесть бинарей; macOS и Windows — только четыре CLI,
поскольку `keeper` и `soul` — это Linux-демоны.

**Проверьте перед запуском.** Артефакты подписаны keyless-[cosign](https://docs.sigstore.dev/)
(GitHub OIDC, без долгоживущего ключа), а к каждому архиву приложен CycloneDX SBOM
(`*.cdx.json`):

```sh
cosign verify-blob checksums.txt \
  --certificate checksums.txt.pem --signature checksums.txt.sig \
  --certificate-identity-regexp '^https://github\.com/souls-guild/soul-stack/\.github/workflows/release\.yml@refs/tags/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
sha256sum --ignore-missing -c checksums.txt

cosign verify ghcr.io/souls-guild/soul-stack/keeper:0.1.0-beta.1 \
  --certificate-identity-regexp '^https://github\.com/souls-guild/soul-stack/\.github/workflows/release\.yml@refs/tags/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
```

Сборка из исходников — [docs/getting-started.md](../getting-started.md).

## С чего начать

- **[docs/install.md](../install.md)** — установка released-бинарей: apt, Homebrew,
  AUR, архивы релиза (с проверкой cosign) и контейнерные образы, плюс заметка про
  карантин macOS.
- **[docs/getting-started.md](../getting-started.md)** — поднять один Keeper и
  инфраструктуру (Postgres + Redis + Vault через `dev/docker-compose.yml`),
  забутстрапить первого Archon, онбордить один Soul и применить простой сценарий.
  ~30 минут.
- **[docs/known-limitations.md](../known-limitations.md)** — что вне рамок беты.
- **[docs/operations/](../operations/README.md)** — операционный runbook для
  production-установки (развёртывание / HA / бэкап / disaster recovery).
- **[docs/architecture.md](../architecture.md)** — обзор архитектуры и ссылки на ADR
  (источник истины по проектным решениям).
- **[docs/README.md](../README.md)** — индекс всей документации.

Готовые примеры Destiny и сервисов («батарейки в комплекте») лежат в
[`examples/destiny/`](../../examples/destiny/) и
[`examples/service/`](../../examples/service/): redis, node-exporter, vector и другие —
реальные раскладки, которые можно копировать.

## AI-ассистенты

PR от AI-ассистентов приветствуются — мы открыты к любому пути, который улучшает Soul
Stack. Но AI может ошибаться: чем бы ни была написана правка, **вы** отвечаете за
проверку её корректности перед отправкой. Две просьбы:

- **Проверяйте то, что присылаете.** Перечитайте и протестируйте изменения до открытия
  PR; не присылайте вывод, который не проверили. Зелёный `make check` и внятное
  описание, *почему* правка верна, сильно помогают.
- **Уважайте процесс проектирования.** Архитектурные решения живут в
  [ADR](../adr/README.md); правка, задевающая дизайн, должна ссылаться на нужный ADR
  или обновлять его, а не обходить.

Правила контрибуции одинаковы для людей и ассистентов — см.
[CONTRIBUTING.md](../../CONTRIBUTING.md).

## Контрибуция

Issues и pull request'ы открыты. Начните с [CONTRIBUTING.md](../../CONTRIBUTING.md) —
там про dev-окружение, гейт `make check`, CLA (подписывается один раз, на первом PR) и
соглашения по коду. Участвуя, вы принимаете
[Кодекс поведения](../../CODE_OF_CONDUCT.md).

## Безопасность и поддержка

- **Уязвимости безопасности** — сообщайте приватно, **не** публичным issue:
  [SECURITY.md](../../SECURITY.md) (`security@soul-stack.com` или приватный
  GitHub-advisory).
- **Баги и неожиданное поведение** —
  [GitHub Issues](https://github.com/souls-guild/soul-stack/issues) (шаблон «Bug
  report»). Приложите вывод `keeper version`.
- **Вопросы и куда написать** — [SUPPORT.md](../../SUPPORT.md). Поддержка в бете —
  best-effort, без SLA.

## Лицензия

Ядро (этот репозиторий) — **[Business Source License 1.1](../../LICENSE)** (fair-code):
исходники открыты, и **production-использование дано для внутреннего использования** —
управление своей или корпоративной инфраструктурой, в том числе коммерческое. Иное
production-использование — предложение Soul Stack третьим лицам как
hosted/managed-сервис или продукт, white-label или встраивание — требует коммерческой
лицензии. Каждая версия автоматически становится
**[Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0)** через два года после
релиза (Change Date), так что ограничение временное, а не постоянное. SDK, `examples/`
и плагины — под Apache 2.0.

Объяснение простым языком, что можно и что нельзя — [LICENSING.md](../../LICENSING.md).
Имя и логотип «Soul Stack» защищены [товарным знаком](../../TRADEMARK.md) отдельно от
лицензии на код.

## Ссылки

- **Сайт:** https://soul-stack.com (обзор, гайды, документация)
- **Документация:** [docs/](../README.md)