Запуск с Docker Compose

Для большинства самый быстрый способ увидеть работающий сервер авторизации — Compose-файл, который поставляется с репозиторием. Он поднимает три сервиса: MongoDB, одноразовый шаг провижининга и сам сервер. Настраивать ничего не нужно, кроме одного значения, о котором речь ниже.

Требования: Docker с Compose v2 (docker compose, а не старый docker-compose).

Запуск

1. Скачайте Compose-файл:

   curl -O https://raw.githubusercontent.com/RedFox-Soft/OAuth-server.ts/main/docker-compose.yml

2. Определитесь со значением ISSUER сейчас — почему, объясняет предупреждение ниже. Если браузер будет обращаться к серверу не по адресу http://localhost:3000, измените его в обоих блоках environment: файла docker-compose.yml — в сервисе setup и в сервисе oauth. Если изменить только один, redirect URI, записанный при начальном заполнении, и объявленный issuer разойдутся, а это именно то расхождение, которое, как сказано в предупреждении ниже, нельзя исправить на месте.

3. Запустите всё:

   docker compose up

4. Откройте консоль по адресу http://localhost:3000/admin. При первом посещении показывается одноразовый экран настройки, на котором создаётся первый суперадминистратор.

Что делают три сервиса

Сервис	Образ	Роль
mongo	mongo:8	Хранилище данных на именованном томе mongo-data с healthcheck через пинг mongosh, которого ждут остальные сервисы
setup	ghcr.io/redfox-soft/oauth-server-ts:latest	Выполняет bun run db:setup и bun run db:migrate, затем завершается: коллекции, индексы, начальный ключ подписи RS256, начальные данные панели администратора и все миграции схемы
oauth	ghcr.io/redfox-soft/oauth-server-ts:latest	Сам сервер на порту 3000; запускается только после успешного завершения setup

Порядок важен. Без зарезервированного проекта администрирования, бакета и клиента admin-panel, которые создаёт setup, вход в консоль перенаправляет на клиент, которому не соответствует ни один документ Client. Страница первоначальной настройки в таком состоянии всё равно работает, и из-за этого проблема может выглядеть как ошибка входа. Кроме того, сервер отказывается запускаться с базой данных, миграции которой не применены, поэтому setup выполняет db:migrate после db:setup. Обе команды можно безопасно запускать повторно, так что повторный docker compose up после загрузки более нового образа — это и есть путь обновления; сначала сделайте резервную копию, если в примечаниях к релизу названа миграция, которую нельзя отменить.

Задайте ISSUER до первого docker compose up

ISSUER должен быть URL, по которому браузер обращается к серверу, и его значение должно быть окончательным до первого up. Redirect URI клиента администратора из начальных данных выводится из него один раз, через $setOnInsert, и последующее изменение не исправляется повторным запуском db:setup.

Если вы уже запустили сервер с неверным значением, обходной путь — удалить хранилище данных и начать заново:

docker compose down -v   # removes the mongo-data volume
# edit ISSUER in docker-compose.yml
docker compose up

Учтите, что при этом уничтожаются все учётные записи, клиенты и ключи подписи в этом томе, так что это решение только для первого дня. В развёртывании, где уже есть данные, через консоль это не исправить: зарезервированный клиент администратора — единственный клиент, который консоль не даёт изменить. Поэтому ISSUER должен быть верным до первого запуска.

Что дальше

• Консоль по адресу http://localhost:3000/admin, где вы создаёте первого администратора.
• Документ discovery — авторитетный список URL эндпоинтов для клиентской библиотеки: http://localhost:3000/.well-known/openid-configuration.
• Набор ключей: http://localhost:3000/jwks.
• Проба liveness, на которую никогда не действует ограничение частоты запросов: http://localhost:3000/health, и её пара для readiness http://localhost:3000/ready, которая также обращается к базе данных.

Этот файл запускает MongoDB. Лежащий рядом docker-compose.postgres.yml — те же три сервиса на PostgreSQL, они запускаются командой docker compose -f docker-compose.postgres.yml up. Это альтернативы, и они никогда не комбинируются. Какая переменная выбирает какую базу данных, см. в разделе PostgreSQL.

Compose-файл, ориентированный на продакшен, — с закреплёнными тегами, внешней базой данных и TLS-прокси перед сервером — описан в разделе Развёртывание с Docker Compose.