Skip to main content

Quickstart Dev

A configuração do Quick Start está sendo atualizada. Será necessário fazer algumas alterações manuais nas aplicações por enquanto.

Sinta-se à vontade para modificar ou sugerir qualquer melhoria ou correção tanto no ‘start’ dos projetos quanto na documentação.

Sistema operacional​

Qualquer sistema operacional pode ser utilizado para seguir esse manual, no entanto, é altamente recomendado, por motivos de compatibilidade nativa e maior produtividade, o uso de um SO GNU/Linux. Para isso, sugerimos a utilização do Ubuntu 24.10 LTS .

Os detalhes da instalação, particionamento de disco e instalação de pacotes de terceiros ficam por sua conta. Geralmente a instalação básica já vai atender perfeitamente.

Caso decida por optar instalar o Debian, são necessários alguns passos pós-instalação:

  • Instalar o sudo e adicionar seu usuário ao grupo: Siga este tutorial
  • Remover o apache, caso venha instalado:

sudo apt remove --purge apache2

Configurações do sistema​

Se tiver dificuldade para fazer os contêineres se comunicarem, verifique se há algo bloqueando a conexão, como o firewall UFW.

https://www.javatpoint.com/ubuntu-disable-firewall

sudo UFW disable
  • DNS
    • Será necessária a configuração de nomes locais para que as aplicações consigam comunicar-se entre si;
    • Em sistemas GNU/Linux, o arquivo de configuração de DNS é o /etc/hosts;
    • Isso fará com que o DNS *.local seja apontado para o localhost;
    • Neste arquivo, adicione as seguintes linhas:
127.0.0.1 www.freterapido.local freterapido.local
127.0.0.1 dev.freterapido.local
127.0.0.1 dash.freterapido.local
127.0.0.1 edi.freterapido.local
127.0.0.1 login.freterapido.local
127.0.0.1 email.freterapido.local
127.0.0.1 ondeestameupedido.local
127.0.0.1 www.ondeestameupedido.local
127.0.0.1 api.freterapido.local       # Rota de APIs
127.0.0.1 login.shippon.local         # Acesso ao Keycloak
127.0.0.1 kong.freterapido.local      # Acesso ao Kong

Shell Scripts​

Adicione as seguintes linhas em seu arquivo ~/.profile, ~/.bashrc ou ~/.zshrc para adicionar as variáveis de ambiente (é necessário fazer logoff para que as informações sejam carregadas):

export GOPRIVATE="github.com/freterapido"
export GOPATH=$HOME/go
export PATH=$PATH:$HOME/.docker-bin
export PATH=$PATH:$GOPATH/bin
export PATH=$PATH:/usr/local/go/bin
export PATH=$PATH:$HOME/bin
export PATH=$PATH:./client/node_modules/.bin
export PATH=$PATH:./node_modules/.bin
export PATH=$PATH:$HOME/projetos/grpc/bins/opt
  • Protoc
# protoc 3.6.1
export PROTOC=$HOME/.protoc
export PATH=$PATH:$PROTOC/bin
  • Como serão utilizados serviços executados via Docker, tenha em mente que poderá haver conflitos em serviços como serviços HTTP, bancos de dados entre outros.
  • Remova quaisquer instalações existentes:
    • Apache;
    • PHP;
    • Composer;
    • NodeJS;
    • NPM;
    • Yarn;
    • MariaDB/MySQL;
    • Redis;
    • MongoDB;

