Configuração do Servidor¶

Usando a imagem padrão do Docker, toda a configuração necessária pode ser feita a partir do navegador. No entanto, dependendo da implantação, pode ser necessário personalizar a configuração do servidor.

Esta página lista todos os métodos para alterar a configuração e todas as opções de configuração existentes.

Arquivo de configuração vs. variáveis de ambiente¶

Para as configurações, você pode usar um arquivo de configuração ou variáveis de ambiente.

Quando você usa a configuração baseada em Docker Compose, pode incluir um arquivo de configuração adicionando o seguinte item à lista sob a chave volumes: no bloco grampsweb::

      - /caminho/para/config.cfg:/app/config/config.cfg

onde /caminho/para/config.cfg é o caminho para o arquivo de configuração no sistema de arquivos do seu servidor (o lado direito refere-se ao caminho no contêiner e não deve ser alterado).

Ao usar variáveis de ambiente,

prefixe cada nome de configuração com GRAMPSWEB_ para obter o nome da variável de ambiente
Use sublinhados duplos para configurações de dicionário aninhadas, por exemplo, GRAMPSWEB_THUMBNAIL_CACHE_CONFIG__CACHE_DEFAULT_TIMEOUT definirá o valor da opção de configuração THUMBNAIL_CACHE_CONFIG['CACHE_DEFAULT_TIMEOUT']

Observe que as opções de configuração definidas via ambiente têm precedência sobre as que estão no arquivo de configuração. Se ambas estiverem presentes, a variável de ambiente "vence".

Variáveis de ambiente sem prefixo estão obsoletas

Por razões históricas, um punhado de configurações – 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, e STATIC_PATH – ainda podem ser definidas via uma variável de ambiente sem o prefixo GRAMPSWEB_. Isso está obsoleto, gera um aviso na inicialização e deixará de funcionar em uma versão futura. Sempre use a forma prefixada, por exemplo, GRAMPSWEB_TREE em vez de TREE.

Observe que isso diz respeito apenas a variáveis de ambiente. Em um arquivo de configuração, os nomes das configurações são sempre usados sem prefixo.

Configurações de configuração existentes¶

As seguintes opções de configuração existem.

Configurações obrigatórias¶

Chave	Descrição
`TREE`	O nome do banco de dados da árvore genealógica a ser usado. Mostre as árvores disponíveis com `gramps -l`. Se uma árvore com esse nome não existir, uma nova vazia será criada.
`SECRET_KEY`	A chave secreta para o Flask. A chave secreta não deve ser compartilhada publicamente. Alterá-la invalidará todos os tokens de acesso.
`USER_DB_URI`	A URL do banco de dados do usuário. Qualquer URL compatível com SQLAlchemy é permitida.

Info

Você pode gerar uma chave secreta segura, por exemplo, com o comando

python3 -c "import secrets;print(secrets.token_urlsafe(32))"

Configurações opcionais¶

