Primeiros passos

• 1: Primeira vez?
• 2: Instalação padrão
• 3: Instalação com Docker
• 4: Personalizar a instalação

1 - Primeira vez?

OpenDataBio é um software para ser usado online. As instalações locais são para teste ou desenvolvimento, embora possam ser usadas para como ambiente local de produção de um único usuário.

Tipos de usuário

• Se você estiver instalando, o primeiro login para uma instalação do OpenDataBio deve ser feito com o usuário super-administrador padrão: admin@example.org e password1. Essas configurações devem ser alteradas, senão a instalação fica aberta à qualquer pessoa lendo essas instruções.
• Quando um usuário se auto-cadastra numa instalação do OpenDataBio, ele não tem permissão de edição ou inserção de dados no banco de dados, ele apenas ganha um cadastro e acesso aos conjuntos de dados que são abertos apenas para usuários registrados e permite que o usuário faça downloads pela interface, os quais exigem login.
• Apenas usuários completos podem contribuir com dados
• E apenas super-administradores podem atribuir o papel de usuário completo para usuários registrados - diferentes instalações do OpenDataBio podem ter políticas diferentes sobre como você pode obter acesso de usuário completo.

Ver mais em Usuários.

Prepare seu perfil de usuário-completo

1. Criar uma Pessoa com os seus dados e ligar ela ao seu perfil de usuário através das configurações. Assim, os formulários da interface utilizarão essa Pessoa como padrão, facilitando a entrada de dados.
2. Você precisará de pelo menos 1 conjunto de dados para entrar seus dados
   1. isso não é necessário para importar dados de biblitecas compartilhadas, como Pessoas, Localidades, Taxons e Referências Bibliográficas (saiba mais aqui).
   2. quando receber atribuição de usuário-completo, um Conjunto de Dados de acesso restrito e Projeto serão automaticamente criados para você com o nome de Workspace SEU-NOME. Você pode modificar as configurações desses objetos da forma que desejar.
3. Você poderá criar tantos projetos e conjuntos de dados que precisar. Entenda bem esses Objetos de Controle de Acesso do OpenDataBio.

Entrando dados

Existem três maneiras principais de importar dados para o OpenDataBio:

1. Um por um por meio da interface web, usando um navegador.
2. Usando os [serviços OpenDataBio de POST API] (/docs/api):
   1. importar de um arquivo CSV, XLXS ou ODS usando a interface (Menu Importar)
   2. através do R, usando OpenDataBio R package, que um cliente para essa API.
   3. criando o seu próprio cliente em outra linguagem
3. Ao usar os [serviços da API OpenDataBio] (/docs/api), você deve preparar seus dados ou arquivo para importação de acordo com as opções de campo do [verbo POST] (/docs/post-data) para o ’endpoint’ específico que você está tentando importar. Verifique também a referência rápida da API.

Dicas para inserir dados

1. Se for inserir dados pela primeira vez, recomendamos que você utilize a interface pelo seu navegador e crie pelo menos um registro para cada objeto que atenda às suas necessidades. Em seguida, experimente as configurações de privacidade do seu espaço de trabalho conjunto de dados e verifique se você pode acessar os dados quando estiver conectado ou não. Ou seja, entenda como os dados ficam organizados e veja como obtê-los.
2. Use Conjunto de dados para um conjunto independente de dados que deve ser distribuído como um grupo. Os conjuntos de dados são publicações dinâmicas, têm autor, dados e título.
3. Embora o ODB tente minimizar a redundância, dar flexibilidade aos usuários tem um custo em algumas definições, como por exemplo, Variáveis e [Pessoas](/docs/concepts/objetos auxiliares/#person) que podem receber registros duplicados. Portanto, deve-se ter cuidado ao criar tais registros. Os administradores podem criar um código de conduta para os usuários de uma instalação ODB para minimizar tal redundância.
4. Siga uma ordem de importação de novos dados, a partir das bibliotecas de uso comum. Por exemplo, você deve primeiro registrar Localidades, Taxons, Pessoas, Variáveis e qualquer outra biblioteca comum antes de importar Indivíduos ou Medições
5. OpenDataBio pode ser instalado com dados previamente organizados para Localidades do Brasil [unidades administrativas (Município, Estado, País), Unidades de Conservação federais e Terras Indígenas] e uma base da árvore da vida para Taxons complementada pela filogenia das plantas com sementes até o nível de Ordem conforme a árvore do Angiosperm Phylogeny WebSite, version 14.
6. Não há nenhuma necessidade de importar localidades do tipo POINT para importar Indivíduos porque o ODB cria a localidade para você se informar latitude e longitude, e detectará para você a qual são as localidades registradas à qual o indivíduo pertence. Ou seja, ODB detecta as unidades administrativas (Município, Estados, Pais), as Unidades de Conservação e Terras Indígenas e também classes ambientais, dependendo das Localidades registradas na base de dados. Você pode usar a API de localidades com o parâmetro querytype para validar previamente as coordenadas dos seus indivíduos.
7. Existem diferentes maneiras de criar localidades do tipo PARCELA e TRANSECTOS - saiba mais em Localidades.
8. A criação de taxons exige apenas a especificação de um nome - ODB pesquisará os serviços de nomenclatura para você, encontrará o nome, metadados e taxons pais ou taxons aceitos, se o seu nome for um sinônimo, e importará todos os eles, se necessário até encontrar na base algum taxon na hierarquia ancestral. Por exemplo, se informar Ocotea guianensis, mas apenas Laurales já está cadastrado na base, ODB irá buscar e cadastrar para você todo o caminho Lauraceae >> Ocotea >> Ocotea guianensis, com autoria, referencia bibliográfica e link ao repositório nomenclatural onde encontrou os dados. Se você estiver importando nomes publicados, basta informar este único atributo. Caso contrário, se o nome não for publicado, é necessário informar campos adicionais. Portanto, separe a importação em lote de nomes publicados e não publicados em dois conjuntos.
9. O campo notes de qualquer modelo é para texto simples ou para dados formatados como objectos JSON. A opção Json permite que você armazene dados estruturados personalizados em qualquer modelo que tenha o campo notes. Você pode, por exemplo, armazenar como notas alguns campos secundários de fontes originais ao importar dados, mas pode armazenar quaisquer dados adicionais que não sejam fornecidos pela estrutura do banco de dados do OpenDataBio. Esses dados não serão validados pelo OpenDataBio e a padronização de tags e valores depende de você. As notas Json serão importadas e exportadas como um texto JSON e serão apresentadas na interface como uma tabela formatada; URLs em seu Json serão apresentados como links.

2 - Instalação padrão

Estas instruções são para uma instalação baseada em apache, mas podem ser facilmente ajustadas para funcionar com nginx.

Requisitos do servidor

1. A versão mínima do PHP é 8.0
2. O servidor da web pode ser apache ou nginx. Para nginx, verifique a configuração nos arquivos do docker para ajustar essas instruções, que são para o apache.
3. Requer um banco de dados SQL, MySQL e MariaDB foram testados, mas também pode funcionar com Postgres. Testado com MYSQL.v8 e MariaDB.v15.1.
4. Extensões PHP necessárias ‘openssl’, ‘pdo’, ‘pdo_mysql’, ‘mbstring’, ’tokenizer’, ‘xlm’, ‘dom’, ‘gd’, ’exif’, ‘bcmath’
5. 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.
6. 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, 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.2 -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.2-{bcmath,xml,mysql,zip,intl,gd,cli,curl,mbstring,sqlite3}

#install apache
apt install libapache2-mod-php8.2
#install pandoc
apt install pandoc
#install supervisor (needed for jobs)
apt-get install supervisor -y

a2enmod php8.2
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|pandoc|supervisord|bcmath|pcntl|zip'

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
        <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 ^/$ /

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.0/cli/php.ini e web ini (/etc/php/8.0/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 = 4294967295  #this is needed for geometry (bug in mysql:8)


[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

#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.0/fpm/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

4. Execute o instalador:

cd /home/odbserver/opendatabio
php install

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

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.

Arquivos Docker incluídos

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

1. Certifique-se de ter Docker e Docker-compose instalados em seu sistema operacional.
2. Verifique se o seu usuário está no grupo docker criado durante a instalação do docker;
3. Baixe ou clone o OpenDataBio em sua máquina;
4. Certifique-se de que o seu usuário é o proprietário da pasta e do conteúdo criados, caso contrário, altere o proprietário e o grupo recursivamente para o seu usuário
5. Entre no diretório criado opendatabio
6. Opcionalmente, pode editar e ajustar o nome do arquivo contendo as configurações de ambiente .env.docker
7. Para instalar localmente para desenvolvimento, basta ajustar as seguintes variáveis ​​no arquivo Dockerfile, que são necessárias para mapear os proprietários dos arquivos para um usuário do docker;
   1. UID o usuário numérico que você está logado e que é o dono de todos os arquivos e diretórios no diretório opendatabio (em geral 1000 ou 1001).
   2. GDI o grupo numérico ao qual o usuário pertence, geralmente o mesmo que UID.
8. O arquivo Makefile contém atalhos para os comandos docker-compose usados ​​para construir os serviços configurados no docker-compose.yml e arquivos auxiliares na pasta docker.
9. Crie os contêineres do docker usando os atalhos (leia o Makefile para compreender os comandos)

make build

1. Inicie os serviços docker implementados

make start

1. Veja os contêineres e tente entrar no contêiner laravel

docker ps
make ssh #para entrar no container do app
make ssh-mysql #para entrar no container do mysql container onde você pode acessar a base de dados usando `mysql -uroot -p`

1. Instale as dependencias

make composer-install

1. Criar a base de dados usando Laravel Migration

make migrate

1. Você pode alimentar as tabelas Locations e Taxons usando o seed data para sua versão do OpenDataBio:

make seed-odb

1. Se funcionou, então Opendatabio estará disponível em seu navegador http::/localhost:8080.
2. O banco de dados estará disponível através do phpmyadmin em http://localhost:8082/
3. Faça login com o super-usuário admin@example.org e a senha password1
4. Configurações adicionais nesses arquivos são necessárias para um ambiente de produção e implantação;

Persistência de dados

As containers criados pelo Docker podem ser excluídos e regerados sem perder os dados As tabelas mysql são armazenadas em um volume, que se apagado irá excluir a base de dados completamente.

docker volume list

Usando

Leia o conteúdo do arquivo Makefile

make stop
make start
make restart
docker ps
...

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
docker system prune -a  #aceitar com Yes
make build
make start

4 - 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/customs.php
• Não remova as chaves de entrada. Defina como null para suprimir a exibição no rodapé e na página inicial.

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.