Налаштування сервера¶
Використовуючи стандартний образ Docker, всі необхідні налаштування можна виконати з браузера. Однак, в залежності від розгортання, може бути необхідно налаштувати конфігурацію сервера.
Ця сторінка містить усі методи зміни конфігурації та всі існуючі параметри конфігурації.
Файл конфігурації vs. змінні середовища¶
Для налаштувань ви можете використовувати або файл конфігурації, або змінні середовища.
Коли ви використовуєте налаштування на основі Docker Compose, ви можете включити файл конфігурації, додавши наступний пункт списку під ключем volumes: у блоці grampsweb::
- /path/to/config.cfg:/app/config/config.cfg
/path/to/config.cfg - це шлях до файлу конфігурації у файловій системі вашого сервера (права сторона посилається на шлях у контейнері і не повинна змінюватись).
При використанні змінних середовища,
- префіксуйте кожну назву налаштування
GRAMPSWEB_, щоб отримати назву змінної середовища - Використовуйте подвійні підкреслення для вкладених налаштувань словника, наприклад,
GRAMPSWEB_THUMBNAIL_CACHE_CONFIG__CACHE_DEFAULT_TIMEOUTвстановить значення параметра конфігураціїTHUMBNAIL_CACHE_CONFIG['CACHE_DEFAULT_TIMEOUT']
Зверніть увагу, що параметри конфігурації, встановлені через середовище, мають пріоритет над тими, що в файлі конфігурації. Якщо обидва присутні, змінна середовища "перемагає".
Змінні середовища без префікса застаріли
З історичних причин, кілька налаштувань – TREE, SECRET_KEY, USER_DB_URI, POSTGRES_USER, POSTGRES_PASSWORD, MEDIA_BASE_DIR, SEARCH_INDEX_DIR, EMAIL_HOST, EMAIL_PORT, EMAIL_HOST_USER, EMAIL_HOST_PASSWORD, DEFAULT_FROM_EMAIL, BASE_URL, і STATIC_PATH – все ще можуть бути встановлені через змінну середовища без префікса GRAMPSWEB_. Це застаріле, виводить попередження під час запуску і перестане працювати в майбутньому випуску. Завжди використовуйте префіксовану форму, наприклад, GRAMPSWEB_TREE замість TREE.
Зверніть увагу, що це стосується лише змінних середовища. У файлі конфігурації назви налаштувань завжди використовуються без префікса.
Перевірка застарілих параметрів
Застарілі параметри конфігурації, на яких ваш сервер все ще покладається – такі як змінні середовища без префікса, SEARCH_INDEX_DIR, або EMAIL_USE_TLS – реєструються як попередження під час запуску. Починаючи з Gramps Web API 3.22, вони також перераховуються разом із їх заміною та версією, в якій підтримка буде видалена, на початку сторінки Системна інформація (доступна через іконку користувача у верхній панелі додатку), коли ви увійшли як адміністратор.
Існуючі параметри конфігурації¶
Існують наступні параметри конфігурації.
Обов'язкові налаштування¶
| Ключ | Опис |
|---|---|
TREE |
Назва бази даних родинного дерева, яку потрібно використовувати. Показати доступні дерева за допомогою gramps -l. Якщо дерева з цією назвою не існує, буде створено нове порожнє. |
SECRET_KEY |
Секретний ключ для Flask. Секрет не повинен бути опублікований. Зміна його анулює всі токени доступу. |
USER_DB_URI |
URL бази даних користувачів. Дозволяється будь-який URL, сумісний з SQLAlchemy. |
Info
Ви можете згенерувати безпечний секретний ключ, наприклад, за допомогою команди
python3 -c "import secrets;print(secrets.token_urlsafe(32))"
Додаткові налаштування¶
| Ключ | Опис |
|---|---|
MEDIA_BASE_DIR |
Шлях, який використовуватиметься як базовий каталог для медіафайлів, переважаючи базовий каталог медіа, встановлений у Gramps. При використанні S3 повинен мати форму s3://<bucket_name> |
TREE_ID |
Назва каталогу бази даних родинного дерева, яку потрібно використовувати в режимі одного дерева (коли TREE не встановлено на *). Коли встановлено, сервер ідентифікує дерево за його назвою каталогу, а не за його відображуваною назвою, що є більш надійним при перейменуваннях. Обов'язково, якщо ви хочете перейменувати дерево через API. Назву каталогу можна знайти за допомогою GET /api/trees/- (поле id). |
SEARCH_INDEX_DB_URI |
URL бази даних для індексу пошуку. Дозволяються лише sqlite або postgresql як бекенди. За замовчуванням sqlite:///indexdir/search_index.db, створюючи файл SQLite у папці indexdir, відносно шляху, де виконується скрипт. |
SEARCH_INDEX_DIR |
Застаріло (використовуйте SEARCH_INDEX_DB_URI замість). Каталог, що містить індекс пошуку. Якщо встановлено, коли SEARCH_INDEX_DB_URI не встановлено, URL індексу пошуку отримується як sqlite:///<SEARCH_INDEX_DIR>/search_index.db. |
STATIC_PATH |
Шлях для обслуговування статичних файлів (наприклад, статичний веб-фронтенд) |
BASE_URL |
Базовий URL, за яким можна отримати доступ до API (наприклад, https://mygramps.mydomain.com/). Це необхідно, наприклад, для створення правильних посилань для скидання пароля |
CORS_ORIGINS |
Походження, з яких дозволені CORS запити. За замовчуванням всі заборонені. Використовуйте "*" для дозволу запитів з будь-якого домену. |
EMAIL_HOST |
Хост SMTP сервера (наприклад, для надсилання електронних листів для скидання пароля) |
EMAIL_PORT |
Порт SMTP сервера. за замовчуванням 465 |
EMAIL_HOST_USER |
Ім'я користувача SMTP сервера |
EMAIL_HOST_PASSWORD |
Пароль SMTP сервера |
EMAIL_USE_TLS |
Застаріло (використовуйте EMAIL_USE_SSL або EMAIL_USE_STARTTLS замість). Булевий, чи використовувати TLS для надсилання електронних листів. За замовчуванням True. При використанні STARTTLS, встановіть це на False і використовуйте порт, відмінний від 25. |
EMAIL_USE_SSL |
Булевий, чи використовувати імпліцитний SSL/TLS для SMTP (v3.6.0+). За замовчуванням True, якщо EMAIL_USE_TLS не встановлено явно. Зазвичай використовується з портом 465. |
EMAIL_USE_STARTTLS |
Булевий, чи використовувати явний STARTTLS для SMTP (v3.6.0+). За замовчуванням False. Зазвичай використовується з портом 587 або 25. |
DEFAULT_FROM_EMAIL |
Адреса "Від" для автоматизованих електронних листів |
THUMBNAIL_CACHE_CONFIG |
Словник з налаштуваннями для кешу ескізів. Дивіться Flask-Caching для можливих налаштувань. |
REQUEST_CACHE_CONFIG |
Словник з налаштуваннями для кешу запитів. Дивіться Flask-Caching для можливих налаштувань. |
PERSISTENT_CACHE_CONFIG |
Словник з налаштуваннями для постійного кешу, який використовується, наприклад, для телеметрії. Дивіться Flask-Caching для можливих налаштувань. |
CELERY_CONFIG |
Налаштування для фонової черги завдань Celery. Дивіться Celery для можливих налаштувань. |
REPORT_DIR |
Тимчасовий каталог, де зберігатиметься вихід виконання звітів Gramps |
EXPORT_DIR |
Тимчасовий каталог, де зберігатиметься вихід експорту бази даних Gramps |
REGISTRATION_DISABLED |
Якщо True, заборонити реєстрацію нових користувачів (за замовчуванням False) |
DISABLE_TELEMETRY |
Якщо True, вимкнути телеметрію статистики (за замовчуванням False). Дивіться телеметрію для деталей. |
PILLOW_MAX_IMAGE_PIXELS |
Встановлює параметр PIL.Image.MAX_IMAGE_PIXELS, який вказує кількість пікселів, які може містити оброблене зображення. Дивіться документацію для деталей. |
MAX_THUMBNAIL_FILE_BYTES |
Встановлює жорсткий максимальний розмір файлу для ескізів. За замовчуванням 50 * 1024 * 1024 (50 МБ). Підвищення цього значення може значно збільшити використання пам'яті і може призвести до аварій через нестачу пам'яті або втрати даних, якщо великі файли розпаковуються в пам'яті. |
Info
При використанні змінних середовища для конфігурації булеві параметри, такі як EMAIL_USE_SSL, повинні бути або рядком true, або false (чутливість до регістру!).
Налаштування для баз даних PostgreSQL¶
Ці налаштування є обов'язковими, якщо ваші родинні дерева розміщені у базі даних PostgreSQL з використанням аддона SharedPostgreSQL.
| Ключ | Опис |
|---|---|
POSTGRES_USER |
Ім'я користувача для підключення до бази даних |
POSTGRES_PASSWORD |
Пароль для користувача бази даних |
Налаштування, що стосуються хостингу кількох дерев¶
Наступні налаштування є актуальними при хостингу кількох дерев.
| Ключ | Опис |
|---|---|
MEDIA_PREFIX_TREE |
Булевий, чи використовувати окрему підпапку для медіафайлів кожного дерева. За замовчуванням False, але настійно рекомендується використовувати True в налаштуванні з кількома деревами |
NEW_DB_BACKEND |
Бекенд бази даних, який потрібно використовувати для новостворених родинних дерев. Повинен бути одним з sqlite або sharedpostgresql. За замовчуванням sqlite. Значення postgresql все ще приймається, але застаріле, оскільки бекенд PostgreSQL буде видалено в майбутній версії. |
POSTGRES_HOST |
Ім'я хоста сервера PostgreSQL, що використовується для створення нових дерев при використанні налаштування з кількома деревами з бекендом SharedPostgreSQL |
POSTGRES_PORT |
Порт сервера PostgreSQL, що використовується для створення нових дерев при використанні налаштування з кількома деревами з бекендом SharedPostgreSQL |
Налаштування для аутентифікації OIDC¶
Ці налаштування потрібні, якщо ви хочете використовувати аутентифікацію OpenID Connect (OIDC) з зовнішніми постачальниками. Для детальних інструкцій з налаштування та прикладів дивіться Аутентифікація OIDC.
| Ключ | Опис |
|---|---|
OIDC_ENABLED |
Булевий, чи включити аутентифікацію OIDC. За замовчуванням False. |
OIDC_ISSUER |
URL постачальника OIDC (для користувацьких постачальників OIDC) |
OIDC_CLIENT_ID |
OAuth ідентифікатор клієнта (для користувацьких постачальників OIDC) |
OIDC_CLIENT_SECRET |
OAuth секрет клієнта (для користувацьких постачальників OIDC) |
OIDC_NAME |
Користувацька назва для постачальника. За замовчуванням "OIDC" |
OIDC_SCOPES |
OAuth області. За замовчуванням "openid email profile" |
OIDC_USERNAME_CLAIM |
Заява, яку використовувати для імені користувача. За замовчуванням "preferred_username" |
OIDC_OPENID_CONFIG_URL |
Необов'язково: URL до кінцевої точки конфігурації OpenID Connect (якщо не використовується стандартний /.well-known/openid-configuration) |
OIDC_PKCE |
Булевий, чи використовувати PKCE. Якщо не встановлено, PKCE використовується, коли документ виявлення постачальника містить S256. Дивіться PKCE |
OIDC_DISABLE_LOCAL_AUTH |
Булевий, чи вимкнути локальну аутентифікацію за допомогою імені користувача/пароля. За замовчуванням False |
OIDC_AUTO_REDIRECT |
Булевий, чи автоматично перенаправляти на OIDC, коли налаштовано лише одного постачальника. За замовчуванням False |
Вбудовані постачальники OIDC¶
Для вбудованих постачальників (Google, Microsoft) використовуйте ці налаштування:
| Ключ | Опис |
|---|---|
OIDC_GOOGLE_CLIENT_ID |
Ідентифікатор клієнта для Google OAuth |
OIDC_GOOGLE_CLIENT_SECRET |
Секрет клієнта для Google OAuth |
OIDC_MICROSOFT_CLIENT_ID |
Ідентифікатор клієнта для Microsoft OAuth |
OIDC_MICROSOFT_CLIENT_SECRET |
Секрет клієнта для Microsoft OAuth |
OIDC_GOOGLE_PKCE |
Булевий, налаштування PKCE для Google, дивіться PKCE |
OIDC_MICROSOFT_PKCE |
Булевий, налаштування PKCE для Microsoft, дивіться PKCE |
Відображення ролей OIDC¶
Ці налаштування дозволяють вам відображати групи/ролі OIDC з вашого постачальника ідентичності на ролі користувачів Gramps Web:
| Ключ | Опис |
|---|---|
OIDC_ROLE_CLAIM |
Назва заяви в токені OIDC, яка містить групи/ролі користувача. За замовчуванням "groups" |
OIDC_GROUP_ADMIN |
Назва групи/ролі з вашого постачальника OIDC, яка відображається на роль "Адміністратор" Gramps |
OIDC_GROUP_OWNER |
Назва групи/ролі з вашого постачальника OIDC, яка відображається на роль "Власник" Gramps |
OIDC_GROUP_EDITOR |
Назва групи/ролі з вашого постачальника OIDC, яка відображається на роль "Редактор" Gramps |
OIDC_GROUP_CONTRIBUTOR |
Назва групи/ролі з вашого постачальника OIDC, яка відображається на роль "Співробітник" Gramps |
OIDC_GROUP_MEMBER |
Назва групи/ролі з вашого постачальника OIDC, яка відображається на роль "Член" Gramps |
OIDC_GROUP_GUEST |
Назва групи/ролі з вашого постачальника OIDC, яка відображається на роль "Гість" Gramps |
Налаштування лише для функцій ШІ¶
Ці налаштування потрібні, якщо ви хочете використовувати функції на основі ШІ, такі як чат або семантичний пошук.
| Ключ | Опис |
|---|---|
LLM_BASE_URL |
Базовий URL для API чату, сумісного з OpenAI. За замовчуванням None, що використовує API OpenAI. |
LLM_MODEL |
Модель, яку потрібно використовувати для API чату, сумісного з OpenAI. Якщо не встановлено (за замовчуванням), чат вимкнено. Починаючи з v3.6.0, асистент ШІ використовує Pydantic AI з можливостями виклику інструментів. |
VECTOR_EMBEDDING_MODEL |
Модель, яку потрібно використовувати для векторних вбудувань семантичного пошуку. При використанні локальної моделі це повинна бути назва моделі Sentence Transformers. При використанні віддаленого API (див. VECTOR_EMBEDDING_BASE_URL) це назва моделі, передана віддаленому постачальнику. Якщо не встановлено (за замовчуванням), семантичний пошук і чат вимкнені. |
VECTOR_EMBEDDING_BASE_URL |
Базовий URL для віддаленого API вбудування, сумісного з OpenAI (наприклад, Ollama, OpenAI, LiteLLM). Якщо не встановлено (за замовчуванням), використовується локальна модель Sentence Transformers. Дивіться Використання віддаленого API вбудування для деталей. |
VECTOR_EMBEDDING_API_KEY |
API ключ для аутентифікованих віддалених постачальників вбудування. Потрібен лише тоді, коли VECTOR_EMBEDDING_BASE_URL встановлено і постачальник вимагає аутентифікації. |
LLM_MAX_CONTEXT_LENGTH |
Обмеження символів для контексту родинного дерева, наданого LLM. За замовчуванням 50000. |
LLM_SYSTEM_PROMPT |
Користувацький системний запит для асистента чату LLM (v3.6.0+). Якщо не встановлено, використовується стандартний запит, оптимізований для генеалогії. |
Приклад файлу конфігурації¶
Мінімальний файл конфігурації для виробництва може виглядати так: ```python TREE="My Family Tree" BASE_URL="https://mytree.example.com" SECRET_KEY="..." # ваш секретний ключ USER_DB_URI="sqlite:////path/to/users.sqlite" EMAIL_HOST="mail.example.com" EMAIL_PORT=465 EMAIL_USE_SSL=True # Використовуйте імпліцитний SSL для порту 465 EMAIL_HOST_USER="gramps@example.com" EMAIL_HOST_PASSWORD="..." # ваш SMTP пароль DEFAULT_FROM_EMAIL="gramps@example.com"