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.

Importações de mídia e limites de upload

Use os valores abaixo como conjunto de referência no .env da instalação (.env.production no perfil Docker de produção). Instalações existentes precisam adicionar as variáveis: atualizar o template não modifica seu arquivo de ambiente.

MEDIA_MAX_FILE_SIZE=209715200
MEDIA_IMPORT_MAX_ARCHIVE_KB=1048576
MEDIA_IMPORT_MAX_ENTRY_BYTES=209715200
MEDIA_IMPORT_MAX_UNCOMPRESSED_BYTES=2147483648
MEDIA_IMPORT_MAX_ENTRIES=5000
MEDIA_IMPORT_MAX_COMPRESSION_RATIO=100
MEDIA_IMPORT_CHUNK_SIZE=50
MEDIA_IMPORT_CHUNK_SECONDS=30
MEDIA_IMPORT_WORKER_TIMEOUT=300
MEDIA_IMPORT_CONCURRENT_CHUNKS=1
MEDIA_IMPORT_RETENTION_DAYS=7
MEDIA_IMPORT_DELIVERY_RETRY_SECONDS=600
MEDIA_IMPORT_LOCK_STORE=redis
QUEUE_CONNECTION=redis
REDIS_DB=0
REDIS_CACHE_DB=1

MEDIA_MAX_FILE_SIZE limita cada mídia a 200 MiB e também participa dos limites de arquivos de outras importações. O ZIP aceita 1 GiB; cada entrada extraída, 200 MiB; o total descompactado, 2 GiB. Os tamanhos estão em bytes, exceto MEDIA_IMPORT_MAX_ARCHIVE_KB, em KiB. O limite de 5000 entradas inclui metadados e diretórios; a razão de compressão máxima é aplicada por entrada.

Cada execução processa até 50 linhas ou um orçamento de 30 segundos, verificado entre arquivos. Um arquivo pode ultrapassar esse orçamento; o timeout de 300 segundos limita a execução inteira, inclusive a preparação do ZIP. Os workers precisam de pcntl para aplicar esse timeout. Uma execução de mídia por vez é o ponto de partida para controlar CPU, memória e disco em instalações multiusuário. Aumentar o limite do upload não exige aumentar a concorrência.

Redis transporta os jobs e fornece locks compartilhados; o banco guarda o progresso. Separe o banco Redis das filas (0) do cache/locks (1). O scheduler recupera entregas interrompidas ou perdidas; 600 segundos é o intervalo de recuperação de referência, não o tempo normal entre partes da importação. Arquivos temporários de trabalhos inativos com falha ou cancelados expiram após 7 dias; depois disso é necessário reenviar o ZIP.

Alinhar aplicação, PHP e servidor web

O menor limite ao longo do caminho do upload prevalece. Livewire acompanha os limites configurados de ZIP/mídia, mas .env não altera o PHP, Apache, Nginx ou proxies externos. Para o conjunto acima, configure o PHP que atende o site:

upload_max_filesize = 1024M
post_max_size = 1100M
max_input_time = 1800

No Nginx use client_max_body_size 1100M;; no Apache use LimitRequestBody 1153433600. A margem acima de 1 GiB acomoda os demais dados da requisição. Aplique também os limites no proxy externo, quando houver. Não é necessário aumentar max_allowed_packet do MySQL para esses arquivos: ZIPs e mídias são armazenados em disco.

max_input_time é uma tolerância inicial para receber uploads lentos; buffering e timeouts do servidor/proxy também influenciam o resultado. Não aumente todos os timeouts para acomodar o tempo total do lote: o processamento ocorre na fila. Dimensione memória por imagem decodificada e concorrência, não pelo tamanho do ZIP. O limite de 200 MiB não garante que toda imagem caiba na memória disponível. Reserve espaço para uploads temporários, extração e mídias finais, considerando vários usuários; o limite descompactado é por arquivo ZIP, não uma cota global.

Fazer a configuração entrar em vigor

1. Edite o arquivo de ambiente efetivamente usado pela instalação.
2. Atualize a configuração com php artisan config:cache e reinicie os workers com php artisan queue:restart, mantendo o Supervisor ativo para relançá-los.
3. Confirme o php.ini do site: php --ini mostra apenas o CLI. Apache com mod_php e PHP-FPM usam configurações próprias; overrides de pool/VirtualHost também podem mudar os valores efetivos.
4. Valide e recarregue Apache/Nginx; reinicie ou recarregue o PHP-FPM quando usado.
5. No Docker, siga as instruções de reconstrução/recriação na página de instalação.
6. Teste um ZIP representativo e acompanhe o UserJob até terminar, incluindo uma retomada de falha. Confira scheduler, acesso ao armazenamento e logs dos workers.

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.