Programas e utilitários​

  • Editor de texto/IDE

    • Pode ser utilizado o editor de sua preferência, mas sugerimos a utilização do Visual Studio Code
    • Extensões recomendadas (Caso tenha alguma sugestão, fique à vontade em adicioná-la):
      • aaron-bond.better-comments
      • alefragnani.numbered-bookmarks
      • brunobastosg.gerador-cpf-cnpj
      • donjayamanne.githistory
      • EditorConfig.EditorConfig
      • felixfbecker.php-debug
      • golang.go
      • humao.rest-client
      • ms-azuretools.vscode-docker
      • vscode-icons-team.vscode-icons
      • zxh404.vscode-proto3
      • bmewburn.vscode-intelephense-client
      • xyz.local-history (Cria um histórico local de alterações para cada arquivo. Obs: lembrar de adicionar a pasta .history no .gitignore, caso ainda não esteja lá)

  • Git

    • Instale usando o comando $ sudo apt install git
    • Após instalado, configurar o nome de usuário e email, conforme descrito aqui;
    • Adicione as seguintes linhas ao arquivo ~/.gitconfig, abaixo da seção de dados do usuário:
    [url "git@github.com:"]
        insteadOf = https://github.com/
    [url "git@github.com:"]
        insteadOf = https://github.com/

  • Posteriormente, será necessário criar e adicionar suas chaves SSH, quando for necessário, siga os passos descritos aqui;

  • Git Flow

    • Instale usando o gerenciador de pacotes $ sudo apt install git-flow;
    • Após instalado, configure-o através dos seguintes comandos:
      • git config --global gitflow.branch.master master
      • git config --global gitflow.prefix.feature feature/
      • git config --global gitflow.prefix.bugfix bugfix/
      • git config --global gitflow.prefix.release release/
      • git config --global gitflow.prefix.hotfix hotfix/
      • git config --global gitflow.prefix.support support/
      • git config --global gitflow.prefix.versiontag v
      • git config --global gitflow.path.hooks :/.git/hooks

Caso não tenha intimidade com o git flow, siga essas dicas

para melhorar a produtividade e evitar problemas ao se trabalhar em projetos maiores

Casos de erros e possíveis soluções​

  • Ao tentar instalar “npm” e pegar o erro “E: Impossível corrigir problemas, você manteve (hold) pacotes quebrados.”

Instale o aptitude com o seguinte comando:

sudo apt-get install aptitude

E após isso ao invés de fazer:

apt-get install nome-do-pacote

Faça:

aptitude install nome-do-pacote

Será perguntado se deseja manter os pacotes, informe “n” para não. Até a última pergunta e informar “Y” para sim.

Pronto, caso encerrado.

  • Se obter erro ao tentar baixar ou rodar as imagens do Docker, confira as permissões do Docker em sua máquina:

sudo chown "$USER":"$USER" /home/"$USER"/.docker -R

sudo chmod g+rwx "/home/$USER/.docker" -R

Se obter algum erro ou problema com relação às bibliotecas node, tente manter a versão 14.x do node instalada (devido boa parte das bibliotecas terem sido desenvolvidas com ele):

Como instalar

Docker e docker-compose​

Instale apenas o Docker CLI e não instale o Docker Desktop, pois eles podem ter conflito de rede.

  • O Docker Desktop pode ter um endereço IP diferente configurado nos projetos 172.17.0.1, portanto, recomendamos instalar apenas o Docker CLI.

https://docs.docker.com/desktop/install/linux-install/

Nas novas versões do Docker, o Docker Compose já está integrado.

Em alguns projetos, será necessário alterar o Makefile de docker-compose para docker compose.

Um dos problemas do Docker é a necessidade de permissão elevada. Caso enfrente algum problema desse tipo permission denied, execute o seguinte comando:

https://stackoverflow.com/questions/48957195/how-to-fix-docker-got-permission-denied-issue

sudo usermod -aG docker $USER

# /var/run/docker.sock
sudo chmod 666 /var/run/docker.sock

logo após, reinicie a máquina

Node e Yarn

  • Execute o comando
sudo apt update
sudo apt install nodejs npm -y

Insomnia

  • O Insomnia é um aplicativo para execução de chamadas HTTP, é muito útil para o teste e depuração de APIs e serviços web.

O manual de instalação se encontra

https://insomnia.rest/download