Chave	Descrição
`MEDIA_BASE_DIR`	Caminho a ser usado como diretório base para arquivos de mídia, substituindo o diretório base de mídia definido no Gramps. Ao usar S3, deve ter a forma `s3://<bucket_name>`
`TREE_ID`	O nome do diretório do banco de dados da árvore genealógica a ser usado no modo de árvore única (quando `TREE` não está definido como `*`). Quando definido, o servidor identifica a árvore pelo nome do diretório em vez do nome de exibição, o que é mais robusto para renomeações. Necessário se você quiser renomear a árvore via API. O nome do diretório pode ser encontrado via `GET /api/trees/-` (o campo `id`).
`SEARCH_INDEX_DB_URI`	URL do banco de dados para o índice de busca. Apenas `sqlite` ou `postgresql` são permitidos como backends. O padrão é `sqlite:///indexdir/search_index.db`, criando um arquivo SQLite na pasta `indexdir` em relação ao caminho onde o script é executado.
`SEARCH_INDEX_DIR`	Obsoleto (use `SEARCH_INDEX_DB_URI` em vez disso). Diretório contendo o índice de busca. Se definido enquanto `SEARCH_INDEX_DB_URI` estiver indefinido, a URL do índice de busca é derivada como `sqlite:///<SEARCH_INDEX_DIR>/search_index.db`.
`STATIC_PATH`	Caminho para servir arquivos estáticos (por exemplo, um frontend web estático)
`BASE_URL`	URL base onde a API pode ser acessada (por exemplo, `https://mygramps.mydomain.com/`). Isso é necessário, por exemplo, para construir links corretos de redefinição de senha.
`CORS_ORIGINS`	Origens de onde solicitações CORS são permitidas. Por padrão, todas são negadas. Use `"*"` para permitir solicitações de qualquer domínio.
`EMAIL_HOST`	Host do servidor SMTP (por exemplo, para enviar e-mails de redefinição de senha)
`EMAIL_PORT`	Porta do servidor SMTP. O padrão é 465.
`EMAIL_HOST_USER`	Nome de usuário do servidor SMTP
`EMAIL_HOST_PASSWORD`	Senha do servidor SMTP
`EMAIL_USE_TLS`	Obsoleto (use `EMAIL_USE_SSL` ou `EMAIL_USE_STARTTLS` em vez disso). Booleano, se deve usar TLS para enviar e-mails. O padrão é `True`. Ao usar STARTTLS, defina isso como `False` e use uma porta diferente de 25.
`EMAIL_USE_SSL`	Booleano, se deve usar SSL/TLS implícito para SMTP (v3.6.0+). O padrão é `True` se `EMAIL_USE_TLS` não estiver definido explicitamente. Geralmente usado com a porta 465.
`EMAIL_USE_STARTTLS`	Booleano, se deve usar STARTTLS explícito para SMTP (v3.6.0+). O padrão é `False`. Geralmente usado com a porta 587 ou 25.
`DEFAULT_FROM_EMAIL`	Endereço "De" para e-mails automatizados
`THUMBNAIL_CACHE_CONFIG`	Dicionário com configurações para o cache de miniaturas. Veja Flask-Caching para possíveis configurações.
`REQUEST_CACHE_CONFIG`	Dicionário com configurações para o cache de solicitações. Veja Flask-Caching para possíveis configurações.
`PERSISTENT_CACHE_CONFIG`	Dicionário com configurações para o cache persistente, usado, por exemplo, para telemetria. Veja Flask-Caching para possíveis configurações.
`CELERY_CONFIG`	Configurações para a fila de tarefas em segundo plano Celery. Veja Celery para possíveis configurações.
`REPORT_DIR`	Diretório temporário onde a saída da execução de relatórios do Gramps será armazenada.
`EXPORT_DIR`	Diretório temporário onde a saída da exportação do banco de dados do Gramps será armazenada.
`REGISTRATION_DISABLED`	Se `True`, desabilita o registro de novos usuários (padrão `False`).
`DISABLE_TELEMETRY`	Se `True`, desabilita a telemetria de estatísticas (padrão `False`). Veja telemetria para detalhes.
`PILLOW_MAX_IMAGE_PIXELS`	Define o parâmetro PIL.Image.MAX_IMAGE_PIXELS, que indica o número de pixels que a imagem processada pode conter. Veja docs para detalhes.
`MAX_THUMBNAIL_FILE_BYTES`	Define um tamanho máximo de arquivo rígido para miniaturas. O padrão é `50 * 1024 * 1024` (50 MB). Aumentá-lo pode aumentar muito o uso de memória e pode levar a falhas por falta de memória ou perda de dados se arquivos grandes forem descompactados na memória.

Info

Ao usar variáveis de ambiente para configuração, opções booleanas como EMAIL_USE_SSL devem ser a string true ou false (sensível a maiúsculas e minúsculas!).

Configurações apenas para banco de dados backend PostgreSQL¶

Isso é necessário se você configurou seu banco de dados Gramps para trabalhar com o complemento PostgreSQL.

Chave	Descrição
`POSTGRES_USER`	O nome de usuário para a conexão com o banco de dados
`POSTGRES_PASSWORD`	A senha para o usuário do banco de dados

Configurações relevantes para hospedagem de várias árvores¶

As seguintes configurações são relevantes ao hospedar várias árvores.

Chave	Descrição
`MEDIA_PREFIX_TREE`	Booleano, se deve ou não usar uma subpasta separada para os arquivos de mídia de cada árvore. O padrão é `False`, mas é altamente recomendado usar `True` em uma configuração de várias árvores.
`NEW_DB_BACKEND`	O backend do banco de dados a ser usado para novas árvores genealógicas criadas. Deve ser um dos `sqlite`, `postgresql` ou `sharedpostgresql`. O padrão é `sqlite`.
`POSTGRES_HOST`	O nome do host do servidor PostgreSQL usado para criar novas árvores ao usar uma configuração de várias árvores com o backend SharedPostgreSQL.
`POSTGRES_PORT`	A porta do servidor PostgreSQL usada para criar novas árvores ao usar uma configuração de várias árvores com o backend SharedPostgreSQL.

Configurações para autenticação OIDC¶

Essas configurações são necessárias se você quiser usar autenticação OpenID Connect (OIDC) com provedores externos. Para instruções detalhadas de configuração e exemplos, veja Autenticação OIDC.

