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

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.

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

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:

#EXEMPLO EM UBUNTU 22.04

#repositórios
apt-get install software-properties-common
add-apt-repository ppa:ondrej/php
add-apt-repository ppa:ondrej/php ppa:ondrej/apache2
add-apt-repository ppa:ondrej/php
add-apt-repository ppa:ondrej/apache2
apt update

#instala o php
apt install php8.3 -y
apt update
apt upgrade

#instala extensoes (modulos) do php
php --version
#quais os modulos instalados?
php -m

#se algum desses nao estive, instale
apt install php8.3-{bcmath,xml,mysql,zip,intl,gd,cli,curl,mbstring,sqlite3,redis}

#install apache
apt install libapache2-mod-php8.3
#instala redis e tectonic
apt install redis-server tectonic
#install pandoc
apt install pandoc
#install supervisor (needed for jobs)
apt-get install supervisor -y

a2enmod php8.3
phpenmod mbstring
phpenmod xml
phpenmod dom
phpenmod gd
a2enmod rewrite
a2ensite
systemctl restart apache2.service

#To check if they are installed:
php -m | grep -E 'mbstring|cli|xml|gd|mysql|redis|bcmath|pcntl|zip'
tectonic --version
redis-server --version

Adicione o seguinte à sua configuração do Apache.

• Mude /home/odbserver/opendatabio para o seu caminho (os arquivos devem estar acessíveis pelo apache)
• Você pode criar um novo arquivo na pasta sites-available: /etc/apache2/sites-available/opendatabio.conf e colocar o seguinte código nele.

<IfModule alias_module>
        Alias /opendatabio      /home/odbserver/opendatabio/public/
        Alias /fonts /home/odbserver/opendatabio/public/fonts
        Alias /images /home/odbserver/opendatabio/public/images
        Alias /build /home/odbserver/opendatabio/public/build
        Alias /vendor/livewire /home/odbserver/opendatabio/public/vendor/livewire
        <Directory "/home/odbserver/opendatabio/public">
                Require all granted
                AllowOverride All
        </Directory>
</IfModule>

Isso fará com que o Apache redirecione todas as solicitações de / para a pasta correta, e também permitirá que o arquivo .htaccess fornecido controle as regras de reescrita, de forma que os URLs sejam bonitos. Se desejar acessar o arquivo apontando o navegador para a raiz do servidor, adicione também a seguinte diretiva:

RedirectMatch ^/$ /

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:

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';
  style-src 'self' 'unsafe-inline';
  img-src 'self' data: https://server.arcgisonline.com https://*.tile.openstreetmap.org;
  font-src 'self' data:;
  connect-src 'self';
"

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 atualize os assets gerados e arquivos do Livewire:

php artisan livewire:publish --assets
php artisan optimize:clear
npm run build

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 seu arquivo php.ini. O instalador pode reclamar da falta de extensões do PHP, então lembre-se de ativá-las nos arquivos cli (/etc/php/8.3/cli/php.ini e web ini (/etc/php/8.3/fpm/php.ini) para PHP!

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

Habilite os módulos Apache ‘mod_rewrite’ e ‘mod_alias’ e reinicie o servidor:

sudo a2enmod rewrite
sudo a2ensite
sudo systemctl restart apache2.service

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


[mariadb]
max_allowed_packet=100M
innodb_log_file_size=300M  #no use for mysql

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, que é necessário para trabalhos. Crie um nome de arquivo opendatabio-worker.conf na pasta de configuração do Supervisor /etc/supervisor/ conf.d/opendatabio-worker.conf com o seguinte conteúdo, ajustando o caminho conforme a 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). Defina 0775 para esses diretórios.
• O arquivo de configuração .env precisa ter permissão 0640 pois contém senhas.
• Este link mostra diferentes métodos de definir permissões para um aplicativo Laravel.

Este é o método recomendado:

cd /home/odbserver

#note que odbserver e www-data podem mudar na sua configuracao

#defia as permissões tanto par ao seu usuário (aqui odbserver) como para o do apache (aqui www-data)
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

#pasta media ajustar
sudo find ./storage/app/public/media  -type f -exec chmod 664 {} \;
sudo find ./storage/app/public/media  -type d -exec chmod 775 {} \;

#arquivo de configuracao .env para permissao 640 
sudo chmod 640 ./.env

Instale OpenDataBio

1. Muitas distribuições Linux (Ubuntu e Debian) têm arquivos php.ini diferentes para a interface de linha de comando e para o Apache. Recomenda-se usar o arquivo de configuração do Apache ao executar o script de instalação, para que ele possa apontar corretamente as extensões ou configurações ausentes. Para fazer isso, encontre o caminho correto para o arquivo .ini e exporte-o **antes de usar o comando de instalação php install **.

   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 com o conteúdo do cp .env.example .env fornecido
   • Leia os comentários neste arquivo e ajuste de acordo
   • Garanta que ASSET_URL esteja correto para a URL/subcaminho da sua instalação

