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:
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:
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;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
)2.0.0
) - quando houver quebra de compatibilidade (ex quando subir a versão do mapas para a versão 6.0
).env
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-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 git@github.com: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
Para subir o ambiente de desenvolvimento basta entrar na pasta dev-scripts
e rodar o script start-dev.sh
.
mapacultural/dev-scripts/$ sudo ./start-dev.sh
acesse 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.
Admin@local
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/SampleTheme
para themes/NovoTema
;
meu-mapas/themes$ cp -a SamplesTheme NovoTema
Edite o arquivo dev-scripts/docker-compose.yml
adicionando uma linha na seção volumes para o tema:
- ../themes/NovoTema:/var/www/html/protected/application/themes/NovoTema
Edite o arquivo themes/NovoTema/Theme.php
e substitua o namespace (linha 2) por NovoTema
:
<?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.yml
adicionando uma linha na seção volumes para o tema:
- ../themes/MetadataKeyword:/var/www/html/protected/application/themes/SpCultura
Edite o arquivo compose/common/0.main.php
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/SamplePlugin
para plugins/MeuPlugin
;
meu-mapas/plugins$ cp -a SamplesTheme MeuPlugin
Edite o arquivo plugins/MeuPlugin/Plugin.php
e substitua o namespace (linha 2) por MeuPlugin
:
<?php
namespace MeuPlugin;
Implemente a funcionalidade do plugin. Há um pequeno tutorial de como desenvolver plugins na documentação para desenvolvedores.
Edite o arquivo dev-scripts/docker-compose.yml
adicionando uma linha na seção volumes para o plugin:
- ../plugins/MeuPlugin:/var/www/html/protected/application/plugins/MeuPlugin
Adicione a configuração para habilitar o plugin dentro do array de configuração de plugins no arquivo compose/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
```sh
meu-mapas/plugins$ git submodule add https://github.com/mapasculturais/plugin-MetadataKeyword MetadataKeyword
Edite o arquivo dev-scripts/docker-compose.yml
adicionando uma linha na seção volumes para o tema:
- ../plugins/MetadataKeyword:/var/www/html/protected/application/plugins/MetadataKeyword
Adicione a configuração para habilitar o plugin dentro do array de configuração de plugins no arquivo compose/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](#4-configurando-o-sistema).
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`
```sh
$ 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.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
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
- ./compose/production/nginx.conf:/etc/nginx/conf.d/default.conf
##### versão com ssl
# - ./compose/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.
Para subir o ambiente basta executar o script start.sh
.
meu-mapas$ sudo ./start.sh
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
Para fixar uma versão do core do Mapas Culturais deve-se editar os arquivos Dockerfile de produção (compose/production/Dockerfile
) e desenvolvimento (compose/local/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:
compose/production/Dockerfile
:
FROM hacklab/mapasculturais:5.6
compose/local/Dockerfile
:
FROM hacklab/mapasculturais:5.6-cli
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
Deve 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.sql
e das pastas abaixo:
docker-data/public-files
docker-data/private-files
docker-data/saas-files