Файл конфигурации¶

Glarus BI поддерживает инициализацию при запуске из файла конфигурации config.yml. Файл конфигурации должен находиться:

В текущем каталоге (где находится запущенный JAR-файл, например metabase.jar).
По пути, указанному в переменной окружения MB_CONFIG_FILE_PATH.

Настройки в файле конфигурации работают так же, как если бы вы задали эти настройки в разделе "Управление" вашего Glarus BI. Настройки, определённые в этом файле, обновят уже существующие настройки. Например, если база данных уже существует (то есть вы уже добавили её во время первичной настройки или через Управление > Базы данных), Glarus BI обновит запись базы данных в соответствии с данными из файла конфигурации.

Подсказка

Если вы определили настройку в файле конфигурации, а затем позже изменили эту настройку в интерфейсе Glarus BI, файл конфигурации перезапишет это изменение при каждом перезапуске.

Настройки из файла конфигурации не считаются «жёстко заданным» источником истины (в отличие от переменных окружения). Настройки, заданные через переменные окружения, нельзя изменить — даже в настройках администратора внутри приложения.

Пример шаблона файла конфигурации¶

См. Шаблон конфигурации.

Настройка config.yml¶

Файл конфигурации разделён на секции: version и config. Внутри config можно указать:

пользователей;
базы данных;
настройки.

Например:

version: 1
config:
  settings:
    - ...
  users:
    - ...
  databases:
    - ...

Файл конфигурации также должен содержать ключ version — это просто удобное поле, чтобы вы могли отслеживать версии вашего файла конфигурации.

Пользователи¶

Первый пользователь, созданный в экземпляре Glarus BI, является администратором. Первый пользователь, перечисленный в файле конфигурации, может быть назначен администратором, но не обязательно. Если кто-то уже запустил приложение и вошёл в него впервые, Glarus BI сделает этого первого пользователя администратором. Кроме того, вы можете явно указать, что пользователь является администратором, используя ключ is_superuser: true.

В примере ниже, при условии, что Glarus BI ещё не был настроен (что создаёт первого пользователя), оба пользователя first@example.com и admin@example.com будут администраторами: first@example.com — потому что он первый в списке, и admin@example.com — потому что у него установлен флаг is_superuser: true.

version: 1
config:
  users:
    - first_name: First
      last_name: Person
      password: metabot1
      email: first@example.com
    - first_name: Normal
      last_name: Person
      password: metabot1
      email: normal@example.com
    - first_name: Admin
      last_name: Person
      password: metabot1
      is_superuser: true
      email: admin@example.com

Если экземпляр Glarus BI уже был настроен, тогда first@example.com будет загружен как обычный пользователь.

Базы данных¶

В новом экземпляре Glarus BI пример ниже настраивает администратора и одно подключение к базе данных.

version: 1
config:
  users:
    - first_name: Cam
      last_name: Era
      password: 2cans3cans4cans
      email: cam@example.com
  databases:
    - name: test-data (Postgres)
      engine: postgres
      details:
        host: localhost
        port: 5432
        user: dbuser
        password: "{{ env POSTGRES_TEST_DATA_PASSWORD }}"
        dbname: test-data

Чтобы определить, какие ключи можно задавать для базы данных, посмотрите поля, доступные в самом Glarus BI для той базы данных, которую вы хотите добавить.

Настройка загрузок (uploads) для базы данных¶

Также можно настроить загрузки в файле конфигурации с помощью следующих параметров:

uploads_enabled: Boolean
uploads_schema_name: String
uploads_table_prefix: String

Пример:

version: 1
config:
  users:
    - first_name: Cam
      last_name: Era
      password: 2cans3cans4cans
      email: cam@example.com
  databases:
    - name: test-data (Postgres)
      engine: postgres
      details:
        host: localhost
        port: 5432
        user: dbuser
        password: "{{ env POSTGRES_TEST_DATA_PASSWORD }}"
        dbname: test-data
      uploads_enabled: true
      uploads_schema_name: uploads
      uploads_table_prefix: uploads_

См. Uploads.

Ключи API¶

С помощью файла конфигурации можно создать ключи API — это удобно для автоматизированных развёртываний и для сохранения стабильных ключей API между окружениями.

Добавить ключи API можно так:

version: 1
config:
  users:
    - first_name: Cam
      last_name: Era
      password: 2cans3cans4cans
      email: cam@example.com
  api-keys:
    - name: "Admin API key"
      group: admin
      creator: cam@example.com
      key: mb_firsttestapikey
    - name: "All Users API key"
      group: all-users
      creator: cam@example.com
      key: mb_secondtestapikey

Можно также использовать переменную окружения, чтобы подставить значение ключа API, например:

api-keys:
  - name: "ENV API Key"
    key: "{{env API_KEY_FROM_ENV}}"
    creator: "admin@example.com"
    group: "admin"