4. Execute o instalador:

cd /home/odbserver/opendatabio
php install

5. Compile os assets frontend depois de configurar o .env (obrigatorio quando ASSET_URL e adicionado ou alterado):

npm ci #talvez precise disso
npm run build

6. Seed data - o script irá pergunar se você quer instalar Localidades e Taxons distribuídos com aplicativo. Esses dados são específicos de cada versão do OpenDataBio. Ver as notas das versões no repositório desses dados.

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 , você deve olhar para o último error em storage/logs/laravel.log. Se você tiver ERROR: No application encryption key has been specified execute:

chave artesanal php: gerar
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 seus Jobs de importação/exportação não estão sendo processados, certifique-se de que o Supervisor esteja executando systemctl start supervisord && systemctl enable supervisord e verifique os arquivos de log em storage/logs/supervisor.log.
• Você pode alterar várias variáveis ​​de configuração para o aplicativo. O mais importante deles provavelmente está definido pelo instalador, mas há outras variáveis em .env e no arquivo config/app.php que você pode alterar. Em particular, você pode querer alterar as configurações de idioma, fuso horário e e-mail. Execute php artisan config: cache após atualizar os arquivos de 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: /

• As pastas storage e bootstrap/cache devem ser graváveis ​​pelo usuário do Apache (geralmente www-data). Veja este link para um exemplo de como fazer isso. Defina a permissão 0775 para esses diretórios.

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 assets_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 --force

4. Recompile os assets frontend apos mudancas no .env:

npm run build

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

php artisan optimize:clear
php artisan config:cache
php artisan queue:restart

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 é usando o Docker e os arquivos de configuração do docker fornecidos, que contêm todas as configurações necessárias para executar o ODB. Usa nginx e mysql e supervisor.

Perfil de produção

O OpenDataBio agora inclui um perfil Docker orientado a produção:

• docker/prod/nginx.conf
• docker/prod/php.ini
• docker/prod/www.conf
• docker-compose.prod.yml

Execute o compose de produção com:

docker compose -f docker-compose.prod.yml build
docker compose -f docker-compose.prod.yml up -d

Principais diferenças em relação ao dev:

