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

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;