# Конфигурация проекта workspaces-api

Документ описывает все переменные окружения и способы конфигурирования сервиса.

## Способы конфигурирования

Сервис настраивается **только через переменные окружения**. Разбор выполняется в `config/config.go` через библиотеку [`envconfig`](https://github.com/kelseyhightower/envconfig) (функция `config.FromEnv()`). Отдельного конфиг-файла (yaml/toml) у приложения нет.

Источники переменных по способам запуска:

| Способ запуска | Откуда берутся переменные |
| --- | --- |
| Локально (docker-compose) | Файл `.env` в корне (`env_file: .env`); поднимает только контейнер Postgres, сам API-сервис в compose закомментирован |
| Локально (бинарник) | Переменные окружения процесса; пример значений — в `.env`, приватные — в `.private.env` (см. `.private.env.example`) |
| Kubernetes (Helm) | `.helm/values.yaml`: блок `envs` (обычные значения) и `secretEnvs` (значения из k8s-секретов) |
| CI/CD (GitLab) | `.gitlab-ci.yml`: переменные пайплайна и build-args для сборки образа |

Порядок запуска в контейнере (`entrypoint.sh`): сначала выполняются миграции (`/migrations migrate`), затем стартует API (`/api`).

## Переменные приложения (`config.Config`)

Читаются напрямую по имени. Пустые обязательные значения не приводят к ошибке старта (envconfig не помечает их как required) — но без корректных значений БД/documentation сервис работать не будет.

| Переменная | Тип | Значение по умолчанию | Назначение |
| --- | --- | --- | --- |
| `POSTGRES_ADDRESS` | string | — | Хост PostgreSQL |
| `POSTGRES_PORT` | string | — | Порт PostgreSQL |
| `POSTGRES_USER` | string | — | Пользователь БД |
| `POSTGRES_PASSWORD` | string | — | Пароль пользователя БД |
| `POSTGRES_DB` | string | — | Имя базы данных |
| `POSTGRES_POOL_SIZE` | int | `0` | Размер пула соединений к БД |
| `API_ADDRESS` | string | — | Адрес прослушивания HTTP-сервера (`host:port`), напр. `0.0.0.0:8000` |
| `DOCUMENTATION_HOST` | string | — | Базовый URL сервиса документации (documentation service) |
| `DOCUMENTATION_ORIGINATOR` | string | — | Идентификатор источника, передаваемый в сервис документации |
| `DOCUMENTATION_LOGGER_FEATURE` | bool | `false` | Включает фичу логирования обращений к сервису документации |
| `SENTRY_DSN` | string | — | DSN для отправки ошибок в Sentry |
| `SENTRY_DEBUG` | bool | `false` | Debug-режим Sentry |
| `ENVIRONMENT` | string | — | Имя окружения (передаётся в Sentry как environment) |
| `BUNDLES_RETRY_COUNT` | int | `3` | Кол-во ретраев клиента bundles (если задано `<= 0`, берётся `3`) |
| `BUNDLES_NJOBS` | int | `3` | Кол-во параллельных задач при работе с bundles (если `<= 0`, берётся `3`) |
| `ENABLE_SQL_QUERY` | bool | `false` | Логировать SQL-запросы (добавляет query-hook в go-pg) |
| `YC-PG-CERTIFICATE` | string | — | Содержимое (PEM) CA-сертификата PostgreSQL; используется при `ENABLE_SSL=1` |
| `ENABLE_SSL` | bool | `false` | Подключаться к PostgreSQL по TLS с проверкой по `YC-PG-CERTIFICATE` |
| `TRACER_USE` | bool | `false` | Включает OpenTelemetry-трейсинг и otel-логгер |
| `TRACER_HOST` | string | `localhost:4317` | Адрес OTLP-коллектора |
| `SERVICE_NAME` | string | `workspaces` | Имя сервиса в трейсах |
| `TRACER_USE_INSECURE` | bool | `true` | Небезопасное (без TLS) подключение к коллектору |
| `TRACER_LOGGER_NAME` | string | `tracer_logger` | Имя otel-логгера |

> Тип `bool` в envconfig принимает `1`/`0`, `true`/`false`, `t`/`f` и т.п.

## Переменные инфраструктуры, сборки и вспомогательных утилит

Не читаются основным кодом приложения, но участвуют в запуске/сборке/деплое.

| Переменная | Где используется | Назначение |
| --- | --- | --- |
| `POSTGRES_EXTERNAL_PORT` | `docker-compose.yml` | Внешний порт проброса контейнера Postgres |
| `API_PORT` | `.env`, `docker-compose.yml` (закомментированный сервис) | Порт API при локальном запуске в контейнере |
| `FAKE_API_ADDRESS` | `fake_bundle_api/main.go` | Адрес фейкового bundle-API (только для локальной разработки/тестов) |
| `GITLAB_CREDENTIALS` | `api.Dockerfile` (build-arg) | Креды `https://<user>:<token>@gitlab.sarex.io` для доступа к приватным Go-модулям при сборке |
| `CI_COMMIT_SHORT_SHA` | `api.Dockerfile` (build-arg) → `APP_VERSION` | Версия/хэш коммита, зашиваемая в бинарь при сборке (`make api`) |
| `APP_VERSION` | `Makefile` (`make api`) | Версия приложения при сборке |

## Переменные из Helm-чарта (`.helm/values.yaml`)

Обычные переменные (`envs`) — переопределяют дефолты по окружениям (`_default`/`stage`/`preprod`/`production`):

| Переменная | Значение `_default` | Примечание |
| --- | --- | --- |
| `POSTGRES_POOL_SIZE` | `3` | |
| `BUNDLES_RETRY_COUNT` | `5` | |
| `BUNDLES_NJOBS` | `5` | |
| `API_ADDRESS` | `0.0.0.0:8000` | В preprod/production — порт `8080` |
| `NAMESPACE` | `workspaces` | Задаётся в чарте, но **кодом приложения не читается** |
| `ENABLE_SQL_QUERY` | `0` | |
| `ENABLE_SSL` | `1` | |
| `DOCUMENTATION_HOST` | `http://documentations-api-svc.documentations:8000` | Зависит от окружения |
| `DOCUMENTATION_LOGGER_FEATURE` | `0` | |
| `DOCUMENTATION_ORIGINATOR` | `stage_ws` | В prod — `prod_ws` |
| `SENTRY_DSN` | `https://…@o279218.ingest.sentry.io/6229949` | |
| `SENTRY_DEBUG` | `0` | |
| `ENVIRONMENT` | `stage` | В prod — `prod` |
| `TRACER_USE` | `1` | |
| `TRACER_HOST` | `signoz-otel-collector.signoz.svc.cluster.local:4317` | Зависит от окружения |
| `SERVICE_NAME` | `workspaces-api.platform` | Зависит от окружения |
| `TRACER_USE_INSECURE` | `1` | |
| `INTERNAL_PATH` | `/internal/` | Задаётся в чарте, но **кодом приложения не читается** |

Переменные из секретов (`secretEnvs`, секрет `workspaces-postgresql-secret` / `ya-pg-secret`):

| Переменная | Ключ секрета |
| --- | --- |
| `POSTGRES_USER` | `username` |
| `POSTGRES_PASSWORD` | `password` |
| `YC-PG-CERTIFICATE` | `ca.crt` |
| `POSTGRES_ADDRESS` | `host` |
| `POSTGRES_PORT` | `port` |
| `POSTGRES_DB` | `database` |

## JWT-ключи

RSA-ключи для JWT лежат в `.pub_keys/` и при сборке образа копируются в `/etc/sarex/keys` (см. `api.Dockerfile`). Пути к ключам передаются в функции работы с токенами (`pkg/gotools/auth/jwt.go`) как аргументы, отдельной переменной окружения для пути к ключам в текущем коде нет.

## Замечания и потенциальные проблемы

- В файле `.env` переменная названа `POSTGRES_POLL_SIZE` (опечатка), тогда как код читает `POSTGRES_POOL_SIZE`. При локальном запуске из `.env` размер пула не применится и останется `0`.
- Имя переменной `YC-PG-CERTIFICATE` содержит дефисы — envconfig сопоставляет её по точному совпадению тега.
- В `.helm/values.yaml` у `secretEnvs.POSTGRES_PORT` значение `_default.secretName` указано как `a-pg-secret` (похоже на опечатку, ожидается `ya-pg-secret`/`workspaces-postgresql-secret`).
- Переменные `NAMESPACE` и `INTERNAL_PATH` задаются в Helm-чарте, но не используются в коде приложения.

## Минимальный набор для локального запуска

Для запуска сервиса локально (Postgres — через docker-compose, API — бинарником) нужно задать:

- `POSTGRES_ADDRESS`, `POSTGRES_PORT`, `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`
- `API_ADDRESS` (напр. `0.0.0.0:6666`)
- `DOCUMENTATION_HOST`, `DOCUMENTATION_ORIGINATOR`
- `ENVIRONMENT` (напр. `local`)
- при необходимости — `SENTRY_DSN`, `ENABLE_SQL_QUERY`

См. пример значений в `.env`.