-
Notifications
You must be signed in to change notification settings - Fork 8
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
vitor
authored and
vitor
committed
Dec 9, 2023
1 parent
a770dd1
commit fd8afb2
Showing
39 changed files
with
1,235 additions
and
977 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -8,4 +8,5 @@ mnt/ | |
.python_history | ||
.env | ||
.pyenv | ||
.pytest_cache | ||
.pytest_cache | ||
.DS_Store |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -15,4 +15,5 @@ RUN apt-get update && \ | |
/var/tmp/* \ | ||
/usr/share/man \ | ||
/usr/share/doc \ | ||
/usr/share/doc-base | ||
/usr/share/doc-base | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,36 +1,23 @@ | ||
# Initialize environment variables | ||
# command `make init-env ARGS="-it"` to set, password and fief_secret | ||
.PHONY: init-env | ||
init-env: | ||
./init/load_fief_env.py $(ARGS) | ||
|
||
.PHONY: up | ||
up: | ||
docker compose up -d --wait | ||
|
||
# Apply initial configuration to Fief instance (container must be already | ||
# running) | ||
# command `make fief-config ARGS="-localhost"` to add localhost uri to development | ||
.PHONY: fief-config | ||
fief-config: | ||
docker compose exec -T api-pgd sh -c "cd /api-pgd/init && python configure_fief.py $(ARGS)" | ||
|
||
.PHONY: down | ||
down: | ||
docker compose down | ||
|
||
.PHONY: tests | ||
tests: | ||
docker compose exec -T api-pgd sh -c "cd /api-pgd/tests && pytest -vvv --color=yes" | ||
|
||
# ### Extra configs | ||
# Build local edited Dockerfile | ||
.PHONY: build | ||
build: | ||
docker build --rm -t ghcr.io/gestaogovbr/api-pgd:latest-dev -f Dockerfile.dev . | ||
docker compose up -d --wait && docker compose exec -T api-pgd sh -c "cd /api-pgd/tests && pytest -vvv --color=yes" | ||
|
||
# example: make test TEST_FILTER=test_put_participante_missing_mandatory_fields | ||
TEST_FILTER=test | ||
# command `$ make test TEST_FILTER="test_put_participante_missing_mandatory_fields"` | ||
.PHONY: test | ||
test: | ||
docker compose exec api-pgd sh -c "cd tests && pytest -k $(TEST_FILTER) -vvv --color=yes" | ||
docker compose up -d --wait && docker compose exec api-pgd sh -c "cd /api-pgd/tests && pytest -k $(TEST_FILTER) -vvv --color=yes" | ||
|
||
.PHONY: build | ||
build: | ||
docker compose down ; docker rmi ghcr.io/gestaogovbr/api-pgd:latest-dev --force ; docker build --rm -t ghcr.io/gestaogovbr/api-pgd:latest-dev -f Dockerfile.dev . | ||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,5 +1,3 @@ | ||
markdown: kramdown | ||
|
||
[](https://github.com/gestaogovbr/api-pgd/actions/workflows/ci_tests.yml) | ||
|
||
## TL;DR (too long; didn't read) | ||
|
@@ -10,13 +8,11 @@ a desenvolver: | |
```bash | ||
git clone [email protected]:gestaogovbr/api-pgd.git && \ | ||
cd api-pgd && \ | ||
make init-env && \ | ||
# aqui tem que entrar com a senha de usuário do sistema operacional local | ||
sudo echo "127.0.1.1 fief" | sudo tee -a /etc/hosts && \ | ||
make up && \ | ||
make fief-config ARGS="-dev" | ||
make up | ||
``` | ||
|
||
> Exemplos de uso da api em [exmaples/](exmaples/) | ||
--- | ||
|
||
## Índice | ||
|
@@ -69,65 +65,25 @@ git clone [email protected]:gestaogovbr/api-pgd.git | |
|
||
### 2.3. Variáveis de ambiente | ||
|
||
A gestão de usuários é realizada por uma aplicação chamada [`fief`](https://www.fief.dev/). | ||
|
||
Para obter as suas configurações iniciais por meio da geração do arquivo `.env`: | ||
|
||
O script em [2.3.1.](#231-opção-1-defalut-e-autogenerated) ou [2.3.2.](#232-opção-2-criação-manual) | ||
irá criar o arquivo `.env` com as configurações necessárias do `fief` para o ambiente. | ||
|
||
O template do arquivo `.env` pode ser encontrado em [init/.env.template](init/.env.template). | ||
|
||
> As demais configurações da api, banco de dados e adicionais do próprio | ||
> fief são definidas no arquivo [docker-compose.yml](docker-compose.yml) | ||
### Para criar as variáveis de ambiente: | ||
|
||
#### 2.3.1. [Opção 1] DEFALUT E AUTOGENERATED | ||
|
||
Criado automaticamente as envs `email`, `password` e `fief_main_admin_api_key` | ||
conforme configurações default em [load_fief_env.py](init/load_fief_env.py#L116). | ||
São definidas no [docker-compose.yml](docker-compose.yml): | ||
* [db](docker-compose.yml#L11): | ||
- `POSTGRES_USER` | ||
- `POSTGRES_PASSWORD` | ||
- `POSTGRES_DB` | ||
* [api-pgd](docker-compose.yml#L31): | ||
- `SQLALCHEMY_DATABASE_URL` | ||
- `SECRET` | ||
- `ACCESS_TOKEN_EXPIRE_MINUTES` | ||
- `API_PGD_ADMIN_USER` | ||
- `API_PGD_ADMIN_PASSWORD` | ||
|
||
```bash | ||
make init-env | ||
``` | ||
|
||
#### 2.3.2. [Opção 2] CRIAÇÃO MANUAL | ||
|
||
Na execução do `make` abre prompt para definir manualmente `email`, `password` | ||
e `fief_main_admin_api_key`. | ||
|
||
> Se desejar criar manualmente também o `fief_main_admin_api_key`: | ||
> | ||
> Obter por python o valor aleatório com o comando: | ||
> `import secrets; secrets.token_urlsafe()` | ||
> | ||
> Senão deixar em branco o prompt `FIEF_MAIN_API_KEY [leave blank if want auto-generated]:` | ||
> que a variável `fief_main_admin_api_key` é gerada automaticamente. | ||
```bash | ||
make init-env ARGS="-it" | ||
``` | ||
|
||
### 2.4. Configuração do `/etc/hosts` | ||
|
||
Na gestão de usuários e controle de acesso da API é usada a aplicação | ||
`fief`. Para o seu correto funcionamento pela | ||
interface `swagger ui`, é **necessário que ela seja alcançável pelo mesmo host, tanto no navegador quanto dentro do container.** Para isso, em ambiente de desenvolvimento, será necessário estabelecer | ||
um alias. | ||
`fief` para o host `localhost` no arquivo `/etc/hosts`. | ||
|
||
```bash | ||
sudo echo "127.0.1.1 fief" | sudo tee -a /etc/hosts | ||
``` | ||
|
||
### 2.5. Iniciando os serviços (`banco`, `api-pgd`, `fief`) | ||
### 2.4. Iniciando os serviços (`banco` e `api-pgd`) | ||
|
||
```bash | ||
make up | ||
``` | ||
|
||
> ⚠️ Caso apareçam erros de permissão em "database", pare os containers | ||
> ⚠️ Caso apareçam erros de permissão em `./mnt/pgdata`, pare os containers | ||
> (`ctrl` + `C`) e digite: | ||
> | ||
> ```bash | ||
|
@@ -137,37 +93,25 @@ make up | |
> Para ajustar as permissões das pastas `./mnt/pgdata/` e todas as suas | ||
> subpastas | ||
### 2.6. Configuração inicial do Fief | ||
Configure o `fief` para incluir dados necessários ao funcionamento da `api-pgd` | ||
em ambiente `dev` (uri de autenticação, campos personalizados de usuários | ||
e outros... template das variáveis de ambiente em [.env.template](init/.env.template)). | ||
```bash | ||
make fief-config ARGS="-dev" | ||
``` | ||
### 2.5. Conferir Acessos | ||
### 2.7. Conferir Acessos | ||
|
||
* [`http://localhost:5057`](http://localhost:5057): endpoint da api-pgd | ||
* [`http://localhost:5057/docs`](http://localhost:5057/docs): swagger ui da api-pgd | ||
* [`http://fief:8000/admin/`](http://fief:8000/admin/): ui de administração do fief | ||
* [`http://fief:8000/docs`](http://fief:8000/docs): swagger ui da api do fief | ||
* [`http://localhost:5057`](http://localhost:5057): endpoint da api-pgd | ||
### 2.8. Desligar serviços | ||
### 2.6. Desligar serviços | ||
```bash | ||
make down | ||
``` | ||
## 3. Rodando testes | ||
|
||
Com os `containers` rodando | ||
([2.5. Iniciando os serviços](#25-iniciando-os-serviços-banco-api-pgd-fief)): | ||
|
||
### 3.1. Todos | ||
```bash | ||
make tests | ||
``` | ||
|
||
### 3.2. Selecionado | ||
|
||
Para rodar uma bateria de testes específica, especifique o arquivo que | ||
contém os testes desejados. Por exemplo, os testes sobre atividades: | ||
|
||
|
@@ -184,26 +128,13 @@ make test TEST_FILTER=test_create_huge_plano_trabalho | |
> para desenvolvimento. | ||
> As sessões a seguir são instruções para edição de algumas configurações do ambiente. | ||
### 4.1. Usuário administrador e cadastro de usuários | ||
|
||
Ao realizar a configuração inicial do `fief` já é criado um usuário | ||
administrador, o qual pode alterar algumas configurações e cadastrar | ||
novos usuários. | ||
|
||
O usuário e senha desse usuário administrador ficam configurados nas | ||
variáveis de ambiente `FIEF_MAIN_USER_EMAIL` e `FIEF_MAIN_USER_PASSWORD` | ||
conforme item [2.3. Variáveis de ambiente](#23-variáveis-de-ambiente) | ||
|
||
### 4.2. Atualizando imagem do api-pgd | ||
### 4.1. Atualizando imagem do api-pgd | ||
|
||
Durante o desenvolvimento é comum a necessidade de inclusão de novas | ||
bibliotecas `python` ou a instalação de novos pacotes `Linux`. Para que | ||
as mudanças surtam efeitos é necessário apagar os containers e refazer a | ||
imagem docker. | ||
|
||
> Confira se os containers não estão `up` com o comando `$ docker ps`. | ||
> Caso estejam: `$ make down` | ||
```bash | ||
make build | ||
``` | ||
|
@@ -220,27 +151,21 @@ make up | |
## 5. Arquitetura da solução | ||
|
||
O arquivo [`docker-compose.yml`](docker-compose.yml) descreve a `receita` | ||
dos contêineres que compõem a solução. Atualmente são utilizados `3 containers`: | ||
dos contêineres que compõem a solução. Atualmente são utilizados `2 containers`: | ||
|
||
* [db](docker-compose.yml#L4); [postgres:15](https://hub.docker.com/_/postgres) | ||
* [api-pgd](docker-compose.yml#L22); [ghcr.io/gestaogovbr/api-pgd:latest-dev](Dockerfile.dev) | ||
* [fief](docker-compose.yml#L59); [ghcr.io/fief-dev/fief:0.27](https://github.com/fief-dev/fief/blob/main/docker/Dockerfile) | ||
* [api-pgd](docker-compose.yml#L21); [ghcr.io/gestaogovbr/api-pgd:latest-dev](Dockerfile.dev) | ||
|
||
## 6. Dicas | ||
|
||
* Exemplos de uso da api em [examples/](examples/) | ||
* Para depuração, caso necessite ver como está o banco de dados no ambiente | ||
local, altere a porta do Postgres no [docker-compose.yml](docker-compose.yml#L8) | ||
de `"5432"` para `"5432:5432"` e o banco ficará exposto no host via `localhost`. | ||
Depois, basta usar uma ferramenta como o [dbeaver](https://dbeaver.io/) | ||
para acessar o banco. | ||
* O `email/login` e `password` do `fief` são definidos no item | ||
[2.3. Variáveis de ambiente](#23-variáveis-de-ambiente). | ||
Depois disso eles ficam no arquivo `.env`, bem como o `client_id` e o `client_secret` | ||
usados na autenticação da API ([api-pgd-swagger-ui](http://localhost:5057/docs), | ||
[fief-swagger-ui](http://fief:8000/docs)) (variáveis `FIEF_CLIENT_ID` e | ||
`FIEF_CLIENT_SECRET`, respectivamente). | ||
* Para subir o ambiente usando algum outro banco de dados externo, basta | ||
redefinir a variável de ambiente `SQLALCHEMY_DATABASE_URL` no | ||
[docker-compose.yml](docker-compose.yml#L38). | ||
[docker-compose.yml](docker-compose.yml#L34). | ||
|
||
|
Oops, something went wrong.