Migrando a configuração para o .env

Guia para instalações que rodavam uma versão anterior do toolkit e vão atualizar para a 03.008.000 ou superior. O que muda para o administrador é onde os valores de configuração ficam:

• Antes: os valores ficavam no config/alfresco-global.properties (banco, hosts, e-mail, chaves htf.*, tokens) e espalhados no docker-compose.yml (código de instalação, senhas, dispositivos, proxy).
• Agora: tudo vem de um arquivo .env (ver Configuração via arquivo .env).

Sem quebra silenciosa

A leitura faz ENV primeiro, com fallback para o arquivo, e o run.sh sync é idempotente. Ainda assim, recomenda-se migrar os valores para o .env, que passa a ser o local oficial.

Procedimento

1. Guarde o alfresco-global.properties e o docker-compose.yml antigos — é de onde você copiará os valores que customizou (senha do banco, SMTP, chave do IA Gemini, tokens de assinatura, código de instalação, hostname, etc.).
2. No pacote novo, edite o .env (já vem com os valores padrão). Para cada valor que você tinha customizado, preencha a variável correspondente usando a tabela De-Para abaixo.
3. Suba normalmente com ./run.sh start. O run.sh preenche o alfresco-global.properties a partir do .env e sobe os serviços.
4. Confira com ./run.sh sync, que mostra o que foi escrito.

Regra geral das chaves htf.*

htf.x.y no properties antigo vira HTF_X_Y no .env (maiúsculas, pontos viram _). Exemplo: htf.gemini.keys torna-se HTF_GEMINI_KEYS.

Gerar o .env automaticamente (opcional)

Em vez de preencher o .env à mão, há um script que gera o .env a partir da instalação antiga: scripts/env_from_old.py.

1. Coloque os arquivos da versão anterior em uma pasta docker_old/ ao lado do .env — o alfresco-global.properties e o docker-compose.yml antigos.

2. Rode em modo de conferência (padrão), que só mostra o de-para e um relatório, sem gravar nada:

   python3 scripts/env_from_old.py

3. Revise o de-para e aplique, gravando o .env (o anterior é salvo em .env.bak):

   python3 scripts/env_from_old.py --apply

O script usa como modelo o .env que acompanha o pacote (preserva a ordem e os comentários, trocando só os valores encontrados) e cobre as chaves nativas, as htf.*, os nomes legados (ex.: iageminikeys) e os envs do docker-compose.yml antigo. No início, ele informa qual template e qual arquivo de saída está usando. Valores que no compose antigo eram ${VARIÁVEL} (interpolados de outro .env) não são adivinhados — apenas reportados para você preencher.

De-Para — valor antigo para variável do .env

Banco de dados

Antes	Agora (.env)
db.username	DB_USERNAME
db.password	DB_PASSWORD
db.url (nome do banco na URL)	DB_NAME (apenas o nome; o host fica fixo)

Host público e proxy

Antes	Agora (.env)
share.protocol + share.host + share.port (e alfresco.*)	PUBLIC_BASE_URL (ex.: https://meuservidor:8443)
IP do host (proxy/FTP/connector)	HOST_IP
SERVER_NAME / hosts do proxy	PROXY_SERVER_NAME, PROXY_AUTO_SELFSIGN_HOSTS, PROXY_DNSMASK_HOSTS
FORCE_SSL / AUTO_LETSENCRYPT / AUTO_SELFSIGN / DNSMASK / SERVER_EMAIL	PROXY_FORCE_SSL / PROXY_AUTO_LETSENCRYPT / PROXY_AUTO_SELFSIGN / PROXY_DNSMASK / PROXY_SERVER_EMAIL

Licença e Portal

Antes	Agora (.env)
INSTALLATION_CODE (serviço licensing)	INSTALLATION_CODE
API_KEY do Portal	usa o mesmo INSTALLATION_CODE
JWT_SECRET do Portal	PORTAL_JWT_SECRET

Keystore de metadados

Antes	Agora (.env)
metadata-keystore.password	METADATA_KEYSTORE_PASSWORD
metadata-keystore.metadata.password	METADATA_KEYSTORE_METADATA_PASSWORD

aviso

O padrão no .env já é o valor histórico que o toolkit sempre usou. Só altere se a sua instalação tiver um keystore com senha diferente — mudar sem regenerar o keystore quebra a criptografia de metadados.

E-mail (SMTP)

Antes	Agora (.env)
mail.host / mail.port / mail.username / mail.password / mail.protocol	MAIL_HOST / MAIL_PORT / MAIL_USERNAME / MAIL_PASSWORD / MAIL_PROTOCOL
mail.from.*, mail.smtp.*, mail.testmessage.*	MAIL_FROM_*, MAIL_SMTP_*, MAIL_TESTMESSAGE_*

Captura, workflow e demais opções

Antes	Agora (.env)
solr.sharedSecret	SOLR_SHARED_SECRET
htf.capture.web.*	HTF_CAPTURE_WEB_*
htf.capture.processor.*	HTF_CAPTURE_PROCESSOR_*
htf.process.workinghours.*	HTF_PROCESS_WORKINGHOURS_*
htf.twofa.* / htf.totp.issuer / htf.totp.period	HTF_TWOFA_* / HTF_TOTP_ISSUER / HTF_TOTP_PERIOD
htf.password.min.length	HTF_PASSWORD_MIN_LENGTH
htf.default.frontend	HTF_DEFAULT_FRONTEND
htf.restrict.usergroup.by.sites	HTF_RESTRICT_USERGROUP_BY_SITES
WSD_DEVICES / TWAIN_CONNECTORS (connector)	WSD_DEVICES / TWAIN_CONNECTORS

Integrações de assinatura e IA (tokens)

Antes	Agora (.env)
htf.gemini.keys / htf.gemini.max.concurrent.tasks	HTF_GEMINI_KEYS / HTF_GEMINI_MAX_CONCURRENT_TASKS
htf.certisign.*	HTF_CERTISIGN_*
htf.docusign.*	HTF_DOCUSIGN_*
htf.selbettissign.*	HTF_SELBETTISSIGN_*
htf.signer.tsa.*	HTF_SIGNER_TSA_*
htf.safeid.token (removido)	SafeID passou a OAuth: HTF_SAFEID_ENABLED, HTF_SAFEID_CLIENT_ID, HTF_SAFEID_CLIENT_SECRET, HTF_SAFEID_LOGIN_HINT, HTF_SAFEID_PIN
htf.paposms.token (removido)	SMS agora é conta própria: HTF_SMS_PROVIDER + HTF_SMS_SMSDEV_KEY ou HTF_PAPOSMS_USER/HTF_PAPOSMS_PASS

Para os cuidados de preenchimento (aspas, caracteres especiais, senha do banco na URL) e o pré-requisito de imagem, veja Configuração via arquivo .env.