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ão5.6.14para5.6.15ou 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 de5.6para5.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ão6.0)
- .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
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.
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-mapasSubstitua 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-mapasDê 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 -> masterPara subir o ambiente de desenvolvimento basta entrar na pasta dev e rodar o script start.sh.
mapacultural/dev/$ sudo ./start.shacesse no seu navegador http://localhost/
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.
Para parar o ambiente de desenvolvimento usar as teclas Ctrl + C
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
O ambiente de desenvolvimento inclui o MailHog que pode ser acessado em http://localhost:8025.
Usaremos para exemplo o nome de tema NovoTema
- Copie a pasta
themes/SampleThemeparathemes/NovoTema;
meu-mapas/themes$ cp -a SamplesTheme NovoTema- Edite o arquivo
dev/docker-compose.ymladicionando uma linha na seção volumes para o tema:
- ../themes/NovoTema:/var/www/src/themes/NovoTema- Edite o arquivo
themes/NovoTema/Theme.phpe substitua o namespace (linha 2) porNovoTema:
<?php
namespace NovoTema;
- Implemente e estilize o tema. Há um pequeno tutorial de como desenvolver um novo tema, baseado no tema BaseV1, na documentação para desenvolvedores.
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.
- 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- Edite o arquivo
dev-scripts/docker-compose.ymladicionando uma linha na seção volumes para o tema:
- ../themes/SpCultura:/var/www/src/themes/SpCulturaEdite 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',Usaremos para exemplo o seguinte nome para o plugin: MeuPlugin.
- Copie a pasta
plugins/SamplePluginparaplugins/MeuPlugin;
meu-mapas/plugins$ cp -a SamplesTheme MeuPlugin- Edite o arquivo
plugins/MeuPlugin/Plugin.phpe substitua o namespace (linha 2) porMeuPlugin:
<?php
namespace MeuPlugin;-
Implemente a funcionalidade do plugin. Há um pequeno tutorial de como desenvolver plugins na documentação para desenvolvedores.
-
Para o ambiente de desenvolvimento, edite o arquivo
dev/docker-compose.ymladicionando uma linha na seção volumes para o plugin:
- ../plugins/MeuPlugin:/var/www/src/plugins/MeuPluginObs.: No ambiente de produção, esse mapeamento é feito atravéz do arquivo Dockerfile em docker/Dockerfile
- 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'] */],
]
];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.
- 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- Edite o arquivo
dev/docker-compose.ymladicionando uma linha na seção volumes para o tema:
- ../plugins/MetadataKeyword:/var/www/src/plugins/MetadataKeyword- 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']
]
],
]
];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.
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$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.shTendo 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.shIMPORTANTE: Antes de prosseguir para o próximo passo, certifique-se de que a pasta
docker-data/certs/confcontém os arquivos abaixo:
live/mapasculturais/fullchain.pemlive/mapasculturais/privkey.pemoptions-ssl-nginx.confssl-dhparams.pem
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/certbotIMPORTANTE: certifique-se de que a identação das linhas descomentadas está correta
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 .envIMPORTANTE: 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.
Para subir o ambiente basta executar o script start.sh.
meu-mapas$ sudo ./start.shO 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.shPara 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.6Deve ser feito backup ao menos diário de um dump do banco de dados, que pode ser obtido com o script dump.sh
meu-mapas$ sudo ./dump.sh > dump.sqle das pastas abaixo:
docker-data/public-filesdocker-data/private-filesdocker-data/saas-files
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent