Mapas Culturais Base Project

A ideia desse projeto é facilitar o deploy da plataforma Mapas Culturais e ser um repositório aglutinador das partes do sistema, viabilizando um alto controle das versões de cada uma das peças do sistema (plugins, tema, core do Mapas Culturais, PostgreSQL/PostGIS, redis etc).

É recomendado a utilização do Git Flow para a estrutura de branches e o Versionamento Semântico para as tags, da seguinte maneira:

• branch develop - para o desenvolvimento de novas funcionalidades e para teste local de novas funcionalidades;
• branch master - para o ambiente de homologaçào, podendo variar para branches específicos de alguma funcionalidade em desenvolvimento para um teste pontual;
• tags para o ambiente de produção (seguindo o Versionamento Semântico)

Seguindo a lógica do Versionamento Semântico, quando chegar o momento do lançamento da primeira versão em produção, deve ser criada a tag 1.0.0 e a partir daí seguir a seguinte lógica de versionamento:

• Nova versão PATCH (ex: 1.0.1) - quando uma nova configuração for feita, ou se algum bug for corrigido em alguma peça do sistema (ex subir a versão do mapas da versão 5.6.14 para 5.6.15 ou de algum plugin), atualização da versão do postgres, nginx ou redis etc;
• Nova versão MINOR (ex: 1.1.0) - quando uma nova funcionalidade for introduzida ao sistema, um novo plugin ou mudança da versão minor do mapas (ex subir a versão do mapas de 5.6 para 5.7)
• Nova versão MAJOR (ex: 2.0.0) - quando houver quebra de compatibilidade (ex quando subir a versão do mapas para a versão 6.0)

Estrutura de arquivos

• .env_sample - modelo para a criação do arquivo .env
• start.sh - inicializa o ambiente de produçao/homologação
• restart.sh - reinicializa o ambiente de produçao/homologação
• stop.sh - desliga o ambiente de produçao/homologação
• update.sh - atualiza o ambiente de produção
• logs.sh - exibe o output do docker-composer de produção, para visualização dos logs
• bash.sh - acessa o terminal do container do Mapas
• psql.sh - acessa o console psql do banco de dados
• init-letsencrypt.sh - script para auxiliar a criação e configuração do certificado Let's Encrypt
• docker-compose.yml - arquivo de configuração dos serviços utilizados para subir o ambiente de produção/homologação
• docker-compose-certbot.yml - arquivo de configuração dos serviços utilizados na geração do certificado Let's Encript
• docker/ - arquivos de configuração e outros utilizados pelo docker-compose
  • common/config.d/ - arquivos de configuração comuns aos ambientes de desenvolvimento e produção
  • db/ - arquivo com dump.sql padrão
  • production/ - arquivos de configuração exclusivos do ambiente de produção
• dev/ - scripts auxiliares para o desenvolvimento
  • start.sh - script que inicializa o ambiente de desenvolvimento
  • bash.sh - entra no container da aplicação
  • shell.sh - entra no shell do mapas culturais
  • psql.sh - entra no banco de dados da aplicação
  • docker-compose.local.yml - arquivo de definição do docker-compose utilizado pelos scripts acima
  • watch.sh - arquivo para compilar assets do thema atual
• plugins - pasta com os plugins desenvolvidos exclusivamente para o projeto
  • SamplePlugin - esqueleto de plugin para demostração e para servir de base para o desenvolvimento de outros plugins
• themes - pasta com os temas desenvolvidos exclusivaente para o projeto
  • SampleTheme - esqueleto de tema filho de Subsite para demostração e para servir de base para o desenvolvimento de outros temas

Guia rápido para início de novo projeto

Antes de tudo certifique-se de ter os pacotes git, docker e docker-compose instalados e estar utilizando sistema operacional Linux ou MacOS.

Nos exemplos é usado o comando sudo para que os scripts tenham os privilégios requeridos pelo docker.

Criando repositório do projeto

