Быстрый старт¶

Сервер Alatyr на одной машине с Docker — за несколько минут и одной командой. Вы скачиваете архив выпуска, запускаете ./first-up.sh, и он сам придумывает все секреты, заводит собственный удостоверяющий центр (УЦ), поднимает сервер и печатает адрес админки с паролем администратора.

Этот путь подходит для пилота и для знакомства с продуктом. Рабочая установка со своим Vault, Keycloak или в Kubernetes — на странице Установка.

flowchart LR
    Archive["Архив выпуска<br/>alatyr-deploy-&lt;версия&gt;.tar.gz"] --> FirstUp["./first-up.sh"]
    FirstUp --> Env[".env с секретами<br/>(права 600)"]
    FirstUp --> Stack["Docker Compose:<br/>PostgreSQL, Vault с УЦ,<br/>сервер, админка"]
    Stack --> Admin["Один https-вход:<br/>админка и API агентов<br/>https://&lt;адрес&gt;:8443"]
    Stack --> Crl["Списки отзыва<br/>и сертификаты УЦ<br/>:8200"]

1. Что нужно заранее¶

Что	Требование
Машина	Linux, 2 ядра, 2 ГБ памяти, 20 ГБ диска (рекомендуется 4 ядра и 4 ГБ) — подробнее в Расчёте ресурсов
Docker	24.0 или новее, Docker Compose 2.20 или новее, `docker compose` подкомандой (не отдельный `docker-compose`); команды — от пользователя с доступом к Docker
Интернет	исходящий доступ к Docker Hub: образы `s3m4rgl/alatyr-server` и `s3m4rgl/alatyr-frontend` скачиваются при первом запуске
Свободные порты	`8443` — один https-вход: админка и API агентов, `3000` — HTTP, перенаправляет на `8443`, `8090` — прямой API (только с самой машины), `8200` — списки отзыва и сертификаты УЦ для агентов
Сеть	`8443` и `8200` открыты из сети, где стоят машины сотрудников
Время	синхронизировано (`timedatectl status`)

2. Скачайте архив выпуска¶

Все файлы выпуска — на странице последнего выпуска. Сервер поднимается из архива alatyr-deploy-<версия>.tar.gz. Рядом с ним выложены docker-compose.yml и env.example из того же архива — их можно посмотреть до скачивания. В архиве второй файл называется .env.example: имя с точкой в начале страница выпуска не принимает.

VER=1.6.1      # номер выпуска со страницы выпуска
curl -fLO https://github.com/s3m4rgl/alatyr-docs/releases/download/v$VER/alatyr-deploy-$VER.tar.gz
sha256sum alatyr-deploy-$VER.tar.gz

Сверьте напечатанную сумму с разделом «Контрольные суммы» на странице выпуска. Не совпала — архив повреждён или подменён, не распаковывайте его.

Версия образов сервера уже вписана в архив: набор и образы приходят парой, выбирать тег не нужно.

3. Распакуйте и запустите¶

tar -xzf alatyr-deploy-$VER.tar.gz
cd alatyr-deploy-$VER
./first-up.sh

Что делает first-up.sh:

Проверяет, свободны ли порты 8443, 3000, 8090, 8200 (8090 нужен только на самой машине). Если порт занят другой программой, сценарий ничего не запускает и называет порт и переменную, которой его поменять.
Заводит .env из .env.example и придумывает недостающие секреты: пароли базы и администратора, ключи подписи и шифрования. Файл получает права 600.
Вписывает адрес машины, по которому агенты будут забирать списки отзыва (ALATYR_PKI_PUBLIC_ADDR). Если у машины один адрес — подставляет его сам, если несколько — спрашивает, какой из них видят агенты. Этот адрес попадает внутрь каждого выданного сертификата, поэтому выберите его внимательно: смена потом требует перевыпуска уже выданных сертификатов. Только адрес, открывающийся с машин сотрудников, — внутреннее имя набор не запишет вовсе (Адрес PKI в сертификатах). Для DNS-имени — флаг: ./first-up.sh --pki-addr alatyr.example.com.
Скачивает образы и поднимает состав: PostgreSQL, Vault с корневым УЦ Alatyr Root CA и промежуточными УЦ для целей, сервер и админку за HTTPS. Сертификат админки выпускается на имя и IP-адреса машины.
Дожидается сервера и печатает один блок «ЗАПИШИТЕ ЭТО СЕЙЧАС»: адрес админки, отпечаток SHA-256 корня Alatyr Root CA, логин и пароль администратора, доступ к базе и где лежит ключ распечатывания Vault.

Блок печатается один раз

Сохраните его сразу в надёжное место. Повторный запуск ./first-up.sh секреты не печатает и не меняет — они остаются в .env.

