Перейти к содержанию

Параметры .env

Параметры окружения задают подключение Webim к инфраструктуре (PostgreSQL, Redis, Kafka, ClickHouse, S3-хранилищу, поисковому движку и почтовому серверу), ключи шифрования, адреса и домены, а также параметры производительности и мониторинга. Параметры действуют на всю установку и читаются при запуске процессов Webim.

В облаке Webim параметры окружения задают сотрудники Webim. Раздел предназначен для технических специалистов hosted-клиентов.

Где хранятся параметры

При установке на сервер параметры хранятся в файле /opt/webim/django-chat/django-chat/.env. Владелец файла — пользователь www-data, права доступа — 640: файл содержит пароли и ключи. При первой установке файл создаётся из шаблона /opt/webim/django-chat/configs/.env, при обновлении Webim файл сохраняется. Переменные VERSION и APP_VERSION* процедура развёртывания перезаписывает сама.

При установке в Kubernetes параметры хранятся в пространстве имён chatback:

  • ConfigMap chatback-config — несекретные параметры;

  • Secret chatback-secrets — пароли, токены и ключи.

Установщик создаёт эти ресурсы из файлов комплекта поставки: несекретные параметры — из configmap-patch.yaml, секретные — из файла secret.env.

Формат файла

  • Каждый параметр записывается в отдельной строке в виде ИМЯ=значение, без пробелов вокруг =.

  • Строки, которые начинаются с #, — комментарии. Комментарий можно добавить и в конце строки: после значения поставьте пробел и #. Если значение само содержит #, заключите его в кавычки.

  • Пустое значение (ИМЯ=) не равно отсутствующему параметру: для большинства параметров пустая строка — допустимое значение, которое отключает соответствующую функцию. Чтобы действовало значение по умолчанию, удалите строку или закомментируйте её.

  • Логические значения: True или False. Также принимаются 1 и 0, yes и no, on и off.

  • Списки записываются через запятую без пробелов, например chat.example.local,admin.example.local.

  • В адресах подключения (postgresql://…, redis://…, clickhouse://…) специальные символы в имени пользователя и пароле (@, :, /, #, %, ?) кодируются по правилам URL: например, @ записывается как %40.

Приоритет источников

Если параметр задан в нескольких местах, действует значение с наибольшим приоритетом:

  • при установке на сервер переменные окружения процесса важнее файла .env. Конфигурация supervisor задаёт для всех процессов Webim LOG_LEVEL="warning", поэтому значение LOG_LEVEL из .env не действует: уровень журналирования меняется в конфигурации supervisor;

  • в Kubernetes значения, заданные в манифесте контейнера (раздел env), важнее Secret, а Secret важнее ConfigMap. Например, для веб-сервера в манифесте заданы DB_POOL_SIZE и PROMETHEUS_MULTIPROC_DIR, для планировщика — SCHEDULER_LEADER_LOCK_ENABLED, SCHEDULER_LOCK_KEY и SCHEDULER_LOCK_TTL.

Изменение параметров

Параметры читаются при запуске процессов, поэтому после изменения перезапустите приложения Webim.

Установка на сервер

  1. Откройте файл .env в текстовом редакторе от имени пользователя www-data:

    sudo -u www-data nano /opt/webim/django-chat/django-chat/.env
    
  2. Измените значения и сохраните файл. Не меняйте владельца и права доступа к файлу.

  3. Проверьте имена групп процессов Webim в supervisor. Обычно это djangochat и djangochat-kafka:

    sudo supervisorctl status
    
  4. Перезапустите процессы Webim:

    sudo supervisorctl restart 'djangochat:*' 'djangochat-kafka:*'
    

Установка в Kubernetes

  1. Измените несекретный параметр в ConfigMap:

    kubectl -n chatback edit configmap chatback-config
    

    Секретный параметр измените в Secret. Удобнее всего пересоздать Secret из файла secret.env комплекта поставки:

    kubectl -n chatback create secret generic chatback-secrets \
      --from-env-file=secret.env --dry-run=client -o yaml | kubectl apply -f -
    
  2. Внесите то же изменение в файлы комплекта поставки (configmap-patch.yaml или secret.env). Иначе при следующем обновлении Webim значение будет перезаписано.

  3. Перезапустите приложения Webim. Инфраструктурные сервисы (PostgreSQL, Redis, Kafka и другие) перезапускать не нужно:

    kubectl -n chatback rollout restart deployment -l 'role in (web,poll,kafka-worker)'
    kubectl -n chatback rollout restart statefulset -l 'role in (scheduler,watchdog)'
    

Параметры сборки фронтенда

Значения BASE_DOMAIN, S3_BASE_URL и S3_STATIC_BUCKET_NAME встраиваются в интерфейс Webim при сборке. После их изменения перезапуска недостаточно: требуется повторное развёртывание Webim.

Проверка при запуске

При запуске Webim проверяет обязательные параметры и формат значений. Если параметр не задан или задан неверно, процесс не запускается, а в журнале появляется ошибка с именем параметра: ImproperlyConfigured, UndefinedValueError или ValueError.

Проверить подключения к PostgreSQL, Redis, ClickHouse и другим сервисам можно командой check_connectivity.

Установка на сервер:

sudo -u www-data PYTHONPATH=/opt/webim/django-chat/django-chat \
  /opt/webim/django-chat/venv/bin/python /opt/webim/django-chat/django-chat/manage.py check_connectivity

Установка в Kubernetes:

kubectl -n chatback exec -it deploy/chatback-web -c web -- python manage.py check_connectivity

Обязательные параметры

Параметр Назначение Описание
SECRET_KEY Ключ подписи данных Ключи и шифрование
PASSWORD_SALT Соль токенов авторизации Ключи и шифрование
ACCOUNT_NAME Имя аккаунта Режим работы и адреса
ROOT_URL Внешний адрес Webim Режим работы и адреса
DOMAINS Разрешённые домены (обязателен при DEBUG=False) Режим работы и адреса
AUTH_COOKIE_NAME, STATUS_FROM_LOGIN_COOKIE_NAME, DEVICE_ID_COOKIE_NAMES Имена cookie Cookie и сессии
DATABASE_URL Подключение к PostgreSQL PostgreSQL
REDIS_CACHE_LOCATION Подключение к Redis Redis
S3_ENDPOINT_URL, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_REGION_NAME Подключение к S3-хранилищу Файлы и S3-хранилище
STATS_DATABASE_DEFAULT_URLS, STATS_DATABASE_TEMPLATE, STATS_CLUSTER_NAME Подключение к базе статистики в ClickHouse ClickHouse и аналитика

Некоторые параметры обязательны только вместе с другими: DEFAULT_HIDDEN_COUNTRIES — если задан GEO_DB_PATH, SENTRY_ENV — если задан SENTRY_DSN.

Значения по умолчанию параметров KAFKA_BOOTSTRAP_SERVERS (см. Kafka) и EMAIL_HOST (см. Почта и внешние сервисы) рассчитаны на среду разработки: в рабочей установке задайте и эти параметры.

Секретные параметры

Храните значения секретных параметров так же, как пароли: не передавайте их в открытом виде и не публикуйте в системах контроля версий. Смена некоторых ключей на работающей установке приводит к потере данных или доступа:

  • SECRET_KEY — подписанные ссылки и cookie становятся недействительными. Если не задан CREDENTIALS_ENCRYPTION_KEY, перестают расшифровываться учётные данные пуш-уведомлений и токены ботов;

  • PASSWORD_SALT — всем сотрудникам нужно войти заново;

  • ENCRYPTION_CONFIGS — нельзя удалять ключ, которым зашифрованы сохранённые данные: секреты каналов перестанут расшифровываться;

  • CREDENTIALS_ENCRYPTION_KEY — устанавливать и менять ключ на работающей установке можно только вместе с перешифрованием токенов ботов. Обратитесь в техническую поддержку Webim.

Разделы справочника

Число рабочих процессов веб-сервера, параметры gunicorn, топики и группы Kafka-обработчиков задаются не в .env, а в конфигурации supervisor или в манифестах Kubernetes: см. Параметры процессов.