[sudo apt-get install insomnia](https://support.insomnia.rest/article/23-installation)

AWS​

  • Após você receber as credenciais para acessar nossos serviços AWS, você precisará configurá-las via CLI. Instale-a CLI da AWS seguindo a documentação https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2-linux.html;
  • Instalada a CLI da AWS, execute aws configure no terminal e utilize suas credenciais para configurar o acesso. Neste passo, apenas as informações de credenciais precisam ser respondidas (duas primeiras), para as duas restantes basta apenas pressionar enter e manter o padrão sugerido pela CLI;

$ aws configure

  • AWS Access Key ID [None]: [obtido na credencial AWS]
  • AWS Secret Access Key [None]: [obtido na credencial AWS]
  • region = us-east-1
  • Default output format [None]: json
  • Por fim, e não menos importante, execute o comando:
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 365555882271[.dkr.ecr.us-east-1.amazonaws.com](http://365555882271.dkr.ecr.us-east-1.amazonaws.com/)
  • O comando acima deve retornar “Login Succeed"

Para evitar problemas de autenticação, recomenda-se executar o comando acima sempre ao iniciar uma nova sessão (logon)

HostDB​

Antes de executar o host-db faz-se necessário clonar o projeto painel-v3.

Execute o comando para criar o link simbólico do tema de login do keycloack.

**sudo make install.symlinks**

Host-db é o repositório responsável por levantar toda a stack de serviços de banco de dados e organizar os endpoints de todas as APIs desenvolvidas, portanto, se tiver alguma dúvida do tipo “qual porta a API x escuta?” Será lá que encontrará a resposta.

É altamente recomendado que sempre, antes de iniciar as tarefas diárias, seja executado o comando make nesse diretório, uma vez que é ele o responsável por toda a stack de banco de dados, roteamento dos serviços, cache, etc.

Outras funcionalidades importantes presentes neste repositório são: um utilitário de backup e restore de bancos de dados, presente no diretório backup/  e um instalador de certificados SSL.

(Obs.: Conceda permissão de execução usando o comando $ sudo chmod +x ./backup.sh ./restore.sh)

Projetos em PHP​

Para projetos escritos em PHP, é necessário executar o comando $ make php.install para que as dependências do projeto sejam instaladas corretamente.

Projetos com Frontend em Angular/AngularJS​

Em projetos desse tipo, para que as dependências sejam instaladas no diretório node_modules basta executar o comando $ make node.install

Painel V3​

Nesse caso em especial, é necessário fazer a instalação das dependências tanto para o cliente, em Angular, e o server, em PHP (Lumen). Para isso, basta executar o comando  $ make install.dev no diretório raíz do projeto. Para que o projeto esteja em pleno funcionamento,  é necessário configurar o

Keycloak.

DBeaver

  • O DBeaver é uma ferramenta para a administração de bancos de dados, sendo útil para a execução de consultas, atualizações de dados e estruturas, etc.
  • A versão mais recente se se encontra aqui, e após feito o download o arquivo, instale-o usando o seguinte comando:

$ sudo dpkg -i arquivo/de/instalacao.deb

Make

  • O Make, de acordo com o site opensource.com, é um interpretador e executor de tarefas, sendo útil para automatizar tarefas repetitivas e/ou complexas demais para serem sempre executadas manualmente, através dos arquivos Makefile. Funções como flush de cache, instalação e atualização de dependências e bootstrap de serviços são as mais utilizadas por nós;
  • Caso esteja com alguma dúvida de o que um comando make faz, basta consultar o conteúdo do Makefile em questão e a sequência de passos estará lá;
  • Fique à vontade para automatizar tarefas repetitivas, extensas ou complexas usando os Makefiles!

Golang

  • Várias de nossas APIs e Backends são escritos em Go. Por se tratar de uma linguagem compilada, se faz necessário instalar o compilador e configurar algumas variáveis de ambiente para que todas funcionem de forma correta;
  • Realize a instalação da última versão utilizando a documentação oficial de instalação do Go (Obs.: Observe que também existe um caminho a ser adicionado à variável de ambiente PATH);

(Será necessária uma reinicialização do sistema para que essa alteração tenha efeito)

  • Por se tratar de uma linguagem compilada, muitos projetos utilizam o realize como task runner e auto reload. Para instalá-lo, utilize o comando:

$ GO111MODULE=off go get -u github.com/oxequa/realize

Protobuf

  • Para instalar o protobuf, siga os passos do manual de instalação;
  • Compilador de protobuf: Buf.build
    • Instalar primeiro o protobuf:
      • Ubuntu:
        • sudo apt-get install protobuf-compiler-grpc
      • Fedora:
        • sudo dnf install grpc-plugins
        • Criar atalho para plugin PHP:
          • sudo ln -s /usr/bin/grpc_php_plugin /usr/bin/protoc-gen-php-grpc

Para instala o buf:

https://docs.buf.build/installation

Realize​

O pacote realize (usado com Golang para watch e task runner), não recebe atualizações por um bom tempo. Caso não consiga instalá-lo, uma alternativa (não elegante) é colocar o binário dele diretamente em seu diretório ~/go/bin

  1. Baixe o binário: download realize
  2. Coloque-o em sua pasta BIN do Go, geralmente localizada em ~/go/bin
  3. Forneça acesso aos arquivos dessa pasta ao seu usuário (caso ainda não tenha)
    1. sudo chmod a+rwx ~/go/bin/*

Caso encontre problemas com comandos não encontrados, verifique se o diretório go/bin/ está incluído no arquivo .bashrc ou .zshrc.

FR migrations​

  • Instalação de certificados SSL

Antes de iniciar a execução de fato do host-db, instale os certificados SSL usando o comando

make install.certificates. Esta ação precisa ser feita apenas uma vez, ou ao reinstalar o sistema ou devido à expiração dos certificados.

Caso encontre algum problema para conectar-se ao banco de dados MySQL, possivelmente seja necessário alterar a senha.


docker ps | mysql

docker exec -it fr_mysql /bin/bash

// a senha padrao 'e 123456
mysql -u root -p

ALTER USER 'root'@'%' IDENTIFIED WITH mysql_native_password BY '123456';

Além disso, se tiver dificuldade de conectar-se ao MySQL, verifique se há algo bloqueando a conexão, como o firewall UFW.

https://www.javatpoint.com/ubuntu-disable-firewall

sudo UFW disable

É necessário criar o banco manualmente primeiro:

CREATE DATABASE painel_db_dev CHARSET utf8mb4;

Caso ocorra algum erro, verifique se o PHP consegue se conectar ao banco. O IP da rede Docker pode ser um pouco diferente do padrão 172.17.0.1. Para verificar, utilize o comando:

ip addr | grep docker

Execute os comandos abaixo para criar as tabelas do "painel_db_dev"

make install
make seed

Banco de dados de CEPs​

Ainda no projeto fr-migrations, execute o comando abaixo para baixar, criar e popular o banco de CEPs.

make migrate.api_cep

Banco de dados da API Cotação V3​

Acesse o readme de seeds da API Cotação V3 e siga as instruções para criar e popular a base de dados da cotação.

Keycloak​

Aplicação com fluxo de autenticação para o Dashboard Frete Rápido com a finalidade de Configurar e gerenciar fluxo de autenticação para usuários do Dashboard Frete Rápido.

A configuração deve ser feita para o usuário/email shipper@freterapido.com, em vez de painel-v3@freterapido.com.

Esse passo não se encontra na documentação do Keycloak.

  • No final da configuração do Keycloak, vá em 'Users' - 'Attributes'.
  • Adicione dois atributos no usuário: 'userId = 1' e 'userType = E'.

Untitled

Para rodar o keycloak acesse as instruções localizadas dentro da pasta host-db/keycloak/doc/readme.md e siga o passo a passo.

Após a configuração, você deve ser capaz de fazer login no Dashboard FR (painel-v3)

Tente entrar como um usuário do tipo embarcador:

Caso tenha algum problema com usuário ou senha inválida, tente usar 12345678.

Considerações finais​

Ao se trabalhar com projetos grandes usando uma arquitetura baseada em microsserviços, é muito comum se esquecer de levantar um serviço x ou y, o que acaba exigindo um tempo maior para identificação e correção do problema. Por exemplo: A API de cotação depende da API de CEP e do banco de dados para funcionar corretamente e ela, por sua vez, não funcionará se as duas não estiverem operacionais. Inicialmente esse será um problema frequente, no entanto, naturalmente com o tempo, será cada vez menos comum.

Como sugestão, crie um arquivo .sh com os serviços comumente utilizados, levantando cada um deles. Isso te poupará tempo e aumentará sua produtividade.

Procure sempre manter-se atualizado também com outros projetos paralelos ao seu. Dúvidas, sugestões, críticas e ideias são sempre bem-vindas.