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
• 8: Backup e restauração

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.

Para mídias de 200 MiB e ZIPs de 1 GiB, configure o PHP do site:

upload_max_filesize = 1024M
post_max_size = 1100M
max_input_time = 1800

No VirtualHost da aplicação, acrescente:

LimitRequestBody 1153433600

php --ini identifica somente a configuração CLI. Confira também a configuração efetiva do Apache ou FPM. Mantenha allow_url_fopen=1; 512M é um ponto de partida para memory_limit, sujeito às dimensões das imagens e à concorrência. Após alterar PHP/Apache, valide com sudo apache2ctl configtest e reinicie o Apache; se usar FPM, recarregue também o serviço da versão correspondente. Veja Configuração administrativa para os limites .env, sua aplicação e verificação.

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;

Use o fluxo suportado de snapshot do banco e sincronização incremental descrito em Backup e restauração.

Scheduler e armazenamento privado de importações

Além dos workers do Supervisor, configure o scheduler no crontab do usuário da aplicação (no exemplo, odbserver), uma vez por minuto:

* * * * * cd /home/odbserver/opendatabio && php artisan schedule:run >> storage/logs/scheduler.log 2>&1

Ele recupera entregas pendentes da fila e limpa temporários expirados. Apache, workers e scheduler precisam ler, gravar e remover arquivos em storage/app/imports. Quando usam usuários diferentes, compartilhe o grupo:

cd /home/odbserver/opendatabio
sudo usermod -aG www-data odbserver
sudo mkdir -p storage/app/imports
sudo chgrp -R www-data storage/app/imports
sudo find storage/app/imports -type d -exec chmod 2770 {} +
sudo find storage/app/imports -type f -exec chmod 0660 {} +

Adapte usuário e grupo ao servidor. Reinicie os processos dos workers após mudar os grupos do usuário; queue:restart sozinho pode não atualizar os grupos herdados de um Supervisor já em execução. Verifique o acesso efetivo de ambos os usuários. O bit setgid (2) preserva o grupo nas novas pastas; o disco privado da aplicação usa permissões de grupo para arquivos novos. Mantenha essa pasta fora de public, sem alias HTTP ou link público, e não aplique 777.

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, siga Backup e restauração para proteger banco, mídias e versões persistentes de datasets. Em novas instalações de produção, essa página também explica como ODB_STORAGE_SOURCE expõe o storage como bind mount do host para rsync incremental eficiente.

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 scheduler

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.

Importações de mídia: limites, volumes e scheduler

Os perfis incluem scheduler, que executa php artisan schedule:work. Mantenha-o ativo junto aos workers para recuperação de entregas e limpeza de temporários. Em produção, o volume privado odbimports é montado em /var/www/html/storage/app/imports na aplicação, workers e scheduler; não é exposto pelo Nginx. No desenvolvimento, o bind mount do projeto compartilha esse caminho. Preserve esse armazenamento durante reinícios para permitir retomadas. Em instalações distribuídas, todos esses processos precisam enxergar os mesmos arquivos e usar o mesmo Redis para locks.

Consulte Configuração administrativa para as variáveis e limites. PHP e Nginx são incorporados às imagens: alterar docker/prod/php.ini, docker/dev/php.ini ou a configuração Nginx exige reconstruir as imagens afetadas e recriar os containers. Um simples restart não incorpora mudanças de imagem nem de variáveis de ambiente do Compose. Após editar o arquivo de ambiente ativo, recrie os serviços da aplicação, workers e scheduler e reconstrua o cache Laravel no ambiente atualizado. Inclua Nginx na recriação quando sua imagem/configuração mudar. Não remova os volumes para aplicar configurações. Se houver proxy externo, ajuste também seu limite de upload e a confiança nos proxies, como explicado no guia Nginx.

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 1100M;

    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

Limites de importação e proxies

O limite de 1100 MiB acima acompanha o ZIP de 1 GiB. Configure também PHP-FPM e .env conforme Configuração administrativa. Use o scheduler e as permissões privadas descritos na instalação padrão. Valide com sudo nginx -t, recarregue Nginx e o PHP-FPM correspondente após alterar suas configurações.

TrustProxies::$proxies = null é adequado quando o protocolo e host originais chegam corretamente ao PHP. Se um proxy externo termina HTTPS e encaminha HTTP, configure os IPs/redes dos proxies confiáveis e seus cabeçalhos encaminhados; caso contrário, URLs e uploads assinados podem falhar. Não use "*" apenas para habilitar importações. APP_URL não substitui a configuração de proxies.

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 Siga Backup e restauração para gerar e verificar o dump e a cópia incremental do storage.
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.

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.

8 - Backup e restauração

Um backup do OpenDataBio tem duas partes: o dump lógico do banco e os arquivos persistentes referenciados por ele. As ferramentas fornecidas propositalmente não compactam nem duplicam o storage de mídias no servidor da aplicação. Elas criam snapshots pequenos e verificados do banco e permitem que uma estação do administrador, NAS ou servidor de backup baixe os arquivos atuais por rsync incremental.