Crie um repositório vazio no github ou gitlab (usarei de exemplo o nome https://github.com/organizacao/meu-mapas)

Clone o repositório do projeto base no seu computador

$ git clone https://github.com/mapasculturais/mapasculturais-base-project.git meu-mapas
$ cd meu-mapas

Substitua a url do remote origin para a url de seu repositório

meu-mapas/$ git remote set-url origin https://github.com/organizacao/meu-mapas

# ou, se você tiver sua chave no github
meu-mapas/$ git remote set-url origin [email protected]:organizacao/meu-mapas

Dê git push no repositório para enviar a versão inicial para seu repositório vazio.

meu-mapas/$ git push
To github.com:organizacao/meu-mapas
 * [new branch]      master -> master

Ambiente de desenvolvimento

Iniciando o ambiente de desenvolvimento

Para subir o ambiente de desenvolvimento basta entrar na pasta dev e rodar o script start.sh.

mapacultural/dev/$ sudo ./start.sh

acesse no seu navegador http://localhost/

psysh

Este ambiente roda com o built-in web server do PHP, o que possibilita que seja utilizado o PsySH, um console interativo para debug e desenvolvimento.

no lugar desejado, adicione a linha eval(\psy\sh()); e você obterá um console. Ctrl + D para continuar a execução do código.

Parando o ambiente de desenvolvimento

Para parar o ambiente de desenvolvimento usar as teclas Ctrl + C

Usuário super administrador da rede

O banco de dados inicial inclui um usuário de role saasSuperAdmin de id 1 e email Admin@local. Este usuário possui permissão de criar, modificar e deletar qualquer objeto do banco.

• email: Admin@local
• senha: mapas123

Testando envio de emails

O ambiente de desenvolvimento inclui o MailHog que pode ser acessado em http://localhost:8025.

Configuração do Tema

Criando um novo tema

Usaremos para exemplo o nome de tema NovoTema

1. Copie a pasta themes/SampleTheme para themes/NovoTema;

meu-mapas/themes$ cp -a SamplesTheme NovoTema

2. Edite o arquivo dev/docker-compose.yml adicionando uma linha na seção volumes para o tema:

    - ../themes/NovoTema:/var/www/src/themes/NovoTema

3. Edite o arquivo themes/NovoTema/Theme.php e substitua o namespace (linha 2) por NovoTema:

<?php
namespace NovoTema;

4. Implemente e estilize o tema. Há um pequeno tutorial de como desenvolver um novo tema, baseado no tema BaseV1, na documentação para desenvolvedores.

Adicionando um tema já existente ao projeto

A melhor maneira de adicionar um tema já existente é colocando o repositório deste como submódulo do repositório do projeto. Utilizaremos como exemplo o tema do SpCultura, disponível no github.

1. Adicione o repositório do tema como submódulo do repositório do projeto

meu-mapas/themes git submodule add https://github.com/mapasculturais/theme-SpCultura SpCultura

2. Edite o arquivo dev-scripts/docker-compose.yml adicionando uma linha na seção volumes para o tema:

    - ../themes/SpCultura:/var/www/src/themes/SpCultura

Definindo o tema ativo

Edite o arquivo docker/common/0.main.php para o ambiente de produção e dev/0.main.php para o ambiente de desenvolvimento e defina o valor da chave themes.active.

    // Define o tema ativo no site principal. Deve ser informado o namespace do tema e neste deve existir uma classe Theme.
    'themes.active' => 'SpCultura',

Configuração dos plugins

Criando um novo plugin

Usaremos para exemplo o seguinte nome para o plugin: MeuPlugin.

1. Copie a pasta plugins/SamplePlugin para plugins/MeuPlugin;

meu-mapas/plugins$ cp -a SamplesTheme MeuPlugin

2. Edite o arquivo plugins/MeuPlugin/Plugin.php e substitua o namespace (linha 2) por MeuPlugin:

<?php
namespace MeuPlugin;

3. Implemente a funcionalidade do plugin. Há um pequeno tutorial de como desenvolver plugins na documentação para desenvolvedores.

4. Para o ambiente de desenvolvimento, edite o arquivo dev/docker-compose.yml adicionando uma linha na seção volumes para o plugin:

    - ../plugins/MeuPlugin:/var/www/src/plugins/MeuPlugin

Obs.: No ambiente de produção, esse mapeamento é feito atravéz do arquivo Dockerfile em docker/Dockerfile

5. Adicione a configuração para habilitar o plugin dentro do array de configuração de plugins no arquivo docker/common/plugins.php:

<?php

return [
    'plugins' => [
        // .....
        'MeuPlugin' => ['namespace' => 'MeuPlugin', /* 'config' => ['uma-configuracao' => 'valor-da-configuracao'] */],
    ]
];

Adicionando um plugin já existente ao projeto

A melhor maneira de adicionar um plugin já existente é colocando o repositório deste como submódulo do repositório do projeto. Utilizaremos como exemplo o plugin MetadataKeyword que serve para configurar metadados que devem ser incluídos na busca por palavra chave das entidades.

1. Adicione o repositório do plugin como submódulo do repositório do projeto

meu-mapas/plugins$ git submodule add https://github.com/mapasculturais/plugin-MetadataKeyword MetadataKeyword

2. Edite o arquivo dev/docker-compose.yml adicionando uma linha na seção volumes para o tema:

    - ../plugins/MetadataKeyword:/var/www/src/plugins/MetadataKeyword

3. Adicione a configuração para habilitar o plugin dentro do array de configuração de plugins no arquivo docker/common/plugins.php:

<?php

return [
    'plugins' => [
        // .....
        'MetadataKeyword' => [
            'namespace' => 'MetadataKeyword', 
            'config' => [
                'agent' => ['En_Municipio', 'En_Nome_Logradouro']
                'space' => ['En_Municipio', 'En_Nome_Logradouro']
            ]
        ],
    ]
];

Ambiente de produção

Antes de montar o ambiente deve-se saber se haverá um load balacer ou um reverse proxy na frente do servidor e se este será responsável por prover o certificado ssl. Caso positivo, pode-se pular as etapa de configuração do certificado Let's Encrypt, indo diretamente para o passo passo 4.

Todos os comandos abaixo são executados no servidor onde será instalada a plataforma.

1. Clonando o repositório no servidor

Para começar a instalação do ambiente no servidor o primeiro passo é clonar o repositório em alguma pasta do servidor. Uma sugestão é colocá-lo dentro da pasta /srv, ou /var/mapasculturais

$ cd /srv

/srv$ sudo clone https://github.com/organizacao/meu-mapas --recursive

/srv$ cd meu-mapas

meu-mapas$

2. Gerando o certificado Let's Encrypt

Para gerar o certificadao, você precisa editar o arquivo init-letsencrypt.sh preenchendo corretamente as linhas que definem as variáveis domain e email, informando o domínio que aponta para o servidor e preferencialmente um e-mail válido do responsável pelo domínio. Essa configuração deve ficar persistida no repositório, então commite essas modificações.

Após editar o arquivo, atualize o código do servidor e execute o script para testar se a configuração está correta e se o desafio do Let's Encrypt consegue ser executado corretamente.

IMPORTANTE: o domínio já deve apontar para o servidor e a porta 80 estar aberta para que o desafio do Let's Encript funcione corretamente.

meu-mapas$ git pull

meu-mapas$ sudo ./init-letsencrypt.sh

Tendo um resultado positivo do Let's Encrypt de que a configuração está correta, edite o arquivo init-letsencrypt.sh para definir o valor da variável staging=0 e execute o script novamente:

meu-mapas$ git pull

meu-mapas$ sudo ./init-letsencrypt.sh

IMPORTANTE: Antes de prosseguir para o próximo passo, certifique-se de que a pasta docker-data/certs/conf contém os arquivos abaixo:

• live/mapasculturais/fullchain.pem
• live/mapasculturais/privkey.pem
• options-ssl-nginx.conf
• ssl-dhparams.pem

3. Preparando o arquivo docker-compose para utilizar o certificado Let's Encrypt:

Para utilizar o certificado Let's Encrypt diretamente no servidor, primeiro deve-se editar o arquivo docker-compose.yml, comentar a linha do arquivo de configuração do nginx sem o ssl e descomentar as linha de configuração do nginx que icluem os certificados gerados pelo Let's Encrypt:

  ##### versão sem ssl
     - ./docker/production/nginx.conf:/etc/nginx/conf.d/default.conf

  ##### versão com ssl
    #  - ./docker/production/nginx-ssl.conf:/etc/nginx/conf.d/default.conf
    #  - ./docker-data/certs/conf:/etc/letsencrypt
    #  - ./docker-data/certs/www:/var/www/certbot

IMPORTANTE: certifique-se de que a identação das linhas descomentadas está correta

4. Configurando o sistema

Antes de subir o ambiente é preciso configurá-lo. Para isso crie no servidor um arquivo .env baseado no .env_sample e preencha-o corretamente.

# criando o arquivo
meu-mapas$ cp .env_sample .env

# editando o arquivo (utilize o seu editor preferido)
meu-mapas$ nano .env

IMPORTANTE: Não commitar este arquivo pois contém informações que não devem estar no controle de versão, como chaves e senhas, então este arquivo só deve existir no servidor.

4. Subindo o ambiente

Para subir o ambiente basta executar o script start.sh.

meu-mapas$ sudo ./start.sh

5. Atualizando o ambiente

O repositório vem configurado para utilizar sempre a última versão estável (latest) do Mapas Culturais e para atualizá-lo basta executar o script update.sh, que fará pull da imagem da última versão estável do core do Mapas Culturais (imagem hacklab/mapasculturais:latest), fazer o build da imagem do projeto e reiniciar o docker-compose.

meu-mapas$ sudo ./update.sh

Fixando uma versão

Para fixar uma versão do core do Mapas Culturais deve-se editar o arquivos Dockerfile em (docker/Dockerfile) e no script update.sh.

Por exemplo para fixar na versão 5.6, deixando atualizar somente versões PATCH dentro da MINOR 5.6, deve-se modificar a primeira linha dos arquivos Dockerfile como a seguir:

• docker/Dockerfile:

FROM hacklab/mapasculturais:5.6

Deve-se também modificar a linha do docker pull no script update.sh para que sempre que este seja executado a última versão PATCH dentro da versão MINOR 5.6 seja baixada antes do build:

docker pull hacklab/mapasculturais:5.6

6. Backup

O processo de backup tem como objetivo garantir a segurança e a recuperação dos dados da plataforma em caso de falhas, exclusões acidentais ou necessidade de auditoria. Ele consiste na geração diária de um dump completo do banco de dados PostgreSQL utilizado pelo sistema, o que assegura que todas as informações estruturadas (como usuários, inscrições, entidades e metadados) sejam salvas de forma compactada. Além disso, o processo mantém cópias organizadas por dia e por mês, permitindo o resgate de versões anteriores conforme necessário. Também são incluídos no backup os arquivos persistentes da aplicação, como uploads realizados por usuários e registros de log, assim como o arquivo .env que contém variáveis críticas de configuração do ambiente. Essa estratégia visa oferecer uma cópia consistente e completa da aplicação, facilitando a restauração em casos de desastre e assegurando a continuidade dos serviços.

📁 Local dos Scripts

Todos os scripts estão localizados no diretório onde o projeto foi clonado.

Exemplo comum:

/dados/mapasculturais/scripts/

⚠️ Importante: Esse caminho depende de onde você clonou o repositório em seu ambiente.
Altere conforme necessário. Exemplo alternativo:

/home/usuario/projetos/mapas/scripts/

---

📌 Objetivo dos Scripts e Como Usar

1. postgres-dump.sh

Realiza o dump diário do banco de dados (mapas) rodando em containers Docker que contenham postgres ou postgis no nome.

• Como usar:

  bash postgres-dump.sh /caminho/para/backups/

• Parâmetro:

  • $1: Caminho de destino onde os dumps compactados (HH.sql.gz) serão salvos.

• Comportamento:

  • Cria um subdiretório com o nome do container sanitizado.
  • Executa pg_dump dentro do container e salva como gzip.

---

2. backup-day.sh

Faz uma cópia diária do arquivo dump (00H.sql.gz) para o nome com o dia do mês, mantendo histórico diário.

• Como usar:

  bash backup-day.sh /caminho/para/backups/

• Parâmetro:

  • $1: Diretório onde estão os arquivos gerados pelo postgres-dump.sh.

• Comportamento:

  • Cria uma cópia como DD.sql.gz, com DD sendo o dia atual (ex: 11.sql.gz).

---

3. backup-mon.sh

Faz uma cópia mensal do dump (00H.sql.gz) para um arquivo com o ano e mês atual.

• Como usar:

  bash backup-mon.sh /caminho/para/backups/

• Parâmetro:

  • $1: Diretório onde estão os arquivos gerados pelo postgres-dump.sh.

• Comportamento:

  • Cria uma cópia como YYYY-MM.sql.gz (ex: 2025-06.sql.gz).

---

4. backup-files.sh

Faz backup dos arquivos persistentes da aplicação (private-files, public-files, logs) e do arquivo .env.

• Como usar:

  bash backup-files.sh /caminho/para/projeto /caminho/para/backups/

• Parâmetros:

  • $1: Caminho do diretório raiz do projeto (deve conter docker-data/ e .env)
  • $2: Diretório de destino dos arquivos de backup

• Comportamento:

  • Usa rsync para copiar as pastas:
    • docker-data/private-files
    • docker-data/public-files
    • docker-data/logs
  • Copia também o arquivo .env

---

🕑 Exemplo de Crontab

Edite a crontab com:

crontab -e

E adicione as linhas (ajuste os caminhos conforme seu ambiente):

# Dump do banco de dados diariamente à meia-noite
00 00 * * * bash /dados/mapasculturais/scripts/postgres-dump.sh /dados/backups/

# Backup diário com data do dia
00 01 * * * bash /dados/mapasculturais/scripts/backup-day.sh /dados/backups/

# Backup mensal com nome do mês
00 02 1 * * bash /dados/mapasculturais/scripts/backup-mon.sh /dados/backups/

# Backup dos arquivos da aplicação
00 03 * * * bash /dados/mapasculturais/scripts/backup-files.sh /dados/mapasculturais /dados/backups/

---

🛠 Requisitos para o backup

• Docker instalado e funcional
• Containers de banco devem conter postgres ou postgis no nome
• O banco de dados deve estar acessível via:
  • Usuário: mapas
  • Nome do banco: mapas
• Diretórios indicados nos parâmetros devem existir e ter permissões adequadas