Skip to content

Commit a4b0eb0

Browse files
doublebyte1doublebyte1
committed
- added pt translation of setup section
1 parent 160a362 commit a4b0eb0

File tree

1 file changed

+360
-0
lines changed

1 file changed

+360
-0
lines changed

‎workshop/content/docs/setup.pt.md‎

Lines changed: 360 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,360 @@
1+
---
2+
title: Configuração do ambiente da workshop
3+
---
4+
5+
# Configuração do ambiente da workshop
6+
7+
Nesta workshop, utilizamos os seguintes materiais:
8+
9+
1. **Documentação** - (como esta página): aceda à versão mais recente em [dive.pygeoapi.io](https://dive.pygeoapi.io)
10+
2. **Exercícios** - descarregue o [ficheiro zip mais recente](https://github.com/geopython/diving-into-pygeoapi/archive/refs/heads/main.zip), extraia o conteúdo e encontre os exercícios em `workshop/exercises` [^1]
11+
3. **Docker** - todos os exemplos/exercícios são executados num `contentor Docker` em `workshop/exercises`
12+
13+
[^1]: Em alternativa, pode fazer um *fork*/clonar o repositório GitHub desta workshop diretamente de <https://github.com/geopython/diving-into-pygeoapi>.
14+
15+
## Editor de Texto
16+
17+
O seu editor de texto deve ser capaz de editar ficheiros de configuração em **texto simples**. Abaixo estão algumas opções de editores de texto (pode haver outros), juntamente com o que alguns dos programadores da pygeoapi preferem usar:
18+
19+
* Notepad ou Notepad++ (Windows)
20+
* Sublime Text: Angelos
21+
* PyCharm: Just
22+
* Emacs: Just
23+
* Visual Studio Code: Francesco, Angelos, Joana
24+
* `vi` / `vim`: Tom, Angelos
25+
26+
Dito isto, sinta-se à vontade para usar o que funciona melhor para si :)
27+
28+
## YAML
29+
30+
A maioria dos exercícios focar-se-á na edição da [configuração](https://docs.pygeoapi.io/en/latest/configuration.html) da pygeoapi, que está no formato [YAML](https://yaml.org). Se não estiver familiarizado com YAML, vale a pena ler um [tutorial](https://www.cloudbees.com/blog/yaml-tutorial-everything-you-need-get-started) para se familiarizar com a sintaxe e a indentação do YAML.
31+
32+
O requisito principal para a formação é instalar o Docker e/ou o Docker Compose no seu sistema.
33+
Aconselhamos vivamente a instalação do Docker antes do início da workshop.
34+
35+
Embora sejam possíveis vários cenários de instalação personalizada (consulte a [documentação](https://docs.pygeoapi.io/en/latest/installation.html) para mais informações), estes não são considerados nesta workshop, dada a capacidade de instalar um ambiente totalmente reprodutível através do Docker e do Docker Compose.
36+
37+
Os Exercícios da Workshop também serão baseados no Docker, pelo que uma instalação personalizada seria, no mínimo, 'desafiadora'.
38+
A boa notícia é que apenas uma única instalação (Docker) é necessária! As imagens Docker utilizadas nesta workshop contêm a versão mais recente da pygeoapi e todas as suas dependências e serviços externos (ex: PostGIS).
39+
40+
## Sobre o Docker
41+
42+
O Docker está disponível desde 2013 e é fornecido como uma opção de implementação em inúmeros projetos de software FOSS e da OSGeo. Dada a era atual da computação, é provável que já tenha ouvido falar do Docker e de *contentorização*. Ou, talvez, já esteja familiarizado e, esperamos, já a utilizar o Docker.
43+
Se não for o caso, existe uma abundância de materiais introdutórios que podem ser encontrados online, como este [tutorial da IBM](https://www.ibm.com/topics/docker).
44+
45+
O software FOSS4G beneficiou enormemente do Docker (padrões consistentes de empacotamento, isolamento, integração e atualização) em comparação com as instalações personalizadas. Embora hoje utilizemos principalmente o Docker, a visão geral é o uso de **Contentores** como o próximo passo na virtualização. A contentorização certamente merece uma workshop própria, portanto, para os fins desta workshop, abordaremos apenas os conceitos básicos do Docker e do Docker Compose.
46+
47+
O [Docker Compose](https://docs.docker.com/compose) é um complemento do Docker para facilitar a orquestração (configuração) de um ou mais 'Contentores' Docker (um Contentor é uma instância em execução de uma imagem Docker) usando uma convenção de configuração (o ficheiro YAML do Docker Compose), geralmente chamado `docker-compose.yml`.
48+
49+
Num patamar superior, existem orquestradores Docker ainda mais sofisticados, como o [Rancher](https://rancher.com/products/rancher) e o [Kubernetes](https://kubernetes.io), mas para esta workshop, o Docker e o Docker Compose são tudo o que precisamos.
50+
51+
## Instalação
52+
53+
A instalação do Docker progrediu muito ao longo dos anos. Esta é a única parte da workshop que depende do sistema/SO que está a utilizar (ex: Windows, Mac ou Linux). Para cada sistema, o site do Docker fornece instruções de instalação detalhadas. Por favor, siga-as de forma consistente.
54+
55+
Para muitas plataformas, está disponível um produto chamado [Docker Desktop](https://docs.docker.com/desktop), que inclui os principais componentes do Docker:
56+
57+
* Instalação para [Windows](https://docs.Docker.com/desktop/install/windows-install)
58+
* Instalação para [Mac](https://docs.Docker.com/desktop/install/mac-install)
59+
* Instalação para [Linux](https://docs.Docker.com/desktop/install/linux-install)
60+
61+
Algumas notas:
62+
63+
* No Windows, recomendamos o uso do [Subsistema Windows para Linux](https://docs.microsoft.com/en-us/windows/wsl) (WSL), pois também fornece uma linha de comandos poderosa (Bash) e tem uma integração ótima com o Docker. Antes de instalar o Docker Desktop, instale o WSL abrindo o Microsoft PowerShell (executar como administrador) e executando `wsl --install`
64+
* **a instalação do WSL requer privilégios de administrador no seu sistema**
65+
* No Mac, se estiver a usar o [Homebrew](https://brew.sh), considere (como o autor fez) usar a [fórmula Docker do brew](https://formulae.brew.sh/formula/Docker)
66+
* No Mac OSX Monterey e posterior, pode haver um problema com a porta local 5000 já em uso, entrando em conflito com a porta padrão usada pelo contentor da pygeoapi. Se vir este erro `OSError: [Errno 48] Address already in use`, precisa de desativar o *Recetor Airplay*. Vá a `Definições do Sistema | Partilha` ou, como no Sonoma, escreva 'airplay' na caixa de pesquisa. Veja a imagem abaixo para o Mac OSX Sonoma. Há também uma descrição detalhada [nesta publicação de blog](https://progressstory.com/tech/port-5000-already-in-use-macos-monterey-issue/).
67+
![Definições do MacBook](assets/images/macosx-airplay-disable.png)
68+
* No Linux, pode escolher o instalador relevante para a sua plataforma. Pode também usar o Virtualbox com uma Imagem Ubuntu ou usar uma VM na nuvem.
69+
* No Linux, ao encontrar problemas de permissão: o *daemon* do Docker normalmente é executado como "root". Isto requer que os comandos sejam prefixados com `sudo` como um utilizador não-root. Na maioria das distribuições, o Docker é acessível por utilizadores no grupo `docker`. Pode omitir o uso de `sudo` e prevenir outros possíveis problemas de permissão da seguinte forma:
70+
* Teste se o grupo `docker` existe: `cat /etc/group | grep docker`.
71+
* Se não existir: `sudo groupadd docker`.
72+
* Adicione o seu utilizador a este grupo: `sudo usermod -aG docker $USER`
73+
* Faça log-out e log-in.
74+
* Veja todos os detalhes e mais opções [nesta instrução](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user).
75+
* O Docker Desktop inclui uma interface gráfica com algumas opções interessantes. Pode ver logs e informações sobre os contentores em execução, abrir o serviço deles num navegador ou até mesmo abrir um terminal dentro do contentor.
76+
77+
Se tudo correr bem, deverá conseguir executar o Docker a partir da linha de comandos da seguinte forma: [^2]
78+
79+
=== "Linux/Mac"
80+
81+
<div class="termy">
82+
```bash
83+
docker version
84+
Docker version 20.10.17, build 100c701
85+
86+
docker compose version
87+
Docker Compose version v2.6.1
88+
```
89+
</div>
90+
91+
=== "Windows (PowerShell)"
92+
93+
<div class="termy">
94+
```bash
95+
docker version
96+
Docker version 20.10.17, build 100c701
97+
98+
docker compose version
99+
Docker Compose version v2.6.1
100+
```
101+
</div>
102+
103+
(Não é necessário que os números da sua versão correspondam exatamente).
104+
[^2]: Para versões recentes do Docker, execute `docker compose version`
105+
106+
107+
## Início Rápido
108+
109+
Assim que o Docker estiver disponível no seu sistema, executar o contentor da pygeoapi com a sua configuração e dados incorporados é uma única linha de comando.
110+
111+
Abra uma sessão de terminal e execute:
112+
113+
!!! question "Primeira execução via Docker"
114+
115+
=== "Linux/Mac"
116+
117+
<div class="termy">
118+
```bash
119+
docker run --rm -p 5000:80 geopython/pygeoapi:latest
120+
Unable to find image 'geopython/pygeoapi:latest' locally
121+
latest: Pulling from geopython/pygeoapi
122+
d7bfe07ed847: Already exists
123+
d5d0144a7164: Already exists
124+
afe0923a0fa0: Already exists
125+
75f8618c4e86: Already exists
126+
c603397fd6ad: Already exists
127+
6584a95328b3: Already exists
128+
fd93e44631d9: Already exists
129+
6a3201071a5d: Already exists
130+
4f4fb700ef54: Already exists
131+
Digest: sha256:27b2b219497a6ea382a946ee90ae96ad00b5c1d8e9b725fccf23211978fef124
132+
Status: Downloaded newer image for geopython/pygeoapi:latest
133+
START /entrypoint.sh
134+
Trying to generate openapi.yml
135+
openapi.yml generated continue to pygeoapi
136+
make SCRIPT_NAME empty from /
137+
Start gunicorn name=pygeoapi on 0.0.0.0:80 with 4 workers and SCRIPT_NAME=
138+
[2022-08-09 12:59:00 +0000] [1] [INFO] Starting gunicorn 20.0.4
139+
[2022-08-09 12:59:00 +0000] [1] [INFO] Listening at: http://0.0.0.0:80 (1)
140+
[2022-08-09 12:59:00 +0000] [1] [INFO] Using worker: gevent
141+
[2022-08-09 12:59:00 +0000] [18] [INFO] Booting worker with pid: 18
142+
[2022-08-09 12:59:00 +0000] [19] [INFO] Booting worker with pid: 19
143+
[2022-08-09 12:59:00 +0000] [21] [INFO] Booting worker with pid: 21
144+
[2022-08-09 12:59:00 +0000] [22] [INFO] Booting worker with pid: 22
145+
```
146+
</div>
147+
148+
=== "Windows (PowerShell)"
149+
150+
<div class="termy">
151+
```bash
152+
docker run --rm -p 5000:80 geopython/pygeoapi:latest
153+
Unable to find image 'geopython/pygeoapi:latest' locally
154+
latest: Pulling from geopython/pygeoapi
155+
d7bfe07ed847: Already exists
156+
d5d0144a7164: Already exists
157+
afe0923a0fa0: Already exists
158+
75f8618c4e86: Already exists
159+
c603397fd6ad: Already exists
160+
6584a95328b3: Already exists
161+
fd93e44631d9: Already exists
162+
6a3201071a5d: Already exists
163+
4f4fb700ef54: Already exists
164+
Digest: sha256:27b2b219497a6ea382a946ee90ae96ad00b5c1d8e9b725fccf23211978fef124
165+
Status: Downloaded newer image for geopython/pygeoapi:latest
166+
START /entrypoint.sh
167+
Trying to generate openapi.yml
168+
openapi.yml generated continue to pygeoapi
169+
make SCRIPT_NAME empty from /
170+
Start gunicorn name=pygeoapi on 0.0.0.0:80 with 4 workers and SCRIPT_NAME=
171+
[2022-08-09 12:59:00 +0000] [1] [INFO] Starting gunicorn 20.0.4
172+
[2022-08-09 12:59:00 +0000] [1] [INFO] Listening at: http://0.0.0.0:80 (1)
173+
[2022-08-09 12:59:00 +0000] [1] [INFO] Using worker: gevent
174+
[2022-08-09 12:59:00 +0000] [18] [INFO] Booting worker with pid: 18
175+
[2022-08-09 12:59:00 +0000] [19] [INFO] Booting worker with pid: 19
176+
[2022-08-09 12:59:00 +0000] [21] [INFO] Booting worker with pid: 21
177+
[2022-08-09 12:59:00 +0000] [22] [INFO] Booting worker with pid: 22
178+
```
179+
</div>
180+
181+
182+
É tudo! Abra o seu navegador e navegue para `http://localhost:5000`, a página da pygeoapi será exibida.
183+
Como parte da execução inicial do `docker run`, o Docker descarregará a Imagem Docker da pygeoapi do [Docker Hub](https://hub.Docker.com/r/geopython/pygeoapi).
184+
Isto pode levar algum tempo, pois a imagem Docker inclui todas as dependências (como GDAL, etc.). Seja paciente! Este é um download único para toda a workshop, ou pode querer fazê-lo antecipadamente.
185+
186+
Algumas notas:
187+
188+
* O Docker executa um contentor da pygeoapi no seu sistema local na porta 5000, que é mapeada para a porta 80 dentro do contentor.
189+
* o contentor Docker da pygeoapi é executado com a [configuração padrão](https://github.com/geopython/pygeoapi/blob/master/docker/default.config.yml) e os dados do repositório GitHub.
190+
* tanto a configuração como os dados (do repositório GitHub) estão incorporados na Imagem Docker - iremos substituí-los mais tarde.
191+
* a opção `--rm` remove o Contentor Docker (mas não a imagem), após a execução.
192+
* pressione `CTRL-C` para parar o contentor e voltar ao terminal.
193+
194+
De seguida, pode substituir a configuração padrão e adicionar os seus próprios dados usando [volumes Docker](https://docs.Docker.com/storage/volumes).
195+
196+
## Personalizar a configuração
197+
198+
Nos próximos exercícios, vamos atualizar o ficheiro de configuração várias vezes.
199+
Para facilitar o desenvolvimento, vamos substituir a configuração da pygeoapi que reside por padrão em `/pygeoapi/local.config.yml` dentro do contentor por um ficheiro local que pode editar no seu editor de texto favorito.
200+
201+
!!! question "Substituir o ficheiro de configuração da pygeoapi"
202+
203+
Descarregue a configuração Docker padrão da pygeoapi de [default.config.yml](https://raw.githubusercontent.com/geopython/pygeoapi/master/docker/default.config.yml) para a pasta atual (ou navegue para a pasta onde descarregou o ficheiro), por exemplo com:
204+
205+
=== "Linux/Mac"
206+
207+
<div class="termy">
208+
```bash
209+
curl -O https://raw.githubusercontent.com/geopython/pygeoapi/master/docker/default.config.yml
210+
```
211+
</div>
212+
213+
=== "Windows (PowerShell)"
214+
215+
<div class="termy">
216+
```bash
217+
curl https://raw.githubusercontent.com/geopython/pygeoapi/master/docker/default.config.yml
218+
```
219+
</div>
220+
221+
Abra o ficheiro no seu editor de texto favorito e altere o título e a descrição da API:
222+
223+
``` {.yml linenums="59"}
224+
metadata:
225+
identification:
226+
title: A minha primeira execução da pygeoapi
227+
description: a pygeoapi fornece uma API para dados geoespaciais
228+
```
229+
230+
Agora execute o contentor com o ficheiro de configuração substituído:
231+
232+
=== "Linux/Mac"
233+
234+
<div class="termy">
235+
```bash
236+
docker run -p 5000:80 \
237+
-v $(pwd)/default.config.yml:/pygeoapi/local.config.yml \
238+
geopython/pygeoapi:latest
239+
```
240+
</div>
241+
242+
=== "Windows (PowerShell)"
243+
244+
<div class="termy">
245+
```bash
246+
docker run -p 5000:80 -v ${pwd}/default.config.yml:/pygeoapi/local.config.yml geopython/pygeoapi:latest
247+
```
248+
</div>
249+
250+
Neste ponto, navegue para `http://localhost:5000` para verificar o novo título e descrição.
251+
252+
!!! note
253+
254+
No Windows, o ficheiro descarregado pode ser renomeado para `default.config.yml.txt`. Certifique-se de renomear o ficheiro para `default.config.yml`.
255+
256+
257+
Ao usar uma montagem de volume Docker (opção `-v`), o Docker anexa ou 'monta' um diretório ou um único ficheiro do seu sistema anfitrião/local no Contentor Docker.
258+
259+
No trecho de código acima, `$(pwd)` indica a pasta de trabalho a partir da qual inicia o contentor Docker.
260+
261+
## Adicionar dados e definir o ficheiro de configuração
262+
263+
Além de adaptar a configuração, geralmente adicionará os seus próprios dados como ficheiros ou serviços de dados remotos como PostGIS ou WFS.
264+
265+
Também pode montar um diretório local como `data/` para `/pygeoapi/mydata` dentro do Contentor.
266+
Dentro do diretório de dados, pode armazenar dados vetoriais, ficheiros raster ou conjuntos de imagens de mosaicos vetoriais.
267+
268+
Abaixo está um exemplo onde a configuração é explicitamente definida para `pygeoapi-config.yml` através de uma variável de ambiente (`-e`) e usa uma montagem Docker para montar a pasta local `data` como `/pygeoapi/mydata`:
269+
270+
=== "Linux/Mac"
271+
272+
<div class="termy">
273+
```bash
274+
docker run -p 5000:80 \
275+
-v $(pwd)/data:/pygeoapi/mydata \
276+
-v $(pwd)/default.config.yml:/pygeoapi/pygeoapi-config.yml \
277+
-e PYGEOAPI_CONFIG=/pygeoapi/pygeoapi-config.yml \
278+
geopython/pygeoapi:latest
279+
```
280+
</div>
281+
282+
=== "Windows (PowerShell)"
283+
284+
<div class="termy">
285+
```bash
286+
docker run -p 5000:80 -v ${pwd}/data:/pygeoapi/mydata -v ${pwd}/default.config.yml:/pygeoapi/pygeoapi-config.yml -e PYGEOAPI_CONFIG=/pygeoapi/pygeoapi-config.yml geopython/pygeoapi:latest
287+
```
288+
</div>
289+
290+
Nas próximas secções, analisaremos exemplos adicionais de montagens na pasta de dados. Mais exemplos de implementação do Docker podem ser encontrados no [repositório GitHub da pygeoapi](https://github.com/geopython/pygeoapi/tree/master/docker/examples).
291+
292+
## Usar o Docker para Clientes Python
293+
294+
Em alguns exercícios, acedemos a *endpoints* remotos da `pygeoapi` usando a [OWSLib](https://owslib.readthedocs.io), uma biblioteca Python para interagir com os Serviços Web da OGC. A OWSLib pode ser instalada usando o comando padrão do Python `pip3 install OWSLib`, mas pode não ter o Python disponível, ou querer manter o seu sistema 'limpo'.
295+
296+
Como o Docker já está disponível no seu sistema, pode iniciar um Contentor com um ambiente Python completo e acedê-lo a partir de um *prompt* de shell `bash`. A linha mágica é:
297+
298+
`docker run -it --rm --network=host --name owslib python:3.10-slim /bin/bash`
299+
300+
Isto irá descarregar uma Imagem Docker oficial e pequena (125MB) do Python. Quando o Contentor é iniciado, é direcionado para uma sessão/*prompt* `bash`. O argumento `--network=host` permite que interaja diretamente com os serviços no seu sistema anfitrião, portanto com a `pygeoapi`, sem configurar uma rede Docker. A partir daí, pode iniciar o `python3`, instalar a OWSLib e talvez até outras ferramentas como `curl` e `wget`.
301+
302+
Abaixo está um exemplo completo, assumindo que a pygeoapi está a ser executada no seu `localhost` na porta 5000:
303+
304+
=== "Linux/Mac"
305+
306+
<div class="termy">
307+
```bash
308+
docker run -it --rm --network=host --name owslib python:3.10-slim /bin/bash
309+
Unable to find image 'python:3.10-slim' locally
310+
3.10-slim: Pulling from library/python
311+
5b5fe70539cd: Pull complete
312+
f4b0e4004dc0: Pull complete
313+
c5424f0ac885: Pull complete
314+
9d21fe1624ec: Pull complete
315+
de0194aa1c21: Pull complete
316+
Digest: sha256:7dc5b4e948acd18c1633b0e593ad0224298646612ce7d0b5ac6d4e17616d7e4b
317+
Status: Downloaded newer image for python:3.10-slim
318+
319+
root@docker-desktop:/# pip3 install owslib
320+
root@docker-desktop:/# python3
321+
>>> from owslib.ogcapi.features import Features
322+
>>> w = Features('http://localhost:5000')
323+
>>> w
324+
<owslib.ogcapi.features.Features object at 0x7ff493e6f850>
325+
>>> conformance = w.conformance()
326+
>>> conformance
327+
etc
328+
329+
```
330+
</div>
331+
332+
=== "Windows (PowerShell)"
333+
334+
<div class="termy">
335+
```bash
336+
docker run -it --rm --network=host --name owslib python:3.10-slim /bin/bash
337+
Unable to find image 'python:3.10-slim' locally
338+
3.10-slim: Pulling from library/python
339+
5b5fe70539cd: Pull complete
340+
f4b0e4004dc0: Pull complete
341+
c5424f0ac885: Pull complete
342+
9d21fe1624ec: Pull complete
343+
de0194aa1c21: Pull complete
344+
Digest: sha256:7dc5b4e948acd18c1633b0e593ad0224298646612ce7d0b5ac6d4e17616d7e4b
345+
Status: Downloaded newer image for python:3.10-slim
346+
347+
root@docker-desktop:/# pip3 install owslib
348+
root@docker-desktop:/# python3
349+
>>> from owslib.ogcapi.features import Features
350+
>>> w = Features('http://localhost:5000')
351+
>>> w
352+
<owslib.ogcapi.features.Features object at 0x7ff493e6f850>
353+
>>> conformance = w.conformance()
354+
>>> conformance
355+
etc
356+
357+
```
358+
</div>
359+
360+
Faremos referência a esta instalação em alguns dos Exercícios onde a OWSLib é utilizada.

0 commit comments

Comments
 (0)