Manter somente dumps do banco no servidor da aplicação é uma proteção mínima, não uma recuperação de desastre. Se o servidor ou disco for perdido, o storage original também será perdido. Sempre que possível, baixe ou envie regularmente uma segunda cópia para outra máquina.

O que deve ser protegido

Guarde em conjunto:

1. o banco MySQL/MariaDB;
2. storage/app/public/media;
3. storage/app/public/datasets, incluindo versões publicadas de datasets;
4. arquivos de ambiente e secrets de produção em local seguro separado;
5. especialmente APP_KEY, necessária para descriptografar valores armazenados pela aplicação, como chaves pessoais do Pl@ntNet.

Redis, caches, sessões, logs, vendor, node_modules e downloads regeneráveis não fazem parte do backup durável.

Ferramentas incluídas

O repositório fornece:

scripts/backup/
├── backup-opendatabio.sh
├── backup.env.example
├── pull-opendatabio-backup.sh
├── pull.env.example
├── verify-opendatabio-backup.sh
└── systemd/

backup-opendatabio.sh roda no servidor da aplicação. Ele cria e verifica o dump comprimido, grava checksums e manifesto, marca o snapshot como COMPLETE e atualiza LATEST atomicamente. Nunca copia ou apaga o storage.

pull-opendatabio-backup.sh roda em outra máquina. Ele baixa o último snapshot completo do banco e sincroniza media e datasets diretamente dos diretórios originais.

Configurar o servidor da aplicação

Crie uma configuração pertencente ao root:

sudo install -d -m 700 /etc/opendatabio /var/backups/opendatabio
sudo cp scripts/backup/backup.env.example /etc/opendatabio/backup.env
sudo chmod 600 /etc/opendatabio/backup.env
sudo editor /etc/opendatabio/backup.env

Informe os caminhos reais do checkout e do backup. O destino deve ser absoluto e diferente de /.

Produção com Docker

Use:

ODB_DEPLOYMENT=docker
ODB_INSTALL_ROOT=/opt/opendatabio
ODB_ENV_FILE=/opt/opendatabio/.env.production
ODB_COMPOSE_FILE=/opt/opendatabio/docker-compose.prod.yml
ODB_COMPOSE_PROJECT=odb-prod
ODB_BACKUP_ROOT=/var/backups/opendatabio
ODB_BACKUP_GROUP=
ODB_STORAGE_PATH=/srv/opendatabio/storage

Por padrão, o Docker usa o volume nomeado odbstorage. Um cliente rsync remoto não consegue acessar com segurança os arquivos dentro desse volume privado. Em uma nova produção que usará backup pull, prepare um diretório no host:

sudo install -d -m 755 /srv/opendatabio/storage

Antes da primeira inicialização, defina no .env.production:

ODB_STORAGE_SOURCE=/srv/opendatabio/storage

Os serviços Compose montam o diretório no local normal da aplicação, e o entrypoint do container aplica o proprietário www-data configurado na imagem. Não fixe UID/GID no host, pois os parâmetros de build podem alterá-los. Instalações existentes que usam volume nomeado devem copiar seu conteúdo para o bind mount durante uma manutenção planejada antes de alterar ODB_STORAGE_SOURCE. Não troque apenas a variável, pois os arquivos parecerão ausentes.

Instalação nativa com Apache/nginx

Use:

ODB_DEPLOYMENT=native
ODB_INSTALL_ROOT=/var/www/opendatabio
ODB_BACKUP_ROOT=/var/backups/opendatabio
ODB_DB_NAME=opendatabio
ODB_DB_DEFAULTS_FILE=/root/.opendatabio-backup.cnf
ODB_BACKUP_GROUP=
ODB_STORAGE_PATH=/var/www/opendatabio/storage/app/public

Armazene as credenciais fora do script:

[client]
host=localhost
port=3306
user=opendatabio_backup
password=SUBSTITUA_POR_SENHA_PRIVADA

sudo chmod 600 /root/.opendatabio-backup.cnf

O usuário precisa de leitura suficiente para exportar tabelas e triggers. A senha não é passada como argumento de comando no host.

Executar e verificar

Teste manualmente antes de agendar:

sudo /opt/opendatabio/scripts/backup/backup-opendatabio.sh \
  /etc/opendatabio/backup.env

Resultado:

/var/backups/opendatabio/
├── LATEST
└── snapshots/20260813T021700Z/
    ├── database.sql.gz
    ├── SHA256SUMS
    ├── manifest.env
    └── COMPLETE

Verifique independentemente:

sudo scripts/backup/verify-opendatabio-backup.sh \
  /var/backups/opendatabio/snapshots/20260813T021700Z

Somente diretórios com COMPLETE entram na retenção automática. O padrão mantém sete dias de dumps. Ajuste ODB_RETENTION_DAYS conforme necessário.

