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 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

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

Copie a pasta themes/SampleTheme para themes/NovoTema;

meu-mapas/themes$ cp -a SamplesTheme NovoTema

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

    - ../themes/NovoTema:/var/www/src/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.

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.

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/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.

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.
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

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.

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.yml adicionando 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']
            ]
        ],
    ]
];

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

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Mapas Culturais Base Project

Estrutura de arquivos

Guia rápido para início de novo projeto

Criando repositório do projeto

Ambiente de desenvolvimento

Iniciando o ambiente de desenvolvimento

psysh

Parando o ambiente de desenvolvimento

Usuário super administrador da rede

Testando envio de emails

Configuração do Tema

Criando um novo tema

Adicionando um tema já existente ao projeto

Definindo o tema ativo

Configuração dos plugins

Criando um novo plugin

Adicionando um plugin já existente ao projeto

Ambiente de produção

1. Clonando o repositório no servidor

2. Gerando o certificado Let's Encrypt

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

4. Configurando o sistema

4. Subindo o ambiente

5. Atualizando o ambiente

Fixando uma versão

6. Backup

Files

README.md

Latest commit

History

README.md

File metadata and controls

Mapas Culturais Base Project

Estrutura de arquivos

Guia rápido para início de novo projeto

Criando repositório do projeto

Ambiente de desenvolvimento

Iniciando o ambiente de desenvolvimento

psysh

Parando o ambiente de desenvolvimento

Usuário super administrador da rede

Testando envio de emails

Configuração do Tema

Criando um novo tema

Adicionando um tema já existente ao projeto

Definindo o tema ativo

Configuração dos plugins

Criando um novo plugin

Adicionando um plugin já existente ao projeto

Ambiente de produção

1. Clonando o repositório no servidor

2. Gerando o certificado Let's Encrypt

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

4. Configurando o sistema

4. Subindo o ambiente

5. Atualizando o ambiente

Fixando uma versão

6. Backup