# Параметры .env

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

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

## Где хранятся параметры { #location }

При установке на сервер параметры хранятся в файле `/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`.

## Формат файла { #format }

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

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

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

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

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

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

## Приоритет источников { #precedence }

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

  * при установке на сервер переменные окружения процесса важнее файла `.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`.

## Изменение параметров { #editing }

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

### Установка на сервер { #editing-host }

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

     ```bash
     sudo -u www-data nano /opt/webim/django-chat/django-chat/.env
     ```

  1. Измените значения и сохраните файл. Не меняйте владельца и права доступа к файлу.

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

     ```bash
     sudo supervisorctl status
     ```

  1. Перезапустите процессы **Webim**:

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

### Установка в Kubernetes { #editing-k8s }

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

     ```bash
     kubectl -n chatback edit configmap chatback-config
     ```

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

     ```bash
     kubectl -n chatback create secret generic chatback-secrets \
       --from-env-file=secret.env --dry-run=client -o yaml | kubectl apply -f -
     ```

  1. Внесите то же изменение в файлы комплекта поставки (`configmap-patch.yaml` или `secret.env`). Иначе при следующем обновлении **Webim** значение будет перезаписано.

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

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

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

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

## Проверка при запуске { #validation }

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

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

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

```bash
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:

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

## Обязательные параметры { #required }

| Параметр | Назначение | Описание |
|---|---|---|
| `SECRET_KEY` | Ключ подписи данных | [Ключи и шифрование](https://webim.ru/kb/11.0/settings/env/general.html#secrets) |
| `PASSWORD_SALT` | Соль токенов авторизации | [Ключи и шифрование](https://webim.ru/kb/11.0/settings/env/general.html#secrets) |
| `ACCOUNT_NAME` | Имя аккаунта | [Режим работы и адреса](https://webim.ru/kb/11.0/settings/env/general.html#mode) |
| `ROOT_URL` | Внешний адрес **Webim** | [Режим работы и адреса](https://webim.ru/kb/11.0/settings/env/general.html#mode) |
| `DOMAINS` | Разрешённые домены (обязателен при `DEBUG=False`) | [Режим работы и адреса](https://webim.ru/kb/11.0/settings/env/general.html#mode) |
| `AUTH_COOKIE_NAME`, `STATUS_FROM_LOGIN_COOKIE_NAME`, `DEVICE_ID_COOKIE_NAMES` | Имена cookie | [Cookie и сессии](https://webim.ru/kb/11.0/settings/env/general.html#cookies) |
| `DATABASE_URL` | Подключение к PostgreSQL | [PostgreSQL](https://webim.ru/kb/11.0/settings/env/postgresql.html#connection) |
| `REDIS_CACHE_LOCATION` | Подключение к Redis | [Redis](https://webim.ru/kb/11.0/settings/env/redis.html#connection) |
| `S3_ENDPOINT_URL`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_REGION_NAME` | Подключение к S3-хранилищу | [Файлы и S3-хранилище](https://webim.ru/kb/11.0/settings/env/files.html#s3) |
| `STATS_DATABASE_DEFAULT_URLS`, `STATS_DATABASE_TEMPLATE`, `STATS_CLUSTER_NAME` | Подключение к базе статистики в ClickHouse | [ClickHouse и аналитика](https://webim.ru/kb/11.0/settings/env/clickhouse.html#stats) |

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

Значения по умолчанию параметров `KAFKA_BOOTSTRAP_SERVERS` (см. [Kafka](https://webim.ru/kb/11.0/settings/env/kafka.html#connection)) и `EMAIL_HOST` (см. [Почта и внешние сервисы](https://webim.ru/kb/11.0/settings/env/integrations.html#email)) рассчитаны на среду разработки: в рабочей установке задайте и эти параметры.

## Секретные параметры { #secrets }

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

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

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

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

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

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

  * [Основные параметры и безопасность](https://webim.ru/kb/11.0/settings/env/general.html) — режим работы, адреса и домены, ключи шифрования, cookie, защита веб-интерфейса.

  * [PostgreSQL](https://webim.ru/kb/11.0/settings/env/postgresql.html) — подключение к основной базе данных и реплике, пулы соединений.

  * [Redis](https://webim.ru/kb/11.0/settings/env/redis.html) — подключение к Redis и Sentinel, пулы соединений.

  * [Kafka](https://webim.ru/kb/11.0/settings/env/kafka.html) — подключение к брокеру, обработчики очередей, топики и мониторинг шины.

  * [ClickHouse и аналитика](https://webim.ru/kb/11.0/settings/env/clickhouse.html) — базы статистики и BI-отчётов.

  * [Поиск и проверка текста](https://webim.ru/kb/11.0/settings/env/search.html) — Elasticsearch или OpenSearch, LanguageTool.

  * [Файлы и S3-хранилище](https://webim.ru/kb/11.0/settings/env/files.html) — S3-хранилище, бакеты, ограничения размера файлов и изображений.

  * [Почта и внешние сервисы](https://webim.ru/kb/11.0/settings/env/integrations.html) — SMTP, Telegram, исходящие HTTP-соединения.

  * [Журналы и мониторинг](https://webim.ru/kb/11.0/settings/env/monitoring.html) — журналирование, Sentry, Prometheus, пороги уведомлений.

  * [Защита от перегрузки](https://webim.ru/kb/11.0/settings/env/load.html) — ограничение конкурентности, замедление опроса, автоматический выключатель, мониторинг пулов соединений, лимиты частоты запросов.

  * [Тайм-ауты, кэш и фоновые задачи](https://webim.ru/kb/11.0/settings/env/timeouts.html) — сроки действия токенов авторизации, сроки актуальности фоновых задач, кэш, блокировки и планировщик.

Число рабочих процессов веб-сервера, параметры gunicorn, топики и группы Kafka-обработчиков задаются не в `.env`, а в конфигурации supervisor или в манифестах Kubernetes: см. [Параметры процессов](https://webim.ru/kb/11.0/settings/processes.html).

---

Источник: https://webim.ru/kb/11.0/settings/env/index.html
