Primeiros passos

• 1: Primeira vez?
• 2: Instalação padrão
• 3: Instalação com Docker
• 4: Instalação com Nginx
• 5: Personalizar a instalação
• 6: Atualizar OpenDataBio
• 7: Configuração administrativa

1 - Primeira vez?

OpenDataBio é normalmente acessado em um servidor mantido por uma instituição ou grupo de pesquisa. As funcionalidades disponíveis dependem do seu nível de usuário e das permissões concedidas em cada projeto, dataset ou biocoleção.

Escolha seu ponto de partida

• Quero apenas consultar ou baixar dados: comece por Pesquisar e mapear dados.
• Quero inserir ou importar dados: leia Preparar uma conta de usuário pleno e depois escolha um dos fluxos de entrada de dados.
• Sou responsável por um dataset: leia Organizar e publicar datasets.
• Trabalho com vouchers ou uma biocoleção: consulte Vouchers, etiquetas e solicitações.
• Sou administrador da instalação: veja Responsabilidades do superadministrador e a seção de instalação e administração.

Papéis e permissões

Visitante

Sem iniciar uma sessão, um visitante pode consultar registros públicos, usar os exploradores, visualizar datasets e versões públicas e baixar dados cuja política permita acesso anônimo. Não pode inserir ou alterar registros.

Usuário registrado

O autocadastro cria uma conta básica. Um usuário registrado pode editar o próprio perfil e acessar dados disponibilizados para usuários autenticados. A instalação pode exigir autenticação e aceite de um acordo para determinados downloads. O cadastro, por si só, não autoriza a inserção de dados.

Usuário pleno

Um superadministrador, ou um usuário pleno autorizado a gerenciar acessos, pode promover uma conta registrada para usuário pleno. Esse nível permite criar dados e receber papéis de colaboração, mas cada operação continua dependendo das permissões do objeto. Ser usuário pleno não concede acesso a todos os datasets nem permite administrar a instalação.

Um usuário pleno pode, quando autorizado:

• criar registros nas bibliotecas compartilhadas;
• criar projetos e datasets;
• inserir dados pela interface ou por formulários;
• importar planilhas e usar a API;
• executar e acompanhar UserJobs;
• administrar objetos nos quais recebeu o papel apropriado.

Curador de Traits

Um superadministrador pode conceder a um usuário pleno a habilidade Curador de Traits. Curadores revisam sugestões de duplicação, varrem e consolidam a biblioteca pública de Traits, registram decisões de não duplicação e arquivam ou restauram Traits permitidos. Usuários plenos comuns podem examinar um Trait individual e sugerir duplicação, mas não podem executar uma mesclagem. Essa habilidade é independente dos papéis de projeto e dataset. Consulte Governança e curadoria de Traits.

Gestor de acesso de usuários

Um superadministrador pode conceder a um usuário pleno a permissão gerenciar acessos de usuários. Esse gestor pode:

• promover um usuário registrado para usuário pleno;
• rebaixar um usuário pleno para usuário registrado.

Essa delegação é limitada. O gestor de acesso não pode criar, promover ou remover superadministradores; não pode alterar outro gestor de acesso; e não pode conceder essa permissão a outras pessoas. Somente um superadministrador pode designar ou remover gestores de acesso.

Antes de promover uma conta, o gestor deve confirmar a identidade do usuário e seguir a política local da instalação. A promoção autoriza a criação de dados, mas não concede automaticamente participação em projetos, datasets ou biocoleções.

Administrador, colaborador e visualizador

Projetos, datasets e biocoleções possuem seus próprios participantes:

As regras específicas variam conforme o tipo de objeto. Por exemplo, o administrador de um dataset pode preparar versões e revisar suas políticas; o administrador de uma biocoleção controla os vouchers e solicitações sob a responsabilidade da coleção.

Superadministrador da instalação

O superadministrador tem acesso global e mantém a instalação. Ele deve:

• revisar novos usuários e atribuir níveis globais com cuidado;
• designar quais usuários plenos podem promover ou rebaixar contas;
• configurar integrações e serviços externos;
• habilitar biocoleções administradas pelo sistema;
• manter localidades e outros registros de referência do sistema;
• revisar ferramentas administrativas, como duplicidades e validações;
• monitorar filas, armazenamento, logs e backups;
• aplicar atualizações e os procedimentos do UPGRADES_NOTES.md.

O superadministrador não deve substituir os responsáveis científicos por projetos e datasets na curadoria cotidiana dos dados.

Preparar uma conta de usuário pleno

1. Confirme que sua conta foi promovida a usuário pleno.
2. Crie ou localize seu registro de Pessoa e associe-o como pessoa padrão do seu perfil. Isso permite preencher automaticamente autoria, coleta, medição e identificação quando apropriado.
3. Defina em qual projeto e dataset os novos registros serão organizados. Crie novos objetos apenas quando os existentes não representam o mesmo trabalho.
4. Consulte as regras locais da instalação para bibliotecas compartilhadas, evitando duplicar pessoas, taxons, localidades, referências ou variáveis.

Inserir e importar dados

Escolha o método conforme o volume e a maturidade dos seus dados:

1. Interface web: melhor para aprender o modelo, criar poucos registros e conferir validações.
2. Formulários: adequados para protocolos repetíveis de coleta e medição.
3. OpenDataBio Collect: usa formulários compatíveis para coleta móvel, inclusive offline.
4. Planilhas: permitem importação em lote pela interface. Os nomes das colunas correspondem aos parâmetros POST da API.
5. OpenDataBio-R: facilita preparar, validar, importar e consultar dados a partir do R.
6. API direta: indicada para integrações e clientes em outras linguagens.

Comece criando manualmente um exemplo pequeno de cada objeto necessário. Depois exporte ou consulte esse registro para confirmar nomes de campos, relações e identificadores antes de preparar um lote grande.

Ordem recomendada para novos dados

Cadastre ou localize primeiro as bibliotecas reutilizadas:

1. pessoas e referências bibliográficas;
2. taxons e localidades que ainda não existam;
3. traits, unidades, categorias e formulários;
4. projeto e dataset;
5. indivíduos e vouchers;
6. medições, identificações e mídias.

Uma localidade do tipo ponto não precisa ser criada antecipadamente quando a importação de indivíduos informa coordenadas e o fluxo utilizado permite sua criação automática. Parcelas, transectos e polígonos, entretanto, devem ser planejados e validados antes de importar grandes quantidades de indivíduos.

Antes de importar um lote grande

• teste algumas linhas pela interface ou em uma instalação de testes;
• confirme o dataset e as permissões de destino;
• valide datas, coordenadas e identificadores usados nas relações;
• separe nomes taxonômicos publicados de nomes não publicados;
• verifique se pessoas, referências e traits já existem;
• acompanhe o UserJob até o fim e examine avisos e erros por registro;
• exporte uma amostra após a importação para conferir o resultado.

Os tutoriais de R transformam essa sequência em exemplos reproduzíveis de consulta e importação. Antes deles, consulte o Fluxo de importação de dados para entender dependências, validação prévia de coordenadas, UserJobs e reconciliação de IDs.

2 - Instalação padrão

Estas instruções são para instalação baseada em apache. Para nginx, use Instalação com Nginx.

Requisitos do servidor

1. A versão suportada do PHP >= 8.2 (8.3 recomendado).
2. Servidor web: apache para este guia. Para nginx, use Instalação com Nginx.
3. Requer um banco de dados SQL, MySQL e MariaDB foram testados, mas também pode funcionar com Postgres. Testado com MySQL 8.0 e MariaDB 10.6+.
4. Extensões PHP necessárias: openssl, pdo, pdo_mysql, mbstring, tokenizer, xml, dom, gd, exif, bcmath, zip, curl, redis.
5. Redis Server é necessário para filas e cache.
6. Tectonic é usado para geração de PDFs/etiquetas a partir de LaTeX.
7. Pandoc é usado para traduzir o código LaTeX usado nas referências bibliográficas. Não é necessário para a instalação, mas é sugerido para uma melhor experiência do usuário.
8. Requer Supervisor, que é necessário para os jobs de usuário
9. Node.js 22 com npm é necessário para compilar o frontend durante a instalação e as atualizações.

Criar usuário dedicado

A maneira recomendada de instalar o OpenDataBio para produção é usando um usuário de sistema dedicado. Nestas instruções, esse usuário é odbserver.

Baixar OpenDataBio

Faça login como seu Usuário dedicado e baixe ou clone este software para onde deseja instalá-lo. Aqui assumimos que é /home/odbserver/opendatabio para que os arquivos de instalação residam neste diretório. Se este não for o seu caminho, altere abaixo sempre que aplicável.

Prepare o Servidor

Primeiro, instale os softwares Apache, MySQL, PHP, Redis, Tectonic, Pandoc e Supervisor. Em um sistema Debian, você também precisa instalar algumas extensões PHP e ativá-las:

sudo apt-get install software-properties-common
sudo add-apt-repository ppa:ondrej/php
sudo add-apt-repository ppa:ondrej/apache2

sudo apt-get install mysql-server redis-server tectonic php8.3 libapache2-mod-php8.3 php8.3-intl \
 php8.3-mysql php8.3-sqlite3 php8.3-gd php8.3-cli pandoc \
 php8.3-mbstring php8.3-xml php8.3-bcmath php8.3-zip php8.3-curl php8.3-redis \
 supervisor

sudo a2enmod php8.3
sudo phpenmod mbstring
sudo phpenmod xml
sudo phpenmod dom
sudo phpenmod gd
sudo a2enmod rewrite
sudo a2enmod alias
sudo a2enmod headers
sudo systemctl restart apache2.service

# Verifique se os requisitos estão instalados:
php -m | grep -E 'mbstring|cli|xml|gd|mysql|redis|bcmath|pcntl|zip'
tectonic --version
redis-server --version

Adicione um VirtualHost dedicado à configuração do Apache.

• Mude /home/odbserver/opendatabio para o seu caminho (os arquivos devem estar acessíveis pelo apache)
• Crie /etc/apache2/sites-available/opendatabio.conf com o conteúdo abaixo.
• Este exemplo instala a aplicação em /opendatabio. Em uma instalação pública, substitua localhost pelo nome real do servidor.

<VirtualHost *:80>
    ServerName localhost
    ServerAdmin webmaster@localhost
    DocumentRoot /var/www/html

    RedirectMatch 302 ^/$ /opendatabio/
    RedirectMatch 301 ^/opendatabio$ /opendatabio/

    Alias /opendatabio/ "/home/odbserver/opendatabio/public/"

    <Directory "/home/odbserver/opendatabio/public">
        Options FollowSymLinks
        AllowOverride All
        Require all granted
        DirectoryIndex index.php
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/opendatabio-error.log
    CustomLog ${APACHE_LOG_DIR}/opendatabio-access.log combined
</VirtualHost>

O alias principal serve todos os assets públicos, incluindo build, imagens, fontes e assets do Livewire. Não são necessários aliases separados para esses diretórios.

echo 'ServerName localhost' | sudo tee /etc/apache2/conf-available/servername.conf
sudo a2enconf servername
sudo a2enmod alias rewrite headers php8.3
sudo a2dissite 000-default
sudo a2ensite opendatabio
sudo apache2ctl configtest
sudo systemctl reload apache2

Não recarregue o Apache a menos que apache2ctl configtest retorne Syntax OK.

Content Security Policy (CSP) para Apache

Configure o CSP na camada do servidor web (não nos arquivos Laravel). Aplique primeiro em modo report-only, valide os logs e depois migre para enforcement.

Para instalação standalone com nginx, use Instalação com Nginx.

Apache: onde colocar

1. Habilite o módulo necessário:

