Configuração administrativa

O OpenDataBio funciona sem serviços externos opcionais, mas administradores precisam decidir explicitamente sobre envio de e-mail, serviços taxonômicos, tradução assistida e os locales disponíveis aos usuários. Mantenha credenciais no arquivo de ambiente da instalação; nunca as versione no repositório.

Os templates de ambiente distribuídos deixam USER_TRANSLATION_PROVIDER e todas as credenciais de serviços vazios. Assim, instalações Apache, nginx e Docker não ativam tradução silenciosamente nem fazem chamadas externas. No instalador interativo para servidor direto, aceitar a resposta padrão não à pergunta opcional do Google mantém o recurso desabilitado. Só configure esses serviços depois de definir quem administrará credenciais, cotas e custos.

Depois de alterar .env ou .env.production, atualize a configuração:

php artisan optimize:clear
php artisan config:cache

Em produção com Docker, execute o Artisan no container da aplicação e use caminhos visíveis dentro desse container.

Google Cloud Translation

O OpenDataBio usa o Cloud Translation Advanced (v3) somente para conteúdo mantido pelos usuários nos formulários de edição. Textos da interface em lang/ não são enviados ao Google. O texto gerado preenche campos ausentes e deve ser revisado antes de salvar o registro. Jobs de importação nunca chamam o Google automaticamente.

O Google exige faturamento ativo mesmo quando o consumo permanece dentro de eventual crédito gratuito. Consulte os preços atuais, configure alerta de orçamento e restrinja cotas antes de habilitar o serviço.

1. Entre no console do Google Cloud.
2. Crie ou selecione um projeto e anote o ID do projeto.
3. Vincule uma conta de faturamento.
4. Em APIs e serviços, habilite Cloud Translation API.
5. Em IAM e administrador → Contas de serviço, crie uma conta exclusiva para o OpenDataBio.
6. Conceda a ela Usuário da API Cloud Translation (roles/cloudtranslate.user). Não conceda Proprietário, Editor, Administrador nem o papel de agente de serviço do Cloud Translation.
7. Crie uma chave JSON para a conta de serviço e faça o download. Guarde-a fora do repositório, legível pelo usuário do servidor web e não pelos demais usuários do sistema.
8. Configure:

USER_TRANSLATION_PROVIDER=google
GOOGLE_CLOUD_PROJECT=id-do-projeto-google
GOOGLE_TRANSLATION_LOCATION=global
GOOGLE_APPLICATION_CREDENTIALS=/caminho/absoluto/google-translation.json
USER_TRANSLATION_MAX_CHARACTERS_PER_REQUEST=10000
USER_TRANSLATION_TIMEOUT=30

No Apache ou nginx, o arquivo e seus diretórios-pai precisam ser acessíveis ao usuário do PHP/servidor web. Um arranjo típico é:

sudo chgrp www-data /caminho/seguro/google-translation.json
sudo chmod 750 /caminho/seguro
sudo chmod 640 /caminho/seguro/google-translation.json

Em produção com Docker, coloque o arquivo no diretório não versionado docker-secrets/, monte-o somente para leitura e use o caminho interno:

GOOGLE_APPLICATION_CREDENTIALS=/run/secrets/google-translation.json

Valide primeiro sem solicitação externa e depois com uma tradução curta:

php artisan translations:check --source=en --target=es
php artisan translations:check --source=en --target=es --live

Para desabilitar a tradução assistida, deixe USER_TRANSLATION_PROVIDER vazio.

Tropicos

O Tropicos Web Services exige uma chave pessoal em todas as solicitações.

Configurá-lo melhora a curadoria taxonômica, permitindo procurar e validar nomes botânicos publicados no Tropicos, em vez de depender somente da biblioteca local ou de outras fontes externas.

1. Abra a página de solicitação de chave do Tropicos.
2. Informe o contato e a finalidade de uso solicitados.
3. Guarde a chave emitida no ambiente:

MOBOT_API_KEY=sua-chave-api-tropicos

Sem a chave, o OpenDataBio continua funcionando e outros serviços taxonômicos configurados, principalmente o GBIF, ainda podem ser usados. Não exponha a chave no código cliente nem a versione.

Identificação de imagens com Pl@ntNet

O OpenDataBio pode enviar de uma a cinco imagens da mesma planta ao Pl@ntNet e apresentar candidatos em espécie, gênero e família para revisão humana. Os resultados são cacheados, nenhuma identificação é alterada automaticamente e a aplicação de um candidato continua sujeita às permissões normais do OpenDataBio.

Crie gratuitamente uma conta de desenvolvedor na página de cadastro do Pl@ntNet e gere ou gerencie a chave em configurações da API key. Consulte o guia oficial de primeiros passos e a referência da API para cotas, termos e detalhes atuais das requisições.

O OpenDataBio aceita duas fontes de credencial:

• Chave do servidor: configurada pelo administrador e compartilhada pelos usuários que não possuem chave pessoal. A cota pertence à instalação.
• Chave pessoal: cadastrada pelo usuário registrado em Editar perfil. Ela é criptografada no banco, tem preferência sobre a chave do servidor e utiliza a cota independente daquela conta no Pl@ntNet.

Para oferecer uma chave compartilhada pela instalação, configure:

PLANTNET_API_KEY=sua-chave-plantnet-do-servidor
PLANTNET_ALLOW_USER_KEYS=true
PLANTNET_SERVER_FALLBACK=true
PLANTNET_DAILY_REQUEST_LIMIT=500
PLANTNET_DAILY_USER_LIMIT=20

