Configuração via arquivo .env
A partir da versão 03.008.000, a configuração que muda por instalação é centralizada em um único arquivo .env, na pasta do pacote de instalação. Esse .env é compartilhado pelos três componentes do ambiente — toolkit, Content App e Portal.
Você não edita mais o alfresco-global.properties nem espalha valores pelo docker-compose.yml. Você edita o .env.
Como funciona
- O
.envé a fonte da verdade dos valores de configuração da instalação (banco, hosts, e-mail, chaveshtf.*, tokens de integração, código de instalação, etc.). - Ao subir, o
run.shescreve os valores do.envnoalfresco-global.properties(que vai versionado vazio, como modelo) e injeta as variáveis de ambiente nos containers. - O
alfresco-global.propertiesversionado passa a conter apenas a infraestrutura interna fixa (driver do banco, nomes internos de serviço, mensageria, agendamentos) e as chaves que o Java lê, vazias — preenchidas a partir do.env.
Subindo o ambiente
cp .env.example .env # primeira vez: copie o modelo
# edite o .env com os valores da sua instalação
./run.sh start # sobe o ambiente
Para conferir os valores aplicados ao alfresco-global.properties:
./run.sh sync
O comando sync é idempotente: se o valor já corresponde ao do .env, nada muda.
Após alterar qualquer valor no .env, é necessário subir novamente (ou reiniciar) os serviços para aplicar.
Cuidados ao preencher o .env
- Não envolva os valores em aspas. O valor é literal até o fim da linha. Caracteres como
@,:,/, espaços e acentos não precisam de escape (ex.:MAIL_PASSWORD=ab@c123def). - Evite o caractere
$nas variáveis usadas pelo Docker Compose (comoDB_PASSWORD,DB_USERNAME,DB_NAME,INSTALLATION_CODE,PORTAL_JWT_SECRET,PUBLIC_BASE_URL,SOLR_SHARED_SECRET,HOST_IP). - A
DB_PASSWORDé usada na URL de conexão do Portal — evite os caracteres@ : / ? #nessa senha, pois quebram a URL. - Integrações que você não usa (token vazio): deixe a variável vazia no
.env.
Chaves de configuração
Além das chaves básicas (banco, hosts, e-mail, tokens de integração), o .env do pacote traz as chaves abaixo. Todas já vêm com um valor padrão adequado; altere apenas o que a sua instalação exigir.
Algoritmo de hash global
| Chave | Padrão | Descrição |
|---|---|---|
HTF_HASH_ALGORITHM | sha-256 | Algoritmo de hash de todos os documentos da plataforma (por página, de conteúdo, base e do documento), com ou sem guarda documental. Valores: md2, md5, sha-1, sha-256, sha-384, sha-512. |
HTF_HASH_RESPECTEXISTING | true | Com true, o documento que já tem um algoritmo gravado mantém o dele (um acervo legado em MD5 continua em MD5 e reprodutível); só documentos novos usam o algoritmo global. Com false, todo recálculo passa a usar o algoritmo global, alterando os hashes dos documentos legados no próximo reprocessamento. |
O algoritmo não é escolhido por documento, perfil, ação ou execução de preservação: a escolha é única, feita aqui. O hash é gerado em todo documento capturado, e o campo de tipo de hash no cartão de metadados é somente leitura.
Segurança, senhas e interface
| Chave | Padrão | Descrição |
|---|---|---|
HTF_TWOFA_ENABLED / HTF_TWOFA_FORCE | false | Habilita o 2FA e, opcionalmente, o torna obrigatório. |
HTF_TOTP_ISSUER / HTF_TOTP_PERIOD | HTF Apps Toolkit / 30 | Nome exibido no aplicativo autenticador e período do código, em segundos. |
HTF_PASSWORD_MIN_LENGTH | conforme o pacote | Comprimento mínimo de senha, aplicado a todas as telas de definição e troca de senha. |
HTF_DEFAULT_FRONTEND | share | Interface padrão do usuário (share ou aca). |
HTF_RESTRICT_USERGROUP_BY_SITES | conforme o pacote | Restringe a listagem de usuários e grupos aos sites do usuário. |
CA_REFRESH_ON_BOOT | false | Atualiza o conjunto de CAs de confiança a cada inicialização. Veja Parametrizando certificado SSL. |
Operação e guarda
| Chave | Padrão | Descrição |
|---|---|---|
HTF_PRESERVATION_DISABLEBOOT | false | Uso em emergência: com true, desliga na inicialização a retomada da Preservação e o supervisor da preservação diária (evita ciclos de falta de memória quando uma execução travou por um arquivo muito grande). Execuções manuais continuam possíveis. |
HTF_CUSTODY_VERSIONCLEANENABLED | false | Política da instalação para limpar o histórico de versões. Com false, ninguém pode limpar versões. |
HTF_SEARCH_ACCELERATED | true | Busca acelerada de tarefas e fluxos (ver notas de upgrade das Notas de Lançamento). |
HTF_SEARCH_MINWORDLEN | 5 | Tamanho mínimo, em caracteres, das palavras indexadas na busca acelerada (mínimo efetivo 5; números com 4 ou mais dígitos, como CPF e telefone, entram sempre). Alterar o valor refaz o índice na próxima inicialização, com a mesma janela de indisponibilidade do /process. Só vale com a busca acelerada ligada. |
Captura
| Chave | Descrição |
|---|---|
HTF_CAPTURE_PROCESSOR_RUNINSTANCES / HTF_CAPTURE_PROCESSOR_RUNIFWAITINGINSTANCES | Quantidade de instâncias de captura simultâneas e quantas rodam quando há instâncias aguardando. |
HTF_CAPTURE_PROCESSOR_JOINER_MAX | Máximo de arquivos consolidados por documento. |
HTF_CAPTURE_WEB_MAX_FILES / HTF_CAPTURE_WEB_MAX_FILESIZE / HTF_CAPTURE_WEB_MAX_TOTAL_FILESSIZE | Limites de envio pelo Capture Web: quantidade de arquivos, tamanho por arquivo e tamanho total (MB). |
LOGIN_REQUIRED | on exige login no Capture Web; off permite acesso anônimo. |
WSD_DEVICES / TWAIN_CONNECTORS | Dispositivos de captura de rede (conector). Vazio, nenhum. |
Backup Agent
| Chave | Descrição |
|---|---|
RESTIC_PASSWORD | Senha do backup incremental. Vazia, o Backup Agent gera uma automaticamente. Defina para fixá-la e torná-la reproduzível; não a troque depois do primeiro backup incremental. Evite o caractere $. Veja Backup Agent. |
Chaves de IA e assinatura
HTF_GEMINI_KEYS e HTF_GEMINI_MAX_CONCURRENT_TASKS são descritas em IA Gemini, com o passo a passo para criar a chave da API. As chaves de TSA, SafeID, DocuSign, Certisign, Selbetti e SMS têm página própria na seção Integrações.
Esta versão lê várias chaves htf.* a partir do ambiente. Use as imagens prestobr/toolkit-* desta versão em diante. Uma imagem de versão anterior combinada com o modelo novo faria essas chaves virem vazias.