sudo a2enmod headers
sudo systemctl restart apache2

2. Edite o arquivo de vhost ativo (exemplo):

sudo nano /etc/apache2/sites-available/opendatabio.conf

3. Dentro do bloco <VirtualHost ...> correto (HTTP e/ou HTTPS), adicione o cabeçalho em uma única diretiva:

Header always set Content-Security-Policy-Report-Only "default-src 'self'; base-uri 'self'; form-action 'self'; frame-ancestors 'self'; object-src 'none'; script-src 'self' 'unsafe-eval' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob: https://server.arcgisonline.com https://*.tile.openstreetmap.org; font-src 'self' data:; connect-src 'self'; media-src 'self' blob:; worker-src 'self' blob:;"

4. Recarregue o Apache:

sudo apachectl configtest
sudo systemctl reload apache2

Instalações em subcaminho (/opendatabio)

Se sua instalação roda em subcaminho (por exemplo http://localhost/opendatabio), ajuste no .env:

APP_URL=http://localhost/opendatabio
ASSET_URL=http://localhost/opendatabio

Depois recompile todos os assets gerados:

sh scripts/build-assets.sh
php artisan optimize:clear

Notas

1. https://server.arcgisonline.com e https://*.tile.openstreetmap.org são necessários para tiles do mapa.
2. unsafe-inline / unsafe-eval são flags temporárias de compatibilidade; remova após endurecer templates/assets.
3. Mantenha Report-Only enquanto ajusta a política em produção.

Configure os arquivos php.ini. Com libapache2-mod-php8.3, os arquivos relevantes são /etc/php/8.3/cli/php.ini e /etc/php/8.3/apache2/php.ini. Uma instalação com FPM usa /etc/php/8.3/fpm/php.ini.

Atualize os valores para as seguintes variáveis:

Encontre os arquivos
php -i | grep 'Configuration File'

Mudar:
	memory_limit should be at least 512M
	post_max_size should be at least 30M
	upload_max_filesize should be at least 30M

Algo como:

[PHP]
allow_url_fopen=1
memory_limit = 512M

post_max_size = 100M
upload_max_filesize = 100M

Mysql Charset e Collation

1. Você deve adicionar o seguinte ao seu arquivo de configuração do SQL (mariadb.cnf ou my.cnf), ou seja, o conjunto de caracteres e o agrupamento que você escolher para sua instalação devem corresponder aos do config/database.php

[mysqld]
character-set-client-handshake = FALSE  #without this, there is no effect of the init_connect
collation-server      = utf8mb4_unicode_ci
init-connect          = "SET NAMES utf8mb4 COLLATE utf8mb4_unicode_ci"
character-set-server  = utf8mb4
log-bin-trust-function-creators = 1
sort_buffer_size = 256M  #espaco suficiente para consultas com geometria
max_allowed_packet=100M

# Somente MariaDB:
[mariadb]
innodb_log_file_size=300M

2. Se estiver usando MariaDB e você ainda tiver problemas do tipo #1267 Illegal mix of collations, então verifique aqui sobre como consertar isso.

Configurar o supervisord

Configure o Supervisor, necessário para os jobs. Crie o arquivo opendatabio-worker.conf em /etc/supervisor/conf.d/opendatabio-worker.conf com o conteúdo abaixo, ajustando o caminho conforme sua instalação:

touch /etc/supervisor/conf.d/opendatabio-worker.conf
echo ";--------------
[program:opendatabio-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /home/odbserver/opendatabio/artisan queue:work --sleep=3 --tries=1 --timeout=0 --memory=512
autostart=true
autorestart=true
user=odbserver
numprocs=8
redirect_stderr=true
stdout_logfile=/home/odbserver/opendatabio/storage/logs/supervisor.log
;--------------" > /etc/supervisor/conf.d/opendatabio-worker.conf

Permissões de arquivos e pastas

• As pastas storage e bootstrap/cache precisam ter permissão de escrita para o usuário do servidor (geralmente www-data). Use permissão de escrita para o grupo (0775) em vez de torná-las graváveis por todos.
• O arquivo de configuração .env precisa ter permissão 0640, pois contém credenciais.
• Este link mostra diferentes métodos de definir permissões para um aplicativo Laravel.

Este é o método recomendado:

cd /home/odbserver

# Permita acesso ao usuário odbserver e ao grupo do Apache.
sudo chown -R odbserver:www-data opendatabio
sudo find ./opendatabio -type f -exec chmod 644 {} \;
sudo find ./opendatabio -type d -exec chmod 755 {} \;

cd /home/odbserver/opendatabio
sudo chgrp -R www-data storage bootstrap/cache
sudo chmod -R ug+rwx storage bootstrap/cache
sudo find storage bootstrap/cache -type d -exec chmod g+s {} \;

# Ajuste as permissões da pasta de mídia.
sudo find ./storage/app/public/media  -type f -exec chmod 664 {} \;
sudo find ./storage/app/public/media  -type d -exec chmod 775 {} \;

# Proteja o arquivo de ambiente.
sudo chmod 640 ./.env

# Verifique se o Apache pode escrever nos diretórios do Laravel.
sudo -u www-data test -w storage
sudo -u www-data test -w bootstrap/cache

Instale o OpenDataBio

1. Muitas distribuições Linux, especialmente Ubuntu e Debian, têm arquivos php.ini diferentes para a interface de linha de comando e para o módulo Apache. Use a configuração do Apache ao executar o instalador, para que ele identifique corretamente extensões ou configurações ausentes.

   Por exemplo,

   export PHPRC=/etc/php/8.3/apache2/php.ini
   

2. O script de instalação baixará o gerenciador de dependências Composer e todas as bibliotecas PHP necessárias listadas no arquivo composer.json. No entanto, se o seu servidor estiver atrás de um proxy, você deve instalar e configurar o Composer independentemente. Implementamos a configuração do PROXY, mas não a estamos mais usando e não testamos corretamente (se você precisar de ajustes, coloque um issue no GitLab).

3. O script solicitará opções de configuração, que são armazenadas no arquivo de ambiente .env na pasta raiz do aplicativo.

   Você pode, opcionalmente, configurar este arquivo antes de executar o instalador:

   • Crie um arquivo .env executando cp .env.example .env
   • Leia os comentários nesse arquivo e ajuste conforme necessário
   • Garanta que ASSET_URL esteja correto para a URL/subcaminho da sua instalação
   • Defina se o Pl@ntNet usará PLANTNET_API_KEY compartilhada, chaves pessoais dos usuários ou ambas. A chave do servidor é opcional quando chaves pessoais estão habilitadas. Consulte a Configuração administrativa.

4. Execute o instalador, selecionando explicitamente o perfil Apache:

cd /home/odbserver/opendatabio
php install apache

O instalador compila o frontend Vite e publica os assets do Livewire depois de configurar o .env. Esses arquivos gerados não são mais versionados. Portanto, Node.js 22 e npm precisam estar instalados no servidor.

5. Dados iniciais — o script perguntará se você deseja instalar dados de Localidades e Táxons. Esses dados são específicos de cada versão. Consulte as notas de versão no repositório dos dados.

Valide a instalação concluída:

php artisan migrate:status
php artisan locales:audit
composer check-platform-reqs
sudo supervisorctl status
redis-cli ping
curl -I http://localhost/opendatabio/
curl -I http://localhost/opendatabio/build/manifest.json

Tradução assistida opcional

Nomes e descrições mantidos pelos usuários precisam conter seus campos essenciais no locale principal. Os outros locales de conteúdo habilitados são opcionais, e qualquer locale habilitado que possua texto pode ser usado como origem de uma tradução assistida. A tradução sempre é apresentada para revisão e nunca é salva automaticamente.

A tradução assistida fica desabilitada por padrão. Google Cloud Translation v3 é o único provedor atualmente suportado:

USER_TRANSLATION_PROVIDER=google
GOOGLE_CLOUD_PROJECT=id-do-projeto
GOOGLE_TRANSLATION_LOCATION=global
GOOGLE_APPLICATION_CREDENTIALS=/caminho-seguro/service-account.json

Habilite a Cloud Translation API e o billing, conceda à service account apenas a permissão de tradução necessária, mantenha o JSON fora do repositório e configure quotas/alertas de cobrança. Atualmente, o Google aplica um crédito mensal de uso gratuito aos primeiros 500.000 caracteres NMT; billing ainda é obrigatório e o uso além do crédito é cobrado. Confira os preços atuais antes de habilitar o recurso. Quando o servidor fornecer Application Default Credentials, GOOGLE_APPLICATION_CREDENTIALS pode ficar vazio.

Depois de editar o .env, valide sem enviar texto e então faça uma solicitação real:

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

O comando com --live envia ao provedor somente a frase curta mostrada pelo comando. Uma falha no provedor não impede o funcionamento do OpenDataBio; deixe USER_TRANSLATION_PROVIDER vazio para desabilitar o recurso.

Problemas de instalação

Existem inúmeras maneiras possíveis de instalar o aplicativo, mas podem envolver mais etapas e configurações.

• Se o navegador retornar 500|SERVER ERROR, consulte o último erro em storage/logs/laravel.log. Se encontrar ERROR: No application encryption key has been specified, execute:

php artisan key:generate
php artisan config:cache

• Se você receber o erro failed to open stream: Connection timed out durante a execução do instalador, isso indica uma configuração incorreta do seu roteamento IPv6. A correção mais fácil é desabilitar o roteamento IPv6 no servidor.
• Se você receber erros durante alimentação aleatória do banco de dados, você pode tentar remover o banco de dados inteiramente e reconstruí-lo. Claro, não execute isso em uma instalação de produção.

php artisan migrate:fresh

• Você pode substituir as tabelas Locations e Taxons usando o seed data depois de reconstruir a base:

php seedodb

Configurações pós-instalação

• Se os jobs de importação/exportação não forem processados, certifique-se de que o Supervisor esteja ativo com systemctl start supervisor && systemctl enable supervisor e verifique storage/logs/supervisor.log.
• Você pode alterar variáveis de configuração em .env e config/app.php, incluindo idioma, fuso horário e e-mail. Execute php artisan config:cache após atualizar a configuração.
• Para impedir que os rastreadores do mecanismo de pesquisa indexem seu banco de dados, adicione o seguinte ao seu “robots.txt” na pasta raiz do servidor (no Debian, /var/www/html):

User-agent: *
Disallow: /

Atualizando uma instalação Apache existente

Antes de atualizar, faça backup do banco de dados, do arquivo .env e de storage/app/public/media. Antes de rodar os comandos, revise diferencas de configuracao da versao alvo:

• Compare .env com .env.example (incluindo ASSET_URL)
• Confira configuracoes do PHP (php.ini em CLI e FPM/Apache)
• Confira configuracao dos workers no Supervisor

1. Coloque a aplicação em modo de manutenção:

cd /home/odbserver/opendatabio
php artisan down

2. Atualize o código-fonte para a versão desejada:

git fetch --tags
git checkout <tag-ou-branch-de-destino>

3. Atualize dependências e aplique migrações de banco:

composer install --no-dev --optimize-autoloader
php artisan migrate:status
php artisan migrate --force

4. Recompile os assets do frontend e do Livewire após mudanças no .env:

sh scripts/build-assets.sh

5. Recrie os caches e reinicie os workers de fila:

php artisan optimize:clear
php artisan config:cache
php artisan queue:restart
echo "" > storage/logs/laravel.log

6. Tire a aplicação do modo de manutenção:

php artisan up

Se a versão de destino incluir novas variáveis de ambiente, adicione-as ao .env antes de rodar assets/cache. Veja o conteúdo de .env.example para mudanças necessárias.

Armazenamento e backups

Você pode alterar as configurações de armazenamento em config/filesystem.php, onde pode definir o armazenamento baseado em nuvem, que pode ser necessário se muitos usuários enviarem arquivos de mídia, exigindo muito espaço em disco.

1. Downloads de dados são colocados em fila como Jobs e um arquivo é gravado em uma pasta temporária,sendo excluído quando o trabalho é excluído pelo usuário. Esta pasta é definida como download disk no arquivo de configuração filesystem.php, que aponta para storage/app/public/downloads. Apagar esses arquivos temporários depende dos usuários, portanto, um trabalho de limpeza do cron pode ser aconselhável para implementar em sua instalação;
2. Arquivos de mídia são armazenados por padrão no media disk, que coloca os arquivos na pasta storage/app/ public/media;
3. Para configuração regular crie ambos os diretórios storage/app/public/downloads e storage/app/public/media com permissões graváveis ​​pelo usuário do servidor
4. Lembre-se de incluir a pasta de mídia em um plano de backup;

3 - Instalação com Docker

A maneira mais fácil de instalar e executar o OpenDataBio é usar o Docker e os arquivos de configuração fornecidos, que incluem nginx, MySQL, Redis e Supervisor para os processos de fila.

Escolha um perfil

O OpenDataBio fornece dois perfis Compose:

1. docker-compose.yml: desenvolvimento e testes locais, com bind mounts do código-fonte, phpMyAdmin e portas 8081/8082.
2. docker-compose.prod.yml: produção, com imagens imutáveis da aplicação, sem bind mounts do código-fonte ou phpMyAdmin, usuário dedicado do banco, verificações de saúde e volumes nomeados.

O Makefile não pergunta qual perfil você deseja. O comando escolhido define o perfil:

• make docker-init inicia o perfil de desenvolvimento e usa .env;
• make init-prod inicia o perfil de produção e usa .env.production.

Para uma instalação de produção, ou para testar o perfil de produção junto de uma instalação Apache existente, use make init-prod.

Se iniciar make docker-init por engano, interrompa com Ctrl+C e pare somente o projeto Compose de desenvolvimento:

docker compose -p odb down

Não acrescente -v, pois essa opção exclui os volumes do projeto Docker selecionado.

Instalação de produção

1. Prepare o ambiente

cd opendatabio
cp .env.production.example .env.production
nano .env.production
chmod 600 .env.production

O Compose lê .env.production no host e injeta seus valores nos containers da aplicação. A imagem de produção intencionalmente não contém /var/www/html/.env; o Laravel lê as variáveis de ambiente injetadas.

No mínimo, substitua:

APP_URL=https://dados.exemplo.org
ASSET_URL=https://dados.exemplo.org
APP_FORCE_HTTPS=true
APP_HTTP_PORT=80

DB_DATABASE=opendatabio
DB_USERNAME=opendatabio
DB_PASSWORD=uma-senha-forte-da-aplicacao
DB_ROOT_PASSWORD=outra-senha-forte-para-root

Defina também se o Pl@ntNet usará uma chave do servidor compartilhada pela instalação, chaves pessoais cadastradas pelos usuários ou ambas. Uma PLANTNET_API_KEY vazia é válida quando PLANTNET_ALLOW_USER_KEYS=true; PLANTNET_SERVER_FALLBACK determina se usuários sem chave pessoal podem usar a chave do servidor. Consulte a Configuração administrativa antes de iniciar os containers.

Se o TLS terminar em um proxy reverso externo, mantenha os containers da aplicação em uma rede/porta HTTP privada e configure o proxy para encaminhar o host e o protocolo originais.

Para testar o perfil de produção localmente enquanto o Apache já usa a porta 80:

APP_URL=http://localhost:8083
ASSET_URL=http://localhost:8083
APP_FORCE_HTTPS=false
APP_HTTP_PORT=8083

2. Construa e inicialize

O script de inicialização:

1. gera APP_KEY somente quando estiver vazia;
2. compila o frontend uma vez e copia os mesmos assets gerados para as imagens autocontidas de PHP e nginx;
3. aguarda as verificações de saúde do MySQL e Redis;
4. executa as migrations;
5. configura os locales da interface e do conteúdo inserido pelos usuários;
6. cria os caches de configuração, rotas e views do Laravel;
7. inicia nginx e workers das filas;
8. executa a auditoria de locales.

make init-prod

Para inicializar um banco de produção novo e depois importar opcionalmente os dados de referência de localidades e táxons compatíveis com a versão:

make init-prod SEED=1

A etapa de seed é interativa e exige digitar PROCEED. Ela substitui as tabelas atuais de referência de localidades e táxons; use-a somente em uma instalação nova ou quando as notas específicas da atualização determinarem essa substituição. Para executá-la posteriormente em uma instalação de produção já inicializada:

make seed-prod

O seed de produção é executado inteiramente nos containers do projeto odb-prod e não lê, altera ou remove arquivos do storage/ local de uma instalação Apache.

A seleção padrão de locales é:

interface: en,es,pt-br
conteúdo inserido por usuários: pt-br

Para escolher outros locales durante a inicialização:

ODB_INTERFACE_LOCALES=en,es,pt-br \
ODB_CONTENT_LOCALES=pt-br,en \
make init-prod

ODB_CONTENT_LOCALES inicializa a seleção de locales de conteúdo. O locale principal sempre é habilitado e os campos traduzíveis essenciais continuam obrigatórios nele; traduções nos demais locales habilitados são opcionais.

A tradução assistida fica desabilitada por padrão. Para habilitar o único provedor atualmente suportado, configure Google Cloud Translation v3 antes de make init-prod. Atualmente, o Google aplica um crédito mensal de uso gratuito aos primeiros 500.000 caracteres NMT, mas billing é obrigatório e o excedente é cobrado. Configure quotas da API e alertas de cobrança e confira os preços atuais.

mkdir -p docker-secrets
cp /origem/segura/google-translation.json docker-secrets/
chmod 700 docker-secrets
chmod 600 docker-secrets/google-translation.json

USER_TRANSLATION_PROVIDER=google
GOOGLE_CLOUD_PROJECT=id-do-projeto
GOOGLE_TRANSLATION_LOCATION=global
GOOGLE_APPLICATION_CREDENTIALS=/run/secrets/google-translation.json

O diretório ignorado docker-secrets é montado como somente leitura em /run/secrets nos containers Laravel e de filas. Nunca inclua seus arquivos na imagem ou no repositório.

Teste o provedor selecionado:

docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml exec -T -u www-data laravel php artisan translations:check --source=en --target=es
docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml exec -T -u www-data laravel php artisan translations:check --source=en --target=es --live

Não gere novamente a APP_KEY depois que houver dados armazenados.

3. Valide a produção

docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml ps
docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml exec -T redis redis-cli ping
docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml exec -T -u www-data laravel php artisan migrate:status
docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml exec -T -u www-data laravel php artisan locales:audit
curl -I http://localhost:8083/

Examine os logs:

docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml logs --tail=200 nginx
docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml logs --tail=200 laravel
docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml logs --tail=200 supervisord
docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml logs --tail=200 mysql

Inicialmente, o CSP do nginx é enviado como Content-Security-Policy-Report-Only. Teste toda a interface e examine os relatórios do navegador antes de ativá-lo em docker/prod/nginx.conf.

Início rápido para desenvolvimento

Esta seção destina-se somente a um checkout de desenvolvimento. Não a siga no mesmo checkout que serve uma instalação Apache: o perfil de desenvolvimento usa .env, monta o código-fonte e pode escrever nos diretórios locais da aplicação.

Pré-requisitos:

1. Docker com o plugin Compose v2 (docker compose).
2. Linux/macOS: usuário com acesso ao socket do Docker ou instalação rootless.
3. Windows: Docker Desktop com WSL2/Hyper-V.
4. make para usar os comandos abreviados abaixo.
5. Node.js 22 e npm no host. O bind mount do código de desenvolvimento substitui a árvore da aplicação presente na imagem; por isso, make docker-init gera no checkout os assets não versionados do frontend e do Livewire.

Preserve primeiro qualquer arquivo de ambiente que não pertença ao Docker:

cp .env .env.backup.apache
cp .env.docker .env
make docker-init

Para um banco novo de desenvolvimento, importe os dados opcionais de referência de localidades e táxons depois da inicialização:

make seed-odb

Como alternativa, execute as duas etapas com make docker-init SEED=1. O seed substitui as tabelas atuais de localidades e táxons e solicita confirmação explícita.

A aplicação de desenvolvimento estará em http://localhost:8081 e o phpMyAdmin em http://localhost:8082.

Login padrão:

usuário: admin@example.org
senha: password1

Altere a senha depois da instalação.

O comando de inicialização destina-se a uma instalação nova. Ele não substitui uma APP_KEY existente, mas migrations e seeds ainda são alterações no banco de dados.

Comandos Make

Construção e banco de dados

1. make docker-init — copia .env.docker se .env não existir, constrói/inicia containers, instala dependências, gera uma chave ausente, executa migrations e cria o link do storage
2. make build — constrói os containers de desenvolvimento
3. make key-generate — gera a chave da aplicação somente se ainda não existir
4. make composer-install — instala as dependências PHP
5. make composer-update — atualiza as dependências PHP
6. make migrate — cria ou atualiza o banco de dados
7. make drop-migrate — exclui e recria o banco de dados
8. make seed-odb — popula o banco com localidades e táxons
9. make seed-prod — popula o banco Docker de produção sem tocar no storage do host
10. make init-prod — constrói e inicializa o perfil de produção
11. make start-prod / make stop-prod — inicia ou para o perfil de produção

Acesso aos containers

1. make start — inicia todos os containers de desenvolvimento
2. make stop — para todos os containers de desenvolvimento
3. make restart — reinicia os containers de desenvolvimento
4. make ssh — abre um shell no container Laravel
5. make ssh-mysql — abre um shell no container MySQL
6. make mysql — abre o console MySQL
7. make ssh-nginx — abre um shell no container nginx
8. make ssh-supervisord — abre um shell no container Supervisor

Manutenção

1. make optimize — limpa caches e arquivos de log
2. make info — mostra informações da aplicação
3. make logs — mostra os logs do Laravel
4. make logs-mysql — mostra os logs do MySQL
5. make logs-nginx — mostra os logs do nginx
6. make logs-supervisord — mostra os logs do Supervisor

Persistência de dados e reinicialização

MySQL, Redis e mídias de produção usam volumes nomeados. Reconstruir uma imagem não exclui esses volumes.

docker volume ls

Para reinicializar somente um projeto de desenvolvimento, incluindo seu banco:

docker compose -p odb down -v --remove-orphans

Para o perfil de produção:

docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml down -v --remove-orphans

Atualização de uma instalação Docker existente

Antes de atualizar, faça backup do banco e de storage/app/public/media.

Revise as diferenças de configuração da versão de destino:

• compare .env.production com .env.production.example, incluindo APP_URL e ASSET_URL;
• confira as configurações PHP em docker/prod/php.ini;
• confira a configuração do Supervisor em docker/general/supervisord.conf.

1. Atualize o código-fonte:

cd opendatabio
git fetch --tags
git checkout <tag-ou-branch>

2. Construa as novas imagens imutáveis:

make build-prod

3. Coloque a aplicação em manutenção e execute as migrations com a nova imagem:

docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml exec -T -u www-data laravel php artisan down
docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml up -d mysql redis laravel
docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml exec -T -u www-data laravel php artisan migrate --force

4. Atualize os caches e substitua os containers web e de workers:

docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml exec -T -u www-data laravel php artisan optimize
docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml up -d --force-recreate nginx supervisord

5. Retorne a aplicação ao serviço e valide:

docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml exec -T -u www-data laravel php artisan up
docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml exec -T -u www-data laravel php artisan locales:audit
docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml ps

As dependências do Composer e os assets do frontend são incorporados às imagens de produção. Não execute composer update ou npm run build interativamente nos containers de produção. Se a nova versão adicionar chaves a .env.production, configure-as antes de reconstruir ou recriar os containers.

4 - Instalação com Nginx

Estas instruções são para instalação com nginx. Se preferir Apache, use a página de instalação padrão (Apache).

Requisitos do servidor

1. Versão suportada do PHP >= 8.2 (8.3 recomendado).
2. Servidor web: nginx.
3. Banco SQL: MySQL ou MariaDB (testado com MySQL 8.0 e MariaDB 10.6+).
4. Extensões PHP necessárias: openssl, pdo, pdo_mysql, mbstring, tokenizer, xml, dom, gd, exif, bcmath, zip, curl, redis.
5. Redis para filas/cache.
6. Tectonic para geração de PDF de etiquetas.
7. Pandoc para renderização bibliográfica (recomendado).
8. Supervisor para jobs em segundo plano.

Prepare o servidor

O exemplo abaixo usa pacotes do Ubuntu/Debian e PHP 8.3. Instale nginx, PHP-FPM e os mesmos serviços e extensões exigidos pela instalação Apache:

sudo apt-get install software-properties-common
sudo add-apt-repository ppa:ondrej/php
sudo apt-get update
sudo apt-get install nginx mysql-server redis-server tectonic pandoc supervisor \
 php8.3-fpm php8.3-cli php8.3-intl php8.3-mysql php8.3-sqlite3 php8.3-gd \
 php8.3-mbstring php8.3-xml php8.3-bcmath php8.3-zip php8.3-curl php8.3-redis

sudo systemctl enable --now nginx php8.3-fpm redis-server supervisor

php -m | grep -E 'mbstring|xml|gd|mysql|redis|bcmath|pcntl|zip'
systemctl status php8.3-fpm --no-pager

Siga as seções de usuário dedicado, download, MySQL, Supervisor e permissões da instalação Apache. Para nginx, configure /etc/php/8.3/cli/php.ini e /etc/php/8.3/fpm/php.ini e reinicie php8.3-fpm.

Configuração do site no nginx

Crie o arquivo do site (exemplo):

sudo nano /etc/nginx/sites-available/opendatabio

Use este bloco base (ajuste domínio/caminhos):

server {
    listen 80;
    server_name seu-dominio.exemplo;

    root /home/odbserver/opendatabio/public;
    index index.php index.html;

    charset utf-8;
    client_max_body_size 100M;

    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_index index.php;
        include fastcgi.conf;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param PATH_INFO $fastcgi_path_info;
        fastcgi_read_timeout 300s;
        fastcgi_send_timeout 300s;
    }

    location ~ /\. {
        deny all;
    }
}

Ative e recarregue:

sudo ln -s /etc/nginx/sites-available/opendatabio /etc/nginx/sites-enabled/opendatabio
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx

Se o link simbólico já existir, não o recrie. Nunca recarregue o nginx antes de nginx -t terminar com sucesso.

HTTPS

O bloco da porta 80 é adequado para a validação inicial. Uma instalação pública de produção deve usar HTTPS. Configure um certificado diretamente no nginx, por exemplo com a integração Certbot da sua distribuição, ou termine o TLS em um proxy reverso confiável. Redirecione HTTP para HTTPS somente depois de testar o VirtualHost HTTPS.

Configure a URL pública de forma consistente:

APP_URL=https://seu-dominio.exemplo
ASSET_URL=https://seu-dominio.exemplo
APP_FORCE_HTTPS=true

Quando o TLS terminar em um proxy reverso, encaminhe os cabeçalhos originais Host e X-Forwarded-Proto e restrinja o acesso direto ao backend.

Content Security Policy (CSP)

No mesmo arquivo do site nginx, adicione no bloco server { ... }:

add_header Content-Security-Policy-Report-Only "default-src 'self'; base-uri 'self'; form-action 'self'; frame-ancestors 'self'; object-src 'none'; script-src 'self' 'unsafe-eval' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob: https://server.arcgisonline.com https://*.tile.openstreetmap.org; font-src 'self' data:; connect-src 'self'; media-src 'self' blob:; worker-src 'self' blob:;" always;

Depois recarregue:

sudo nginx -t
sudo systemctl reload nginx

Notas:

1. Comece com Report-Only e depois migre para enforcement após validar logs.
2. https://server.arcgisonline.com e https://*.tile.openstreetmap.org são necessários para os tiles do mapa.

URL da instalação

O bloco acima publica o OpenDataBio na raiz de um host dedicado. Use valores correspondentes no .env:

APP_URL=https://seu-dominio.exemplo
ASSET_URL=https://seu-dominio.exemplo

Depois recompile todos os assets gerados:

sh scripts/build-assets.sh
php artisan optimize:clear

Uma instalação nginx em subcaminho, como /opendatabio, também exige regras específicas de location, alias e FastCGI; alterar somente o .env não é suficiente. Prefira um host ou subdomínio dedicado. Se o subcaminho for obrigatório, use a configuração Apache testada ou prepare e teste uma configuração nginx específica antes de publicá-la.

Etapas compartilhadas da aplicação

Para evitar redundância, use as mesmas seções da instalação Apache (também válidas para implantação com nginx):

1. Configurações de PHP na Instalação padrão, usando o caminho FPM indicado acima
2. Configurar o supervisord em Instalação padrão
3. Permissões de arquivos e pastas em Instalação padrão
4. Instale o OpenDataBio conforme a Instalação padrão, mas execute php install nginx
5. Configurações pós-instalação em Instalação padrão

5 - Personalizar a instalação

Mudanças simples que podem ser implementadas no layout de um site OpenDataBio

Logo e imagem de fundo

Para substituir o logotipo da barra de navegação e a imagem da página inicial, apenas coloque seus arquivos de imagem substituindo os arquivos em /public/custom/ sem alterar seus nomes.

Textos e informações

Para alterar o texto de boas-vindas da página inicial, altere os valores para cada entrada nos arquivos:

• /lang/en/customs.php
• /lang/pt-br/customs.php
• /lang/es/customs.php
• Não remova as chaves de entrada. Defina como null para suprimir a exibição no rodapé e na página inicial.

Documentação Local

Você pode adicionar documentação em formato *.md para o repositório em arquivos nas seguintes pastas:

• /resources/docs/en/*
• /resources/docs/pt/*

Este espaço é reservado para administradores definirem documentação e diretivas personalizadas para os usuários de uma instalação específica do OpenDataBio. Por exemplo, este é um espaço para adicionar um código de conduta para os usuários, quem contatar para se tornar um usuário pleno,tutoriais específicos, etc.

NavBar e Rodapé

1. Se você deseja alterar a cor da barra de navegação superior e do rodapé, basta substituir a classe CSS do Bootstrap 5 nos templates correspondentes em /resources/views/layouts.
2. Você pode adicionar html adicional ao rodapé e barra de navegação, alterar o tamanho do logotipo, etc… como desejar.

6 - Atualizar OpenDataBio

Use esta página para a sequência comum de implantação. Antes de atualizar, leia o arquivo UPGRADES_NOTES.md da versão de destino do OpenDataBio. Ele é a fonte oficial para requisitos, permissões de armazenamento, migrações, preenchimentos e comandos de reparo específicos da versão; essas instruções não são repetidas aqui.

Antes de começar

1. Leia UPGRADES_NOTES.md e as notas da versão de destino. Anote todos os testes preliminares e comandos pós-migração antes de começar.
2. Faça backup de pelo menos:
   • Dump do banco de dados
   • .env
   • Toda a árvore storage/app, incluindo mídias, exportações geradas e os arquivos persistentes das versões de datasets
3. Compare as configurações atuais com os modelos/configurações da versão de destino:
   • .env com .env.example (incluindo ASSET_URL)
   • Configuração do Supervisor (/etc/supervisor/conf.d/opendatabio-worker.conf ou equivalente no contêiner)
   • Configuração do PHP (php.ini de CLI e FPM/Apache)
4. Planeje uma janela de manutenção para o ambiente de produção.

Atualização (instalação Apache ou nginx)

1. Coloque a aplicação em modo de manutenção:

cd /home/odbserver/opendatabio
php artisan down

2. Atualize o código-fonte:

git fetch --tags
git checkout <target-tag-or-branch>

3. Instale as dependências e execute as migrações:

composer install --no-dev --optimize-autoloader
php artisan migrate:status
php artisan migrate --force

4. Execute, na ordem documentada, os comandos pós-migração indicados no UPGRADES_NOTES.md da versão de destino. Alguns comandos enviam UserJobs em segundo plano; mantenha a aplicação em manutenção e acompanhe-os até o fim quando as notas assim exigirem.
5. Recompile os assets do frontend e do Livewire após mudanças no .env (obrigatório quando ASSET_URL mudar):

sh scripts/build-assets.sh

6. Limpe o cache e reinicie os workers:

php artisan optimize:clear
php artisan config:cache
php artisan queue:restart
systemctl restart supervisor.service
# Reinicie o servidor web e o PHP-FPM conforme a sua instalação.

7. Verifique a aplicação, os workers, os logs e as operações citadas nas notas de atualização; depois coloque a aplicação online novamente:

php artisan up

Atualização (instalação Docker)

Os comandos abaixo são para o perfil de produção (docker-compose.prod.yml e .env.production). Para o perfil de desenvolvimento com bind mounts, execute make docker-init somente quando desejar intencionalmente um ambiente de desenvolvimento.

1. Atualize o código-fonte e revise as configurações:

cd opendatabio
git fetch --tags
git checkout <target-tag-or-branch>

Compare .env.production com .env.production.example, sem substituir a chave da aplicação nem os segredos existentes.

2. Coloque a aplicação atual em manutenção e construa as novas imagens:

docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml exec -T -u www-data laravel php artisan down
make build-prod

3. Inicie o novo container da aplicação e execute as migrations:

docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml up -d mysql redis laravel
docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml exec -T -u www-data laravel php artisan migrate:status
docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml exec -T -u www-data laravel php artisan migrate --force

4. Execute dentro do contêiner da aplicação, na ordem documentada, os comandos pós-migração do UPGRADES_NOTES.md da versão de destino e acompanhe os UserJobs enviados por eles.
5. Atualize os caches e recrie nginx e os workers. As dependências do Composer e os assets do frontend já estão incluídos nas imagens de produção:

docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml exec -T -u www-data laravel php artisan optimize
docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml up -d --force-recreate nginx supervisord

6. Valide e retire a aplicação do modo de manutenção:

docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml exec -T -u www-data laravel php artisan locales:audit
docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml exec -T -u www-data laravel php artisan up
docker compose --env-file .env.production -p odb-prod -f docker-compose.prod.yml ps

Variáveis de ambiente

Para Apache/nginx, compare .env com .env.example. Para Docker de produção, compare .env.production com .env.production.example. Siga UPGRADES_NOTES.md para variáveis cujo valor ou significado mudou; confira APP_FORCE_HTTPS e ASSET_URL.

Estratégia de rollback

Se algo falhar depois das migrações:

1. Mantenha o modo de manutenção ativo.
2. Restaure o banco, o .env e o backup correspondente de storage/app. Os registros do banco e os arquivos das versões de datasets devem ser restaurados como um único snapshot.
3. Retorne para a tag estável anterior.
4. Reinstale as dependências/reconstrua os contêineres e valide os logs antes de php artisan up.

7 - 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.