Змінні середовища

DocPlatform зчитує конфігурацію зі змінних середовища. Встановіть їх в оболонці, у файлі .env в робочій директорії або в оркестраторі контейнерів.

Сервер

Змінна За замовчуванням Опис
PORT 3000 HTTP порт прослуховування
HOST 0.0.0.0 HTTP адреса прослуховування. Встановіть 127.0.0.1, щоб обмежити лише localhost.
DATA_DIR .docplatform Коренева директорія для всіх даних DocPlatform (база даних, резервні копії, робочі простори, ключі)
BASE_DOMAIN — Власний домен для опублікованої документації (наприклад, docs.yourcompany.com). Коли встановлено, опублікована документація використовує цей домен для канонічних URL та записів sitemap.
PUBLISH_REQUIRE_AUTH false Коли true, усі опубліковані документаційні сайти вимагають, щоб відвідувач був автентифікований як учасник робочого простору. Неавтентифіковані відвідувачі перенаправляються на сторінку входу та повертаються на оригінальну сторінку після входу.

Автентифікація

Змінна За замовчуванням Опис
JWT_SECRET_PATH {DATA_DIR}/jwt-key.pem Шлях до приватного ключа RS256 для підпису JWT. Автоматично генерується при першому запуску, якщо відсутній.
JWT_ACCESS_TTL 900 Час життя токена доступу в секундах (за замовчуванням: 15 хвилин)
JWT_REFRESH_TTL 2592000 Час життя токена оновлення в секундах (за замовчуванням: 30 днів)

OIDC провайдери (опціонально)

Увімкніть вхід через Google та/або GitHub, встановивши ці змінні. Якщо не встановлено, доступна лише локальна автентифікація (email + пароль).

Змінна За замовчуванням Опис
OIDC_GOOGLE_CLIENT_ID — Google OAuth 2.0 client ID
OIDC_GOOGLE_CLIENT_SECRET — Google OAuth 2.0 client secret
OIDC_GITHUB_CLIENT_ID — GitHub OAuth client ID
OIDC_GITHUB_CLIENT_SECRET — GitHub OAuth client secret

Див. Автентифікація для інструкцій з налаштування.

Git

Змінна За замовчуванням Опис
GIT_SSH_KEY_PATH ~/.ssh/docplatform_deploy_key Шлях до приватного SSH ключа для git операцій. Необхідний для приватних репозиторіїв через SSH.
GIT_SYNC_INTERVAL 300 Інтервал polling за замовчуванням у секундах для віддаленої синхронізації (мінімум: 10). Перевизначається значенням sync_interval окремого робочого простору. Встановіть 0 для синхронізації лише через webhook (без polling).
GIT_AUTO_COMMIT true Поведінка автоматичної фіксації за замовчуванням. Перевизначається значенням git_auto_commit окремого робочого простору.
GIT_WEBHOOK_SECRET — Спільний секрет для перевірки webhook payload (HMAC-SHA256) від GitHub, GitLab або Bitbucket.
GIT_COMMIT_NAME DocPlatform Ім’я committer для автоматичних комітів
GIT_COMMIT_EMAIL docplatform@local Email committer для автоматичних комітів

Email (опціонально)

Налаштуйте SMTP для запрошень до робочих просторів та email-листів скидання пароля. Без SMTP токени виводяться в stdout (логи сервера).

Змінна За замовчуванням Опис
SMTP_HOST — Ім’я хоста SMTP сервера (наприклад, smtp.gmail.com)
SMTP_PORT 587 SMTP порт (587 для STARTTLS, 465 для SSL)
SMTP_FROM — Адреса електронної пошти відправника (наприклад, [email protected])
SMTP_USERNAME — Ім’я користувача для автентифікації SMTP
SMTP_PASSWORD — Пароль для автентифікації SMTP

Резервне копіювання

Змінна За замовчуванням Опис
BACKUP_ENABLED true Увімкнути щоденне автоматичне резервне копіювання SQLite
BACKUP_RETENTION_DAYS 7 Кількість днів зберігання файлів резервних копій. Старіші резервні копії видаляються автоматично.
BACKUP_DIR {DATA_DIR}/backups Директорія для файлів резервних копій

Телеметрія

Змінна За замовчуванням Опис
DOCPLATFORM_TELEMETRY off Встановіть on, щоб увімкнути анонімні, опціональні метрики використання. Коли увімкнено, SHA-256 ідентифікатор інсталяції (без персональної інформації) надсилається щотижня.
DOCPLATFORM_TELEMETRY_ENDPOINT — Власний ендпоінт для даних телеметрії (розширене — для ізольованих середовищ із внутрішньою аналітикою)

Що надсилає телеметрія (коли увімкнена)

  • SHA-256 ідентифікатор інсталяції (отриманий з директорії даних, незворотний)
  • Кількість робочих просторів та загальна кількість сторінок
  • Версія DocPlatform
  • ОС та архітектура

Телеметрія ніколи не надсилає: контент сторінок, email користувачів, IP-адреси, імена файлів або будь-яку персональну інформацію. Частота: щотижня.

Обробка frontmatter

Змінна За замовчуванням Опис
FRONTMATTER_ERROR_MODE strict Як обробляти некоректний YAML frontmatter: strict обмежує сторінку доступом лише для адміністраторів (запобігає випадковому розкриттю); lenient зберігає останній відомий коректний frontmatter та показує попередження.

Використання файлу .env

Створіть файл .env у директорії, де ви запускаєте docplatform serve:

# .env
PORT=8080
DATA_DIR=/var/lib/docplatform
GIT_SSH_KEY_PATH=/etc/docplatform/deploy_key
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_FROM=[email protected]
SMTP_USERNAME=[email protected]
SMTP_PASSWORD=app-specific-password
BACKUP_RETENTION_DAYS=30

DocPlatform завантажує файл .env автоматично. Змінні середовища, встановлені в оболонці, мають пріоритет над значеннями .env.

Docker середовище

Передавайте змінні середовища в Docker через прапорці -e або файл env:

docker run -d \
  --name docplatform \
  -p 3000:3000 \
  -v docplatform-data:/data \
  -e DATA_DIR=/data \
  -e SMTP_HOST=smtp.example.com \
  -e SMTP_FROM=[email protected] \
  --env-file .env.production \
  ghcr.io/valoryx-org/docplatform:latest

Примітки щодо безпеки

  • Ніколи не фіксуйте файли .env у системі контролю версій. Додайте .env до вашого .gitignore.
  • JWT ключі генеруються автоматично. Якщо потрібно змінити, видаліть файл ключа та перезапустіть — новий ключ буде згенеровано, і всі наявні сесії будуть інвалідовані.
  • Паролі SMTP — використовуйте специфічні для додатків паролі або API ключі, а не пароль основного облікового запису.
  • Git токени — використовуйте токени з обмеженою областю дії для репозиторію та мінімальними правами (читання + запис для синхронізації).