См. ниже раздел переменные окружения в config.yml.

Ключи API, которые вы создаёте (значение ключа key), должны иметь формат mb_, за которым следует строка Base64 (если говорить формально — tetrasexagesimal строка). То есть: mb_, затем буквы и цифры; минимум: 12 символов, максимум: 254 символа. Создаваемый ключ должен соответствовать регулярному выражению: mb_[A-Za-z0-9+/=]+.

Сгенерировать ключ API можно командой openssl rand:

echo "mb_$(openssl rand -base64 32)"

Она выдаст что-то вроде:

mb_aDqk1Tc4ZotWb2TyjHY71glALKlB+g75dLgmSufWGLc=

Ещё несколько замечаний о ключах API в файле конфигурации:

creator ключа API должен быть администратором. То есть в вашем экземпляре Glarus BI уже должен быть хотя бы один администратор, или вам нужно добавить учётную запись администратора в секцию users файла конфигурации.
Сами ключи можно назначать только одной из двух групп: admin или all-users. Файл конфигурации ограничивает назначение group этими группами, потому что это единственные группы, которые Glarus BI всегда инициализирует.
Разрешения ключа соответствуют разрешениям, выданным его группе group (а не пользователю creator).
Если Glarus BI найдёт существующий ключ API с тем же именем (name), что и ключ в файле конфигурации, он сохранит существующий ключ (то есть не перезапишет его ключом из файла конфигурации). Например, если вы сначала создали ключ API, а позже пересоздали ключ в интерфейсе, загрузка приложения с файлом конфигурации не перезапишет пересозданный ключ (то есть значение key в файле конфигурации перестанет работать).
Если вы хотите перезаписать существующий ключ через файл конфигурации, вам нужно сначала удалить существующий ключ. Если вы хотите сохранить оба ключа, нужно переименовать ключ в файле конфигурации.

Примечание

Файл конфигурации также содержит ключ api-key в секции settings. Эта настройка не создаёт ключи API; она используется для строкового сравнения в заголовке при аутентификации запросов к endpoint /notify.

Использование переменных окружения в `config.yml`¶

Как показано в примерах выше, переменные окружения можно указывать с помощью шаблонных тегов, например:

setting: "{{ env POSTGRES_TEST_DATA_PASSWORD }}"

Обратите внимание на кавычки вокруг шаблона "{{ env API_KEY_FROM_ENV }}": если не добавить кавычки, YAML-парсер не определит, что это строковый шаблон, который должен быть развёрнут, и приложение не подставит значение переменной окружения.

Glarus BI не поддерживает рекурсивное развёртывание: если одна переменная окружения ссылается на другую переменную окружения, результат будет непредсказуемый.

Значения со специальными символами в `config.yml`¶

Если значение содержит двойные фигурные скобки (}} или {{), вам нужно использовать тройные скобки, чтобы сказать парсеру конфигурации использовать буквальное значение. Например, если пароль равен MetaPa$$123{{>, вам нужно обернуть значение в тройные скобки:

password: "{{{ MetaPa$$123{{> }}}"

Обратите внимание на кавычки в "{{{ MetaPa$$123{{> }}}".

Отключение первичной синхронизации базы данных¶

При загрузке модели данных из сериализованного экспорта стоит отключить планировщик, чтобы приложение не пыталось синхронизировать базу данных.

Чтобы отключить первичную синхронизацию, добавьте config-from-file-sync-database в список settings и установите значение false. Настройка config-from-file-sync-database должна идти до списка databases, например:

version: 1
config:
  settings:
    config-from-file-sync-databases: false
  databases:
    - name: my-database
      engine: postgres
      details: ...

Настройки¶

В этом файле конфигурации вы можете указать любую административную настройку.

В целом, настройки в разделе settings этого файла настройки соответствуют переменным окружения: в статье по ссылке перечислено, что вы можете использовать. Форма записи ключа в файле настроек отличается от формата имени переменной окружения. Для переменной окружения используется стиль написания SCREAMING_SNAKE_CASE с приставкой MB:

MB_NAME_OF_VARIABLE

тогда как в файле конфигурации это должно быть изменено на стиль "lisp-case" без приставки MB:

name-of-variable

Например, если вы хотите указать MB_EMAIL_FROM_NAME в файле config.yml:

version: 1
config:
  settings:
    config-from-file-sync-databases: false
    email-from-name: Stampy von Mails-a-lot
  databases:
    - name: my-database
      engine: h2
      details: ...

Через файл конфигурации можно задавать любую административную настройку (список настроек см. в шаблоне файла конфигурации). Также можно просмотреть список переменных окружения, чтобы понять, что можно настроить. Но имейте в виду, что не все переменные окружения можно задавать через файл конфигурации.