Configuração

Documentação · English

Carregamento e validação

As fontes de verdade são config/environment.py, config/engine.py, config/settings.py e .env.example. As configurações são carregadas ao iniciar o processo. Variáveis exportadas têm prioridade sobre .env; não há interpolação, então ${VALUE} permanece literal. Caminhos relativos partem da raiz do código; ~ expande para a pasta pessoal da conta do serviço.

Booleanos aceitam 1/true/yes/y/on e 0/false/no/n/off, sem distinguir maiúsculas. Grafias inválidas impedem a inicialização. Limites numéricos do engine devem ser positivos. Nos códigos, mínimo ≤ padrão ≤ máximo; a área do viewport não pode superar largura × altura. GRAVEWRIGHT_PORT deve ficar entre 1–65535. Origens públicas normalizam esquema e hostname para minúsculas, preservando portas explícitas e colchetes IPv6; assim, HTTPS://VTT.EXAMPLE.COM ativa as mesmas configurações HTTPS que https://vtt.example.com. Rejeitam caminhos, barra final, credenciais, portas vazias, caracteres de controle, query e fragmentos, incluindo delimitadores ? ou # vazios. Isso não significa que toda configuração use o mesmo parser numérico ou limite superior.

O executor Windows lê os padrões do .env.example e depois o .env na raiz do projeto, com limites de segurança locais impostos por seu perfil específico. Se o .env do projeto não existir, gera uma configuração completa a partir de .env.example, com uma nova chave privada. Nunca importa configurações da pasta de dados do usuário. A referência abaixo descreve as configurações padrão do servidor; os recursos também se aplicam ao executor, enquanto endereço de escuta, debug, cookies, host/origem, confiança de proxy e Channels em um único processo são fixados para execução local. Configure a porta do executor no .env do projeto.

Referência de ambiente

Os valores abaixo correspondem à configuração de exemplo/padrão. “Vazio” significa ausência de valor configurado. As explicações de bytes usam unidades binárias.

O instalador nativo configura automaticamente o Marketplace oficial quando não há catálogo configurado. Catálogos personalizados existentes são preservados.

Duas opções comentadas também são reconhecidas:

GRAVEWRIGHT_CONTAINER é lido pela descoberta de releases para identificar formato de instalação quando vale 1, true ou yes; não configura contêiner nem oferece atualização automática. DJANGO_SETTINGS_MODULE seleciona o módulo Python de configuração; os pontos de entrada usam config.settings por padrão.

Executor de Delay do Blueprint

O host ASGI inicia automaticamente o executor de Delay. Daphne usa os hooks de início/encerramento do reactor, inclusive no Runner habitual; outros hosts ASGI precisam enviar eventos lifespan de início/encerramento. Importar Django ou executar um comando de gerenciamento não inicia um agendador. O executor consulta as entradas vencidas no banco a cada 250 ms e processa até 20 por passagem; a execução pode ocorrer depois do prazo sob carga ou após indisponibilidade. Ele não exige navegadores conectados, consultas HTTP, tarefas Redis ou um processo iniciado separadamente.

Esperas pendentes ficam no SQLite configurado e sobrevivem ao reinício do servidor. GRAVEWRIGHT_AUTOMATION_WORKER_ENABLED=false desativa o processamento naquele processo sem descartar a fila. Pausar automação da cena conserva somente as esperas daquela cena até retomar. O sinalizador de manutenção existente do atualizador conserva a fila durante a verificação de saúde até confirmar ou reverter a atualização. Aplique as migrações habituais antes de iniciar o host; falhas de banco aparecem nos logs do servidor e geram novas tentativas, sem fingir execução bem-sucedida. Veja Delay persistente para cancelamento e cópia.

Geração de tiles e imagens grandes

GRAVEWRIGHT_MAP_MAX_PIXELS define o limite exato de pixels do mapa. Na inicialização, a proteção de cabeçalho do Pillow é elevada até pelo menos esse valor configurado, evitando um teto inferior sem relação com a configuração. Exceder qualquer proteção de pixels informa um erro de limite de pixels. Os limites independentes de bytes, dimensões e quantidade de tiles continuam aplicáveis. As duas configurações de pixels devem ser positivas; reinicie o servidor após alterá-las.

