Manual Mapas - Docker Compose

Execute o Mapas Culturais com Docker Compose em ambientes locais e em cenários próximos de produção.

Pré-requisitos

Docker com Docker Compose v2
Git

Setup padrão

git clone https://github.com/redemapas/mapas.git
cd mapas

docker compose up -d

O Docker Compose constrói a imagem da aplicação e inicia todos os serviços. O contêiner da aplicação espera o PostgreSQL passar no health check antes de iniciar.

As migrações do banco (db-updates.php) rodam automaticamente dentro do entrypoint do contêiner em toda inicialização. Não há etapa manual obrigatória.

Verifique a prontidão com:

docker compose logs -f mapas

O contêiner está pronto quando você vir a flag /mapas-ready ser criada.

Os serviços abaixo estarão rodando:

Serviço	URL	Credenciais
Aplicação	http://localhost:8080	—
MailPit (teste de e-mail)	http://localhost:8025	—
PostgreSQL	`localhost:5432`	usuário: `mapas`, senha: `mapas-dev`

Todo e-mail enviado pela aplicação é capturado pelo MailPit. Nada é entregue a endereços reais.

HTTPS local com Caddy

Recursos de PWA e notificações Web Push exigem HTTPS. O repositório inclui um compose.override.yml que adiciona um proxy reverso Caddy com TLS local automático.

O Docker Compose carrega compose.override.yml automaticamente junto com compose.yaml, então não é necessário passar flags extras:

docker compose up -d

O serviço Caddy encaminha as requisições para o contêiner da aplicação e emite um certificado localmente confiável usando sua CA interna.

Serviço	URL
Aplicação (HTTPS)	https://mapas.localhost:8443
Aplicação (HTTP)	http://mapas.localhost:8081

O hostname mapas.localhost resolve para 127.0.0.1 na maioria dos sistemas operacionais. Se isso não acontecer, adicione 127.0.0.1 mapas.localhost ao seu arquivo /etc/hosts.

Confie na CA do Caddy

Os navegadores vão exibir um aviso de segurança até que o certificado raiz do Caddy seja confiável pelo sistema operacional. Execute o comando abaixo depois que os serviços subirem:

docker compose exec caddy caddy trust

Reinicie o navegador depois de confiar na CA.

Gerenciamento de contêineres

O diretório dev/ reúne scripts auxiliares para operações comuns:

dev/bash.sh          # Abre um shell dentro do contêiner da aplicação PHP
dev/psql.sh          # Conecta ao PostgreSQL
dev/shell.sh         # Inicia um shell PHP interativo (psysh)
dev/pnpm.sh <cmd>    # Executa comandos pnpm dentro do contêiner

Build do frontend

A imagem de produção compila os assets do frontend durante o build. Em desenvolvimento, você pode recompilá-los sem reconstruir a imagem:

dev/pnpm.sh -C src install

dev/pnpm.sh -C src run build

dev/pnpm.sh -C src run watch

Restaurando um dump do banco

scripts/restore-dump.sh -db=mapas -u=mapas -f=dump.sql

O script se conecta ao contêiner PostgreSQL em execução e restaura o arquivo SQL informado.

Imagem de contêiner

A imagem de produção é publicada no GitHub Container Registry:

ghcr.io/redemapas/mapas

A imagem usa build em múltiplos estágios:

Stage Node.js: compila os assets de frontend com pnpm.
Stage Composer: instala as dependências PHP.
Stage de produção: PHP 8.4-FPM + Nginx sobre Alpine Linux.
Stage de desenvolvimento: estende a imagem de produção com Node.js, pnpm e pcov para testes.

O estágio de desenvolvimento é usado em compose.yaml (target: development). O estágio de produção é usado pelo Helm chart.

A senha padrão do PostgreSQL (mapas-dev) é propositalmente fraca e adequada apenas para desenvolvimento local. Nunca a use em produção.

Manual Rede das Artes

Docker Compose