Chave	Descrição
`OIDC_ENABLED`	Booleano, se deve habilitar a autenticação OIDC. O padrão é `False`.
`OIDC_ISSUER`	URL do emissor do provedor OIDC (para provedores OIDC personalizados)
`OIDC_CLIENT_ID`	ID do cliente OAuth (para provedores OIDC personalizados)
`OIDC_CLIENT_SECRET`	Segredo do cliente OAuth (para provedores OIDC personalizados)
`OIDC_NAME`	Nome de exibição personalizado para o provedor. O padrão é "OIDC"
`OIDC_SCOPES`	Escopos OAuth. O padrão é "openid email profile"
`OIDC_USERNAME_CLAIM`	A reivindicação a ser usada para o nome de usuário. O padrão é "preferred_username"
`OIDC_OPENID_CONFIG_URL`	Opcional: URL para o endpoint de configuração OpenID Connect (se não estiver usando o padrão `/.well-known/openid-configuration`)
`OIDC_DISABLE_LOCAL_AUTH`	Booleano, se deve desabilitar a autenticação local por nome de usuário/senha. O padrão é `False`
`OIDC_AUTO_REDIRECT`	Booleano, se deve redirecionar automaticamente para OIDC quando apenas um provedor estiver configurado. O padrão é `False`

Provedores OIDC integrados¶

Para provedores integrados (Google, Microsoft), use estas configurações:

Chave	Descrição
`OIDC_GOOGLE_CLIENT_ID`	ID do cliente para Google OAuth
`OIDC_GOOGLE_CLIENT_SECRET`	Segredo do cliente para Google OAuth
`OIDC_MICROSOFT_CLIENT_ID`	ID do cliente para Microsoft OAuth
`OIDC_MICROSOFT_CLIENT_SECRET`	Segredo do cliente para Microsoft OAuth

Mapeamento de Funções OIDC¶

Essas configurações permitem que você mapeie grupos/funções OIDC do seu provedor de identidade para funções de usuário do Gramps Web:

Chave	Descrição
`OIDC_ROLE_CLAIM`	O nome da reivindicação no token OIDC que contém os grupos/funções do usuário. O padrão é "groups"
`OIDC_GROUP_ADMIN`	O nome do grupo/função do seu provedor OIDC que mapeia para a função "Admin" do Gramps
`OIDC_GROUP_OWNER`	O nome do grupo/função do seu provedor OIDC que mapeia para a função "Owner" do Gramps
`OIDC_GROUP_EDITOR`	O nome do grupo/função do seu provedor OIDC que mapeia para a função "Editor" do Gramps
`OIDC_GROUP_CONTRIBUTOR`	O nome do grupo/função do seu provedor OIDC que mapeia para a função "Contributor" do Gramps
`OIDC_GROUP_MEMBER`	O nome do grupo/função do seu provedor OIDC que mapeia para a função "Member" do Gramps
`OIDC_GROUP_GUEST`	O nome do grupo/função do seu provedor OIDC que mapeia para a função "Guest" do Gramps

Configurações apenas para recursos de IA¶

Essas configurações são necessárias se você quiser usar recursos impulsionados por IA, como chat ou busca semântica.

Chave	Descrição
`LLM_BASE_URL`	URL base para a API de chat compatível com OpenAI. O padrão é `None`, que usa a API OpenAI.
`LLM_MODEL`	O modelo a ser usado para a API de chat compatível com OpenAI. Se não definido (o padrão), o chat é desativado. A partir da v3.6.0, o assistente de IA usa Pydantic AI com capacidades de chamada de ferramentas.
`VECTOR_EMBEDDING_MODEL`	O modelo a ser usado para embeddings de vetor de busca semântica. Ao usar um modelo local, isso deve ser um nome de modelo Sentence Transformers. Ao usar uma API remota (veja `VECTOR_EMBEDDING_BASE_URL`), este é o nome do modelo passado para o provedor remoto. Se não definido (o padrão), a busca semântica e o chat são desativados.
`VECTOR_EMBEDDING_BASE_URL`	URL base para uma API de embedding remota compatível com OpenAI (por exemplo, Ollama, OpenAI, LiteLLM). Se não definido (o padrão), um modelo local Sentence Transformers é usado. Veja Usando uma API de embedding remota para detalhes.
`VECTOR_EMBEDDING_API_KEY`	Chave da API para provedores de embedding remotos autenticados. Necessário apenas quando `VECTOR_EMBEDDING_BASE_URL` está definido e o provedor requer autenticação.
`LLM_MAX_CONTEXT_LENGTH`	Limite de caracteres para o contexto da árvore genealógica fornecido ao LLM. O padrão é 50000.
`LLM_SYSTEM_PROMPT`	Prompt de sistema personalizado para o assistente de chat LLM (v3.6.0+). Se não definido, usa o prompt otimizado para genealogia padrão.

Exemplo de arquivo de configuração¶

Um arquivo de configuração mínimo para produção poderia ser assim: ```python TREE="Minha Árvore Genealógica" BASE_URL="https://minhaarvore.exemplo.com" SECRET_KEY="..." # sua chave secreta USER_DB_URI="sqlite:////caminho/para/usuarios.sqlite" EMAIL_HOST="mail.exemplo.com" EMAIL_PORT=465 EMAIL_USE_SSL=True # Usar SSL implícito para a porta 465 EMAIL_HOST_USER="gramps@exemplo.com" EMAIL_HOST_PASSWORD="..." # sua senha SMTP DEFAULT_FROM_EMAIL="gramps@exemplo.com"