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

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

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

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

2. Construa e inicialize

O script de inicialização:

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

make init-prod

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

make init-prod SEED=1

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

make seed-prod

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

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

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

Para escolher outros locales durante a inicialização:

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

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

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

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

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

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

Teste o provedor selecionado:

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

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

3. Valide a produção

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

Examine os logs:

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

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

Início rápido para desenvolvimento

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

Pré-requisitos:

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

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

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

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

make seed-odb

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

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

Login padrão:

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

Altere a senha depois da instalação.

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

Comandos Make

Construção e banco de dados

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

Acesso aos containers

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

Manutenção

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

Persistência de dados e reinicialização

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

docker volume ls

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

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

Para o perfil de produção:

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

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

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

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

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

1. Atualize o código-fonte:

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

2. Construa as novas imagens imutáveis:

make build-prod

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

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

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

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

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

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

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