1. Usa configurações nginx/php-fpm em docker/prod/*.
2. Remove bind-mounts do código-fonte da aplicação.
3. Desativa o phpMyAdmin por padrão (perfil dev-only).
4. Publica o nginx na porta 80 (ajuste se houver reverse proxy).

O CSP no nginx (report-only) está incluído em docker/prod/nginx.conf. Mantenha report-only primeiro e só depois aplique enforcement.

Arquivos Docker incluídos

laravel-app/
----docker/*
----.env.docker
----docker-compose.yml
----Dockerfile
----Makefile

Eles foram adaptados deste link, onde você também encontra uma configuração de produção.

Instalação

Pré-requisitos

1. Docker com plugin Compose (docker compose v2).
2. Linux/mac: usuário no grupo docker ou usar sudo.
3. Windows: Docker Desktop (WSL2/Hyper-V habilitados).

Início rápido (Linux/mac, requer make)

cd opendatabio
make docker-init          # copia .env.docker se faltar, sobe containers, instala composer, gera key, migra e faz storage:link
make seed-odb             # seed opcional para Locations/Taxons
#ou tudo junto
make docker-init SEED=1   # igual acima + seed opcional para Locations/Taxons

• Depois de configurar o .env (ou sempre que ASSET_URL mudar), recompile os assets:

npm run build

• App: http://localhost:8081 (usuário admin@example.org / password1)
• phpMyAdmin: http://localhost:8082

Windows (PowerShell)

cd opendatabio
powershell -ExecutionPolicy Bypass -File scripts/docker-init.ps1
# opcional seed
powershell -ExecutionPolicy Bypass -File scripts/docker-init.ps1 -Seed

Comandos manuais (se você não tiver make)

cp .env.docker .env
docker compose up -d
docker compose exec -T -u www-data laravel composer install --optimize-autoloader
docker compose exec -T -u www-data laravel php artisan key:generate --force
docker compose exec -T -u www-data laravel php artisan migrate --force
docker compose exec -T -u www-data laravel php artisan storage:link

Seed opcional sem make:

docker compose exec -T -u www-data laravel php getseeds
docker exec -i odb_mysql mysql -uroot -psecret odbdocker < storage/Location*.sql
docker exec -i odb_mysql mysql -uroot -psecret odbdocker < storage/Taxon*.sql
rm storage/Location*.sql storage/Taxon*.sql

Persistência de dados

Os contêineres criados pelo Docker podem ser excluídos e recriados sem perder os dados As tabelas MySQL são armazenadas em um volume; se ele for apagado, a base de dados será excluída.

docker volume list

Usando

O arquivo Makefile contém os seguintes comandos para interagir com os contêineres do docker e o odb.

Comandos para construir e criar o app

1. make docker-init - copia .env.docker (se faltar), constroi/sobe containers, instala composer, gera key, migra e faz storage:link
2. make build - construir os contêineres
3. make key-generate - gerar a chave do app e adicioná-la ao .env
4. make composer-install - instalar dependências php
5. make composer-update - atualizar dependências php
6. make composer-dump-autoload - executar o dump-autoload do composer dentro do contêiner
7. make migrate - criar ou atualizar o banco de dados
8. make drop-migrate - apaga a base de dados e migra novamente
9. make seed-odb - popular o banco de dados com localizações e táxons

Comandos para acessar os contêineres docker

1. make start - iniciar todos os contêineres
2. make stop - parar todos os contêineres
3. make restart - reiniciar todos os contêineres
4. make ssh - entrar no contêiner principal da aplicação laravel
5. make ssh-mysql - entrar no contêiner mysql, para que você possa acessar o log do banco de dados usando mysql -uUSER -pPWD
6. make mysql - entrar no console docker do mysql
7. make ssh-nginx - entrar no contêiner nginx
8. make ssh-supervisord - entrar no contêiner supervisord

Comandos de manutenção

1. make optimize - limpar caches e arquivos de log
2. make info - mostrar informações do app
3. make logs - mostrar logs do laravel
4. make logs-mysql - mostrar logs do mysql
5. make logs-nginx - mostrar logs do nginx
6. make logs-supervisord - mostrar logs do supervisord

Recriando os containers

Se você tiver problemas e alterou os arquivos do docker, pode ser necessário reconstruir:

#apaga todas as imagens sem apagr a base de dados
make stop #pare todas
docker system prune -a  #aceitar com Yes

#se quiser pagar os dados
docker volume list
docker volume rm VOLUME_ID

#construa novamente
make build
make start

Atualizando uma instalação Docker existente

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

• Compare .env com .env.example (incluindo assets_url)
• Confira configuracoes PHP do perfil alvo (docker/prod/php.ini ou seu arquivo customizado)
• Confira configuracao do Supervisor (docker/supervisord.conf ou equivalente no seu deploy)

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

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

2. Reconstrua e reinicie os contêineres:

make stop
make build
make start

3. Atualize dependências PHP e rode as migrações:

make composer-install
make migrate

4. Recompile os assets frontend apos mudancas no .env:

npm run build

5. Atualize os caches do Laravel e reinicie os workers de fila:

make optimize
docker compose exec -T -u www-data laravel php artisan queue:restart

Se a nova versão incluir mudanças no .env, adicione as novas chaves antes de rodar assets/cache/restart em produção.

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.

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

    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_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param PATH_INFO $fastcgi_path_info;
        fastcgi_read_timeout 300;
    }

    location ~ /\. {
        deny all;
    }
}

Ative e recarregue:

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

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';
  style-src 'self' 'unsafe-inline';
  img-src 'self' data: https://server.arcgisonline.com https://*.tile.openstreetmap.org;
  font-src 'self' data:;
  connect-src 'self';
" 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.

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 atualize os assets gerados e arquivos do Livewire:

php artisan livewire:publish --assets
php artisan optimize:clear
npm run build

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 (php.ini) em Instalação padrão
2. Configurar o supervisord em Instalação padrão
3. Permissões de arquivos e pastas em Instalação padrão
4. Instale OpenDataBio em Instalação padrão
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:

• /resources/lang/en/customs.php
• /resources/lang/pt-br/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 Boostrap 5 nas tags e arquivos correspondentes na pasta /resources/view/layout.
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 após mudanças no .env (obrigatório quando ASSET_URL mudar):

npm ci
npm run build

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)

1. Atualize o código-fonte:

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

2. Reconstrua e reinicie os contêineres:

make stop
make build
make start

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

make composer-install
make migrate

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. Recompile os assets do frontend após mudanças no .env (obrigatório quando ASSET_URL mudar):

npm run build

6. Limpe o cache e reinicie os workers:

make optimize
docker compose exec -T -u www-data laravel php artisan queue:restart

Variáveis de ambiente

Compare .env com o .env.example da versão de destino antes de compilar assets ou armazenar configurações em cache. Siga UPGRADES_NOTES.md para variáveis cujo valor ou significado mudou; em produção, 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.