Свои логин и пароль администратора можно задать до первого запуска: cp .env.example .env, впишите ALATYR_ADMIN_EMAIL и ALATYR_ADMIN_PASSWORD, затем ./first-up.sh. Сценарий заполняет только пустые значения. Пароль — не короче 8 символов, с заглавной буквой, строчной и цифрой.

4. Проверьте, что поднялось¶

Из каталога набора:

docker compose ps -a
curl -s http://localhost:8090/health
curl -s http://localhost:8090/api/v1/version

Все службы — в состоянии healthy, одноразовые vault-init и issuers-init завершились с кодом 0, а сервер отвечает своей версией.

Если сервер не поднялся, first-up.sh вместо блока «ЗАПИШИТЕ» печатает хвост журнала сервера и выходит с кодом 1. Журнал целиком — docker compose logs server.

5. Войдите в админку¶

Добавьте корень Alatyr Root CA в доверенные корневые сертификаты браузера или системы. Скачать его можно по ссылке из блока, вида http://<адрес>:8200/v1/pki/ca/pem. Перед установкой сверьте отпечаток SHA-256 с напечатанным в блоке. Без этого шага браузер предупредит о сертификате.
Откройте адрес админки из блока — https://<адрес машины>:8443.
Войдите логином и паролем администратора из блока.

Результат. Вы в админке, внизу боковой панели — ваша учётная запись с ролью «Администратор».

Пароль верный, а вход не проходит

Админка открыта по имени, которого нет в списке имён сертификата, или по http://. Откройте её по адресу https://… из блока. Нужно другое имя — допишите его в ALATYR_TLS_NAMES в .env и повторите ./first-up.sh.

6. Смените пароль администратора¶

Внизу боковой панели под вашей учётной записью — кнопка «Сменить пароль». Смените пароль сразу после первого входа: прежнее значение остаётся в .env на диске. После первого запуска пароль меняется только в админке — правка .env на него уже не влияет.

Забыли пароль — сбросьте его с машины сервера, из каталога набора:

docker compose exec server alatyr-server reset-admin-password --email admin@example.com

Новый пароль печатается один раз; все прежние сессии перестают действовать.

Что дальше¶

Установка поднимается пустой: в ней только администратор. Дальше —

Первые шаги в админке: издатели целей, политика выдачи, назначение целей устройствам — раздел «Первые шаги после запуска» в README.md архива и маршрут пилота Пилот: с чего начать.
Агенты на устройства сотрудников: Установка → Агент и Агенты. Агенту при установке дают адрес API, а не админки, и с портом: https://<имя машины>:8443 — один https-вход набора, на нём и админка, и API агентов. Адрес без порта ведёт на порт 443, где в такой установке ничего не слушает. Если перед API поставлен ваш обратный прокси с TLS — давайте адрес прокси.
Все настройки сервера и переменные .env — Конфигурация.
Перед рабочей эксплуатацией: ваши PostgreSQL и Vault вместо встроенных (Своё или внешнее), своё доменное имя или свой сертификат для https-входа (Установка), резервная копия тома vault_data — Установка и Отказоустойчивость (HA).

Обновление¶

Новая версия ставится из архива нового выпуска по инструкции UPGRADE.md внутри него. Коротко: сначала резервная копия базы и Vault — миграции базы назад не откатываются, — затем файлы набора новой версии, ./migrate-env.sh (с 1.6.0 — обязательно, до смены версии), новая версия в .env, затем подъём. Данные, настройки и выданные сертификаты сохраняются.

С 1.6.1 прямой http API отвечает только с самой машины

После обновления порт 8090 слушает 127.0.0.1, а агент 1.6.1 не ходит по http к другой машине. Если агенты настроены на http://<адрес>:8090:

до обновления сервера задайте в .env ALATYR_API_BIND=0.0.0.0 — иначе эти агенты теряют связь с сервером сразу после его обновления (сервер уже обновлён — то же, затем docker compose up -d);
обновите сервер — ./first-up.sh печатает отпечаток корня;
обновите агентов до 1.6.1 сразу с адресом https://<имя>:8443 и ALATYR_CA_FINGERPRINT=<отпечаток> — переданные при обновлении значения заменяют прежние;
когда все агенты на https, верните ALATYR_API_BIND=127.0.0.1 и выполните docker compose up -d.

Пока ALATYR_API_BIND=0.0.0.0, порт 8090 открыт сети и данные агентов идут открытым текстом. Подробности — UPGRADE.md набора.

Остановка и удаление¶

Из каталога набора:

docker compose down        # остановить, данные сохранить
docker compose up -d       # запустить снова
docker compose down -v     # остановить и УДАЛИТЬ базу и Vault целиком

down -v необратим

Вместе с томом vault_data исчезает корень УЦ: все выданные сертификаты становится нечем проверять и отзывать.