Agendar no servidor

Timer do systemd (recomendado)

sudo cp scripts/backup/systemd/opendatabio-backup.service.example \
  /etc/systemd/system/opendatabio-backup.service
sudo cp scripts/backup/systemd/opendatabio-backup.timer.example \
  /etc/systemd/system/opendatabio-backup.timer
sudo systemctl daemon-reload
sudo systemctl enable --now opendatabio-backup.timer
sudo systemctl list-timers opendatabio-backup.timer

Consulte execuções:

sudo systemctl status opendatabio-backup.service
sudo journalctl -u opendatabio-backup.service

Persistent=true executa um backup perdido após o servidor voltar.

Alternativa com cron

Edite com sudo crontab -e:

17 2 * * * /opt/opendatabio/scripts/backup/backup-opendatabio.sh /etc/opendatabio/backup.env >> /var/log/opendatabio-backup.log 2>&1

Liste agendamentos:

sudo crontab -l
sudo ls -la /etc/cron.d /etc/cron.daily
sudo systemctl list-timers --all

O script usa flock; execuções sobrepostas falham com segurança.

Baixar para uma máquina do administrador

Instale openssh-client e rsync na estação, NAS ou servidor receptor. Use um usuário SSH que possa apenas ler os diretórios de backup e storage. Prefira chave SSH dedicada e valide a chave de host do servidor.

No servidor da aplicação, crie o grupo configurado e adicione o usuário SSH:

sudo groupadd --system opendatabio-backup
sudo usermod -aG opendatabio-backup backup-reader

Depois defina ODB_BACKUP_GROUP=opendatabio-backup em backup.env e gere um novo backup para aplicar as permissões de grupo ao snapshot concluído.

backup-opendatabio.sh dá ao grupo acesso de leitura apenas aos snapshots concluídos e a LATEST. Separadamente, permita leitura e travessia de media e datasets com grupo ou ACL apropriado; não torne configurações privadas legíveis para todos.

sudo install -d -m 700 /etc/opendatabio /srv/backups/opendatabio
sudo cp scripts/backup/pull.env.example /etc/opendatabio/pull-backup.env
sudo chmod 600 /etc/opendatabio/pull-backup.env
sudo editor /etc/opendatabio/pull-backup.env

Valores principais:

ODB_REMOTE_HOST=backup-reader@example.org
ODB_REMOTE_BACKUP_ROOT=/var/backups/opendatabio
ODB_REMOTE_STORAGE_ROOT=/srv/opendatabio/storage
ODB_LOCAL_ROOT=/srv/backups/opendatabio
ODB_SSH_IDENTITY=/home/admin/.ssh/opendatabio-backup
ODB_STORAGE_POLICY=archive

Teste:

scripts/backup/pull-opendatabio-backup.sh \
  /etc/opendatabio/pull-backup.env

O cliente lê LATEST no servidor em vez de adivinhar uma pasta pela data local. Ele reutiliza uma conexão SSH, valida checksum e gzip e executa rsync incremental diretamente no storage original. Não usa compressão, pois imagens e muitos arquivos de datasets já estão comprimidos.

Políticas:

• archive (padrão) nunca apaga localmente um arquivo ausente no servidor;
• mirror iguala a cópia atual, mas move removidos ou substituídos para history/SNAPSHOT/ em vez de descartá-los.

Não adicione --delete simples sem snapshot ou diretório de preservação. Uma exclusão acidental na aplicação seria propagada ao backup.

Os exemplos opendatabio-backup-pull.service.example e opendatabio-backup-pull.timer.example podem ser instalados e ajustados na máquina receptora. Persistent=true é adequado a uma estação nem sempre ligada. Cron é aceitável em uma máquina continuamente ativa.

Restaurar

Teste periodicamente em uma instalação isolada:

1. valide COMPLETE, SHA256SUMS e gzip -t;
2. use a versão registrada em manifest.env;
3. coloque o destino em manutenção e pare workers;
4. crie backup preventivo do destino;
5. recrie a base e importe database.sql.gz;
6. restaure media e datasets em storage/app/public;
7. restaure a APP_KEY correspondente e secrets necessários;
8. corrija proprietário e permissões;
9. execute php artisan migrate --force, php artisan optimize e php artisan locales:audit;
10. verifique logs, login, contagens, mídias, versões de datasets e um job pequeno antes de reabrir o acesso.

Em migração MariaDB para MySQL, versões recentes do mariadb-dump podem incluir uma diretiva inicial de sandbox incompatível com o MySQL da Oracle. Remova apenas essa diretiva exata; nunca elimine cegamente a primeira linha do SQL.

Verificações operacionais

Monitore:

• idade e tamanho de LATEST;
• código de saída e logs do backup no servidor;
• state/last-success no destino do pull;
• espaço livre em ambas as máquinas;
• verificação periódica de checksums;
• restauração real de teste ao menos trimestralmente.

Um backup só está comprovado quando uma restauração funciona.