hacklab/mapas-ufpel repository overview

⁠Mapa Cultural da UFPEL

Repositório do Mapa Cultural da UFPEL

É 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
• compose/ - arquivos de configuração e outros utilizados pelo docker-compose
  • common/ - arquivos de configuração comuns aos ambientes de desenvolvimento e produção
  • local/ - arquivos de configuração exclusivos do ambiente de desenvolvimento
  • production/ - arquivos de configuração exclusivos do ambiente de produção
• dev-scripts/ - scripts auxiliares para o desenvolvimento
  • start-dev.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
• 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
  • MapasUFPel - tema do Mapa Cultural da UFPEL

⁠Ambiente de desenvolvimento

⁠Iniciando o ambiente de desenvolvimento

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

⁠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

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

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

<?php
namespace NovoTema;

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

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

⁠Definindo o tema ativo

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

⁠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

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

<?php
namespace MeuPlugin;

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

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

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

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

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

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

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.

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

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

⁠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

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

⁠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