GRAVEWRIGHT_MAP_TILER=auto usa libvips quando disponível e Pillow nos demais casos. pillow sempre seleciona Pillow; vips exige libvips e impede a inicialização quando ele está indisponível. As dependências padrão e os instaladores nativos não selecionam o extra opcional vips. Para um ambiente do código-fonte, instale com:

uv sync --locked --extra vips

Para um Runner nativo, instale no ambiente Python indicado pelo inicializador gerado; a .venv do checkout pode ser outro ambiente. Mantenha --extra vips nas sincronizações de dependências seguintes. Um uv sync exato sem esse argumento, uma reinstalação nativa ou a preparação de uma atualização gerenciada do núcleo seleciona as dependências padrão e pode remover ou omitir o extra. Verifique novamente a disponibilidade após essas operações; definir GRAVEWRIGHT_MAP_TILER=vips não instala dependências.

Pillow decodifica o mapa inteiro. Seu teto adicional GRAVEWRIGHT_MAP_PILLOW_MAX_PIXELS tem padrão de 64 milhões de pixels, mesmo com um limite geral maior. Uma imagem maior exige libvips ou um aumento explícito desse teto após avaliar a memória disponível. Esse teto limita o tamanho de imagem aceito, não a memória residente: decodificação, orientação, reamostragem e codecs também alocam memória. Libvips processa mapas comuns em faixas, mas formatos, codecs e rotações EXIF podem exigir memória adicional e espaço temporário em disco.

Apenas uma pirâmide de mapa é gerada por vez em cada processo do servidor, incluindo a decodificação. Workers separados ainda podem processar mapas simultaneamente. Os dois mecanismos produzem tiles WebP sem perdas, com a mesma disposição de 512 pixels e tiles parciais nas bordas; os níveis reduzidos podem diferir porque os filtros de reamostragem são diferentes.

A geração nativa prepara a imagem-fonte e os tiles em data/runner/tmp/ dentro da instalação. Um GRAVEWRIGHT_RUNNER_ROOT explícito altera a raiz das ferramentas, e um override Django de FILE_UPLOAD_TEMP_DIR tem prioridade para a área temporária dos tiles; caminhos relativos partem da raiz da instalação. A pasta deve permitir escrita e comportar a fonte, os tiles preparados e eventuais arquivos temporários dos codecs enquanto os tiles finais são gravados na mídia. Falhas de armazenamento ou de geração nativa permanecem erros do servidor, e tiles já gravados são removidos se o upload falhar. Consulte implantação para timeouts de upload síncrono e dimensionamento.

Configurações sem variáveis de ambiente

Estas opções são definidas em Python, sem leitura automática de entradas com o mesmo nome no .env:

Corpos de autenticação têm limite separado de 16 KiB no middleware. Importações/exportações têm limites em gravewright/administration/archives.py. Uploads de mapa têm limites independentes de bytes, imagem decodificada e tiles gerados. Confira o código responsável antes de presumir que um limite governa todos os caminhos.

Preferências persistidas da instância

gravewright.administration.preferences armazena identidade, canais de atualização e conteúdo de privacidade no singleton HostSettings. APP_NAME e DEFAULT_LOCALE são fallbacks, sem substituir obrigatoriamente os valores salvos. A lista de idiomas suportados é ('en',). Definir DEFAULT_LOCALE=pt-BR não acrescenta uma interface em português.

A publicação da privacidade fica ativa se a opção de ambiente ou a persistida for verdadeira. Retenção de snapshots/auditoria é aplicada pelos fluxos das operações, não por um agendador em segundo plano fornecido pelo projeto. Preferências individuais e configurações de campanha são separadas das configurações da instância.

Para HTTPS, defina a origem pública exata acessada pelo navegador, incluindo portas diferentes da padrão. Outras entradas em DJANGO_ALLOWED_HOSTS não se tornam origens WebSocket adicionais quando existe origem pública configurada. Sem ela, a validação WebSocket deriva a origem do esquema ASGI e Host; esquema ausente assume HTTP.

O adaptador de proxy ASGI aceita exatamente um cabeçalho X-Forwarded-Proto com valor http ou https apenas do par imediato conectado em TRUSTED_PROXIES. Ignora valores duplicados, separados por vírgula, malformados ou de origem não confiável. Mantenha --proxy-headers do Daphne desativado para preservar o endereço original nessa verificação. A mesma lista controla o IP encaminhado. Veja implantação para um exemplo de proxy TLS e requisitos de Redis e armazenamento.