Nessa configuração, chaves pessoais têm preferência. Quem não possui uma usa PLANTNET_API_KEY. PLANTNET_DAILY_REQUEST_LIMIT é um teto local de segurança por credencial; PLANTNET_DAILY_USER_LIMIT limita o uso da chave compartilhada por usuário não administrador. O saldo remoto informado pelo Pl@ntNet também é respeitado. Administradores não estão sujeitos ao limite individual da chave compartilhada, mas continuam sujeitos às cotas local e remota da credencial.

Para exigir chaves pessoais e não compartilhar uma cota da instalação:

PLANTNET_API_KEY=
PLANTNET_ALLOW_USER_KEYS=true
PLANTNET_SERVER_FALLBACK=false
PLANTNET_DAILY_REQUEST_LIMIT=500

Nesse modo, o Pl@ntNet permanece disponível para todo usuário que cadastrar uma chave pessoal válida. Quem não possui uma chave não vê a ação de identificação. Deixar PLANTNET_API_KEY vazia não desabilita as chaves pessoais.

Para impedir credenciais pessoais e usar somente a chave da instalação, configure PLANTNET_ALLOW_USER_KEYS=false. Quando não houver chave pessoal permitida nem fallback de servidor habilitado, a identificação pelo Pl@ntNet fica indisponível; o restante do OpenDataBio continua funcionando.

As requisições partem do servidor OpenDataBio, não diretamente do navegador. Por isso, no uso normal não é preciso habilitar Expose my API key nem adicionar a URL do OpenDataBio aos domínios CORS autorizados no Pl@ntNet. Se o administrador decidir expor a chave nas configurações do Pl@ntNet, deve seguir as instruções atuais do serviço e autorizar o IP do servidor para requisições sem CORS.

Depois de alterar o ambiente, execute os comandos de atualização de configuração indicados no início desta página. Nunca versione chaves do servidor ou pessoais.

E-mail

E-mail é usado para recuperação de senha, verificação opcional de endereço, solicitações de datasets e notificações de jobs. Instalações de produção devem usar uma conta SMTP dedicada ou um provedor transacional.

Sem e-mail funcional, administradores precisam atender recuperações de conta manualmente, usuários podem não receber decisões sobre pedidos de acesso e jobs longos não conseguem avisar com segurança quando exigem atenção.

MAIL_MAILER=smtp
MAIL_HOST=smtp.exemplo.org
MAIL_PORT=587
MAIL_USERNAME=opendatabio@exemplo.org
MAIL_PASSWORD=substitua-pelo-segredo
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=opendatabio@exemplo.org
MAIL_FROM_NAME="${APP_NAME}"
MAIL_VERIFY_PEER=true
MAIL_VERIFY_PEER_NAME=true
MAIL_ALLOW_SELF_SIGNED=false
EMAIL_VERIFICATION_ENABLED=false

Use a porta 465 e a criptografia exigida pelo provedor quando aplicável. Mantenha a verificação de certificados habilitada em produção. Só habilite EMAIL_VERIFICATION_ENABLED depois de testar envio e recuperação de senha. Os workers da fila precisam estar ativos para notificações enfileiradas.

Responsabilidades dos locales

O OpenDataBio mantém três conceitos separados:

• APP_LOCALE é o locale principal permanente e é sempre obrigatório no conteúdo traduzível.
• Locales de interface possuem todos os arquivos de tradução em lang/<codigo>/.
• Locales de conteúdo são idiomas nos quais usuários podem manter valores de UserTranslation; não exigem tradução da interface.

ODB_INTERFACE_LOCALES e ODB_CONTENT_LOCALES inicializam uma instalação nova. Em uma instalação existente, use Admin → Locales da aplicação ou:

php artisan locales:configure --interfaces=en,es,pt-br --content=en,es,pt-br
php artisan locales:audit

Adicionar um locale somente para conteúdo

1. Em Admin → Locales da aplicação, adicione um código normalizado, como fr ou es-mx, e um nome legível.
2. Habilite Conteúdo do usuário.
3. Não habilite Interface sem que lang/<codigo>/ esteja completo.
4. Adicione um mapeamento em config/user-translation.php se o provedor não aceitar diretamente o código usado pela aplicação.

Registros existentes não são preenchidos automaticamente. Usuários podem abrir os formulários de edição e gerar explicitamente traduções ausentes. Importações em lote precisam fornecer suas traduções explicitamente.

Adicionar um novo locale de interface

1. Copie toda a estrutura de chaves de um diretório lang/<codigo>/ existente para lang/<novo-codigo>/.
2. Traduza cada valor no contexto da aplicação sem alterar chaves, placeholders, estrutura HTML ou sintaxe de pluralização.
3. Adicione o nome do locale em config/languages.php.
4. Execute a auditoria de locales e os testes da aplicação.
5. Implante o código contendo os arquivos de tradução.
6. Adicione/habilite o locale pela página administrativa ou por locales:configure.
7. Limpe os caches. Reconstrua resources/api/odb_param_schema.json usando seu gerador ao publicar mudanças de documentação/schema; nunca edite o JSON gerado manualmente.

Ao atualizar o OpenDataBio, compare o novo .env.example com o ambiente implantado, execute as migrations, rode php artisan locales:audit e atualize cada diretório lang/<codigo>/ instalado com novas chaves antes de habilitar a interface.