diff --git a/node_modules/.package-lock.json b/node_modules/.package-lock.json new file mode 100644 index 0000000..813d53f --- /dev/null +++ b/node_modules/.package-lock.json @@ -0,0 +1,6 @@ +{ + "name": "DocStruct", + "lockfileVersion": 3, + "requires": true, + "packages": {} +} diff --git a/package-lock.json b/package-lock.json index 55c9bf2..813d53f 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,38 +1,6 @@ { + "name": "DocStruct", + "lockfileVersion": 3, "requires": true, - "lockfileVersion": 1, - "dependencies": { - "dom-walk": { - "version": "0.1.2", - "resolved": "https://registry.npmjs.org/dom-walk/-/dom-walk-0.1.2.tgz", - "integrity": "sha512-6QvTW9mrGeIegrFXdtQi9pk7O/nSK6lSdXW2eqUspN5LWD7UTji2Fqw5V2YLjBpHEoU9Xl/eUWNpDeZvoyOv2w==" - }, - "global": { - "version": "4.4.0", - "resolved": "https://registry.npmjs.org/global/-/global-4.4.0.tgz", - "integrity": "sha512-wv/LAoHdRE3BeTGz53FAamhGlPLhlssK45usmGFThIi4XqnBmjKQ16u+RNbP7WvigRZDxUsM0J3gcQ5yicaL0w==", - "requires": { - "min-document": "^2.19.0", - "process": "^0.11.10" - } - }, - "min-document": { - "version": "2.19.0", - "resolved": "https://registry.npmjs.org/min-document/-/min-document-2.19.0.tgz", - "integrity": "sha512-9Wy1B3m3f66bPPmU5hdA4DR4PB2OfDU/+GS3yAB7IQozE3tqXaVv2zOjgla7MEGSRv95+ILmOuvhLkOK6wJtCQ==", - "requires": { - "dom-walk": "^0.1.0" - } - }, - "process": { - "version": "0.11.10", - "resolved": "https://registry.npmjs.org/process/-/process-0.11.10.tgz", - "integrity": "sha512-cdGef/drWFoydD1JsMzuFf8100nZl+GT+yacc2bEced5f9Rjk4z+WtFUTBu9PhOi9j/jfmBPu0mMEY4wIdAF8A==" - }, - "retypeapp": { - "version": "3.5.0", - "resolved": "https://registry.npmjs.org/retypeapp/-/retypeapp-3.5.0.tgz", - "integrity": "sha512-YhHilXfKLXU2BCZ0lfj4tUVMrk8nUjkSCAoV52xIPfRfSKQQah9D5vn2Eiu+FUmeGGEB9gykr8UVi7CvjmiqbQ==" - } - } + "packages": {} } diff --git a/package.json b/package.json new file mode 100644 index 0000000..0967ef4 --- /dev/null +++ b/package.json @@ -0,0 +1 @@ +{} diff --git a/stack/assets/logos-tecnologias/docker-logo.png b/stack/assets/logos-tecnologias/docker-logo.png new file mode 100644 index 0000000..428dd0d Binary files /dev/null and b/stack/assets/logos-tecnologias/docker-logo.png differ diff --git a/stack/auxiliares/docker/build.md b/stack/auxiliares/docker/build.md new file mode 100644 index 0000000..004616a --- /dev/null +++ b/stack/auxiliares/docker/build.md @@ -0,0 +1,55 @@ +--- +order: 4 +icon: tools +label: "Fazendo o build" +author: + name: Pedro Santos +date: 2025-10-28 +category: Explicação +tags: + - explicacao + - images +--- + +# Fazendo a build de uma image + +Com uma dockerfile em mãos, prosseguimos para construir, ou fazer o build de uma image. O comando usado para isso é o comando `docker build`, que segue o formato: + +`docker build [OPTIONS] PATH | URL` + +Onde `[OPTIONS]` indica as flags e `PATH|URL` indica o contexto de execução, que pode ser um diretório local ou um repositório remoto. + +O comando build busca um arquivo com o nome Dockerfile dentro do contexto de execução e o usa para construir a image, por isso é mais conveniente sempre usar esse nome. Abaixo estão algumas flags interessantes que podem ser usadas para modificar o comportamento do comando build. A documentação introdutória para este assunto pode ser acessada em https://docs.docker.com/get-started/docker-concepts/building-images/build-tag-and-publish-an-image/. + +## Flags frequentemente usadas + +`--no-cache`: assegura que a build seja totalmente refeita, ignorando o cache de execuções prévias. + +`-f `: faz com que o docker busque e utilize o arquivo de nome `file` para a construção, ao invés de buscar o arquivo de nome padrão Dockerfile. + +`--label =“”`: permite adicionar metadados à build. + +`-t :`: adiciona tags à imagem, como nome e versão, caso não seja especificado o docker sempre utiliza a tag “:latest” como padrão. + +## Comandos relacionados à images + +Aqui estão alguns comandos mais frequentemente utilizados para gerenciar images docker. + +- `docker image ls`: lista as images presentes no sistema. + +- `docker image pull [OPTIONS] NAME[:TAG|@DIGEST]`: faz download de uma image em um registro remoto. + +- `docker image push [OPTIONS] NAME[:TAG]`: faz upload de uma image para um registro remoto. + +- `docker image rm [OPTIONS] IMAGE [IMAGE...]`: remove uma ou mais images. + +- `docker image tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]`: cria uma nova tag para uma image já existente. + +## Retomando o exemplo + +Para fazer a build do servidor python simples demonstrado na seção anterior, utilizamos o seguinte comando, notando que é necessário estar no mesmo diretório que a dockerfile. + +`docker build -t python-server:v1 .` + +Utilizamos a flag `-t` para nomear a image python-server, com a tag v1. Use o comando `docker image ls` para verificar que a image está de fato no seu sistema. + diff --git a/stack/auxiliares/docker/compose.md b/stack/auxiliares/docker/compose.md new file mode 100644 index 0000000..d8b416b --- /dev/null +++ b/stack/auxiliares/docker/compose.md @@ -0,0 +1,124 @@ +--- +order: 1 +icon: versions +label: "O compose" +author: + name: Pedro Santos +date: 2025-10-28 +category: Explicação +tags: + - explicacao + - images + - compose +--- + +# O que é Docker compose + +Docker compose é uma ferramenta para definir e manter aplicações multi-container. Esta ferramenta facilita a manutenção +da aplicação, suas redes e volumes, ao permitir a configuração em um único arquivo YAML. + +## Instalação + +Para instalar o plugin do docker compose, basta usar o seguinte comando: + +```bash +sudo apt-get install docker-compose-plugin +``` + +## Exemplo + +Este exemplo foi copiado da documentação oficial do docker compose, disponível em https://docs.docker.com/compose/gettingstarted/#step-1-set-up. + +```bash + mkdir composetest + cd composetest +``` + +```python3 app.py +import time + +import redis +from flask import Flask + +app = Flask(__name__) +cache = redis.Redis(host='redis', port=6379) + +def get_hit_count(): + retries = 5 + while True: + try: + return cache.incr('hits') + except redis.exceptions.ConnectionError as exc: + if retries == 0: + raise exc + retries -= 1 + time.sleep(0.5) + +@app.route('/') +def hello(): + count = get_hit_count() + return f'Hello World! I have been seen {count} times.\n' +``` + +```requirements.txt +flask +redis +``` + +```docker Dockerfile +FROM python:3.10-alpine +WORKDIR /code +ENV FLASK_APP=app.py +ENV FLASK_RUN_HOST=0.0.0.0 +RUN apk add --no-cache gcc musl-dev linux-headers +COPY requirements.txt requirements.txt +RUN pip install -r requirements.txt +EXPOSE 5000 +COPY . . +CMD ["flask", "run", "--debug"] +``` + +Até agora estes foram os passos padrão para definir uma image, para usar o compose é preciso criar um arquivo de configuração YAML. + +```yaml compose.yaml +services: + web: + build: . + ports: + - "8000:5000" + redis: + image: "redis:alpine" +``` + +Esse arquivo define 2 serviços, `web` e `redis`. O serviço `web` utiliza dockerfile presente no diretório para fazer o build, e utiliza uma conexão entre as portas do container e uma porta externa. + +## Building + +Para fazer o build usando o docker compose, use o comando: + +`docker compose up` + +É possível utilizar as flags para execução de container no docker compose, por exemplo, `-d` faz com que os containers rodem no background. + +## Alguns comandos interessantes + +A lista completa de comandos pode ser acessada em https://docs.docker.com/reference/cli/docker/compose/. + +- `docker compose down [OPTIONS] [SERVICES]`: Interrompe e remove containers, redes e volumes criados por um comando `up`. + +- `docker compose images [OPTIONS] [SERVICE]`: lista as imagens utilizadas por containers. + +- `docker compose kill [OPTIONS] [SERVICE]`: força a interrupção de containers. + +- `docker compose ls [OPTIONS]`: lista os projetos compose sendo executados. + +- `docker compose ps [OPTIONS] [SERVICE]`: lista e fornece informações acerca dos containers em um projeto compose. + +- `docker compose pull [OPTIONS] [SERVICE]`: faz download de uma image associada a um serviço definido por um arquivo `compose.yaml`. + +- `docker compose up [OPTIONS] [SERVICE]`: builda, cria e inicia containers para um serviço. + +## Documentação para YAML + +A documentação para os arquivos `compose.yaml` é extremamente extensa, a documentação oficial pode ser acessada em https://docs.docker.com/reference/compose-file/. + diff --git a/stack/auxiliares/docker/conceitos_importantes.md b/stack/auxiliares/docker/conceitos_importantes.md new file mode 100644 index 0000000..c17997b --- /dev/null +++ b/stack/auxiliares/docker/conceitos_importantes.md @@ -0,0 +1,29 @@ +--- +order: 6 +icon: book +label: "Conceitos" +author: + name: Pedro Santos +date: 2025-10-28 +category: Conceitos importantes +tags: + - fundamentos + - explicacao +--- + +# Antes de iniciar... + +Antes de iniciar a explicação sobre como usar docker para desenvolver suas aplicações, é necessário falar sobre alguns conceitos essenciais para a compreensão dos próximos tópicos. A documentação introdutória oficial para este assunto está disponível em https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-container/. + +# Docker images + +Container é como chamamos os processos sendo executado por uma máquina, mas como o container sabe qual é sua tarefa e quais são as dependencias necessárias para executar tal tarefa? Utilizando uma image. + +Uma image é como chamamos o pacote que inclui os arquivos binários, dependências, bibliotecas e configurações para um container. Em termos da programação orientada à objetos, a docker image é uma classe, e os containeres são instâncias dessa classe. + +É importante notar que images são imutáveis, uma vez criadas, só podem ser alteradas adicionado mudanças ou criando uma nova image do zero. Além disso, images são construídas em camadas, cada camada representa uma mudança no sistema de arquivos, adicionando, removendo ou modificando arquivos. + +# Docker registry + +Para compartilhar docker images, existem os docker registries, plataformas que permitem armazenamento e compartilhamento de images, de modo similar ao github, mas exclusivas para images. O registro oficial do docker é o DockerHub, que pode ser acessado em https://hub.docker.com/. Há outros registros, por exemplo, as grandes empresas fornecedoras de computação em nuvem, como Amazon (Amazon Elastic Container Registry) , Microsoft (Azure container registry), e Google (Google Container Registry) também oferecem registros para containeres. + diff --git a/stack/auxiliares/docker/containers.md b/stack/auxiliares/docker/containers.md new file mode 100644 index 0000000..3b74443 --- /dev/null +++ b/stack/auxiliares/docker/containers.md @@ -0,0 +1,69 @@ +--- +order: 3 +icon: rocket +label: "Executando um container" +author: + name: Pedro Santos +date: 2025-10-28 +category: Explicação +tags: + - fundamentos + - explicacao +--- + + +# Rodando containers + +Se já temos uma image, podemos executar um container a partir dessa image, para isso, utilizamos o comando `docker run`, que tem o seguinte formato. + +`docker container run [OPTIONS] IMAGE [COMMAND] [ARG...]` + +Caso o docker não encontre localmente a image que você deseja rodar, ele fará uma busca no registro remoto configurado, o registro padrão é o dockerhub. A documentação introdutória oficial para este assunto está disponível em https://docs.docker.com/get-started/docker-concepts/running-containers/publishing-ports/ + +## Flags para o comando run + +Abaixo estão algumas flags frequentemente utilizadas para modificar o comando de execução. + +`--name `: designa o nome `custom-name` ao container, caso não seja especificado, docker vai gerar um nome aleatório. + +`-p :`: conecta a porta `host-port` à porta `container-port` do container. + +`-d`: roda o container no background, ou seja, não ocupa o terminal atual. + +`-e =`: define uma variável de ambiente. + +`--rm`: encerra o container quando a execução deste for concluída. + +`--memory `: especifica um limite de memória para o container, caso o limite seja ultrapassado o container é encerrado. + +`-t`: conecta o terminal ao I/O stream do container. + +`-i`: permite enviar texto ao stdin(input padrão) do container. + +## Comandos úteis para o gerenciamento de containers + +Aqui estão alguns comandos frequentemente utilizados para o gerenciamento de containers. + +`docker ps`: lista os containers ativos. + +`docker kill `: finaliza um container de maneira abrupta. + +`docker stop `: finaliza um container, esperando um certo tempo por seu encerramento. + +`docker port `: lista as portas utilizadas por um container. + +`docker stats `: mostra os recursos atualmente utilizados pelo container. + +`docker rename `: renomeia um container. + +`docker restart `: reinicia um container. + +## Retomando o exemplo + +Vamos rodar o servidor python que fizemos anteriormente, para isso, usamos o seguinte comando: + +`docker run -p 8000:8000 -d python-server:v1` + +Verifique que o container está rodando utilizando o comando `docker ps`. Como não utilizamos a flag `--name`, nosso container recebeu automaticamente um nome aleatório. + +Há algumas formas diferentes de interromper o container. A maneira mais "graciosa", de acordo com o docker, é utilizando o comando `docker stop`, pois este envia um sinal de parada ao container e espera seu encerramento. Ao contrário do `docker stop`, o comando `docker kill` finaliza abruptamente um container, o que pode comprometer processos que não são fechados corretamente. \ No newline at end of file diff --git a/stack/auxiliares/docker/images.md b/stack/auxiliares/docker/images.md new file mode 100644 index 0000000..5a3f7f8 --- /dev/null +++ b/stack/auxiliares/docker/images.md @@ -0,0 +1,97 @@ +--- +order: 5 +icon: paste +label: "Escrevendo images" +author: + name: Pedro Santos +date: 2025-10-28 +category: Explicação +tags: + - fundamentos + - explicacao + - images +--- + +# Criando uma image + +Para criar uma image, utilizamos uma dockerfile, que é um arquivo contendo instruções acerca de como construir a image requerida. Uma boa prática é sempre criar a dockerfile no mesmo diretório dos arquivos que serão necessários para o container. É comum escrever os comandos dentro de uma dockerfile utilizando letras maiúsculas, abaixo estão alguns comandos mais mente utilizados. A documentação introdutória oficial para este assunto pode ser acessada em https://docs.docker.com/get-started/docker-concepts/building-images/. + +## Comandos mais utilizados + +-`FROM `: especifica uma image já existente para ser usada como base. + +-`WORKDIR `: especifica o diretório de trabalho atual dentro da image, ou seja, onde os próximos comandos serão executados e para onde os arquivos devem ser copiados. Caso o diretório ainda não exista, ele será criado automaticamente. + +-`COPY `: copia o arquivo `src` para dentro da image no path `dest`. + +-`ADD `: faz a mesma coisa que COPY, mas permite que src seja uma URL. É importante notar que, caso `src` seja um arquivo .tar, este comando irá automaticamente fazer a extração dos arquivos no interior do .tar. + +-`RUN `: faz com que o construtor execute o comando especificado. + +-`ENV `: define uma variável de ambiente. + +-`EXPOSE `: esse comando meramente indica ao usuário em qual porta o construtor da image gostaria que o container fosse exposto, porém não realiza de fato nenhuma ação. + +-`CMD [“”, “”]`: especifica o comando padrão a ser executado pela image. + +-`ARG `: declara uma variável que deve receber um valor durante a build da image. + +## Exemplo prático + +Como exemplo, vamos fazer uma Dockerfile para um server http simples usando python, o server retorna apenas uma página com "Hello world". + +```bash + +mkdir Dockerteste +cd Dockerteste +touch server.py +touch index.html +touch Dockerfile +``` + +```python Dockerteste/server.py +from http.server import SimpleHTTPRequestHandler, HTTPServer + +server = HTTPServer(("0.0.0.0", 8000), SimpleHTTPRequestHandler) +server.serve_forever() +``` + +```html Dockerteste/index.html +

Hello world

+``` + +```docker Dockerteste/Dockerfile +FROM ubuntu + +RUN apt-get update +RUN apt-get install -y python3 + +WORKDIR /server +COPY index.html . +COPY server.py . + +EXPOSE 8000 +CMD ["python3", "server.py"] +``` + +Cada comando na Dockerfile de exemplo realiza os seguintes passos: + +- `FROM ubuntu`: especifica que queremos usar uma image já existente do SO ubuntu. + +- `RUN apt-get update`: executa o comando de busca de atualizações. + +- `RUN apt-get install -y python3`: executa o comando para instalação do python. + +- `WORKDIR /server`: cria o diretório `/server` e o configura como diretório de trabalho atual. + +- `COPY index.html`: copia `index.html` para o diretório `/server`. + +- `COPY server.py`: copia `server.py` para o diretório `/server`. + +- `EXPOSE 8000`: mostra que queremos expor o container na porta 8000. + +- `CMD ["python3", "server.py"]`: executa o comando "python3 server.py" ao iniciar o container. + +## Podemos usar um .dockerignore + +Caso queira que o docker ignore completamente um arquivo específico, basta criar um arquivo `.dockerignore` e incluir o nome do arquivo. Assim como o `.gitignore`, os arquivos nomeados serão totalmente ignorados. diff --git a/stack/auxiliares/docker/index.yml b/stack/auxiliares/docker/index.yml new file mode 100644 index 0000000..2bc710c --- /dev/null +++ b/stack/auxiliares/docker/index.yml @@ -0,0 +1,5 @@ +icon: /assets/logos-tecnologias/docker-logo.png +label: Docker +author: + name: Pedro Santos +date: 2025-09-28 diff --git a/stack/auxiliares/docker/introducao.md b/stack/auxiliares/docker/introducao.md new file mode 100644 index 0000000..46541fc --- /dev/null +++ b/stack/auxiliares/docker/introducao.md @@ -0,0 +1,32 @@ +--- +order: 7 +icon: question +label: "O que é docker?" +author: + name: Pedro Santos +date: 2025-10-28 +category: Explicação +tags: + - fundamentos + - explicacao +--- + +# O que é docker? + +Docker é uma plataforma para desenvolvimento, distribuição e execução de aplicações. É uma plataforma baseada em containers, permitindo isolamento e segurança entre diferentes processos. Como containers são feitos para consumirem poucos recursos, isso permite o uso eficiente de recursos, ao distribuir a memória e poder computacional entre diversos containers. + +# O que é um container? + +Um container é uma unidade de software que contém todos os pacotes necessários para rodar uma determinada aplicação. Esses containers funcionam como processos isolados, rodando em um ambiente próprio. Isso garante alguns benefícios, como: + +- Independência: como cada container existe em um ambiente isolado, é possível evitar conflitos de dependência entre processos ao incluir diferentes versões de bibliotecas em cada container. + +- Velocidade: containers podem ser iniciados e finalizados em um intervalo de tempo muito pequeno(segundos ou minutos), permitindo mais rapidez no desenvolvimento, manutenção e distribuição de aplicações. + +- Segurança: como cada container é um ambiente isolado, ataques ou falhas de segurança em um container não podem afetar outros containers e nem a máquina que está executando o processo. + +- Portatibilidade: containers podem rodar em qualquer máquina que suporte o sistema docker, desde computadores pessoais até ambientes de nuvem. + +## Containers não são máquinas virtuais + +Enquanto VM’s são abstrações de uma máquina física, containers são abstrações à nível de aplicação. Máquinas virtuais precisam ter um sistema operacional próprio, o que as faz consumir muitos recursos do sistema. Containers não precisam de um sistema operacional instalado internamente, podendo compartilhar o kernel com outros containers, o que demanda muito menos recursos. \ No newline at end of file diff --git a/stack/auxiliares/docker/memoria.md b/stack/auxiliares/docker/memoria.md new file mode 100644 index 0000000..085d915 --- /dev/null +++ b/stack/auxiliares/docker/memoria.md @@ -0,0 +1,48 @@ +--- +order: 2 +icon: cache +label: "Persistência de dados" +author: + name: Pedro Santos +date: 2025-10-28 +category: Explicação +tags: + - fundamentos + - explicacao +--- + +# Persistência de dados e containers + +Quando um container é iniciado, ele usa os arquivos configurados na image. Embora o container possa criar, deletar e alterar arquivos ao longo de sua execução, os dados alterados são apagados ao finalizar o container. Para lidar com persistência de dados, há 2 mecanismos possíveis, volume e bind. A documentação introdutória oficial para este assunto está disponível em https://docs.docker.com/get-started/docker-concepts/running-containers/persisting-container-data/. + +## Volumes + +Volumes são um mecanismo de persistência de dados que permite armazenar dados fora de um container. Esses arquivos são criados e gerenciados pelo docker, e ficam armazenados no host do container. Para criar um volume, usamos o comando a seguir: + +`docker volume create ` + +Para conectar um volume à um container, operação chamada de "montar" um volume, é utilizada a flag -v ao iniciar o container: + +`docker run -v : ` + +Isso faz como que todos os arquivos escritos em source sejam salvos no volume, que não é apagado quando o container é encerrado. Abaixo estão alguns comandos interessantes para o gerenciamento de volumes. + +`docker volume ls`: lista os volumes + +`docker volume rm `: apaga um volume, é necessário que este volume não esteja sendo utilizado por nenhum container, caso contrário sua destruição é bloqueada. + +`docker volume prune`: remove todos os volumes não sendo usados por nenhum container. + +`docker volume inspect `: fornece informações acerca do volume. + +## Binds + +Outro modo de adquirir durabilidade de dados é dar ao container acesso à arquivos no host, ou seja, compartilhar arquivos entre o host e o container. Para isso, o docker disponibiliza um mecanismo chamado bind, que pode ser feito com o seguinte comando: + +`docker run --mount type=bind,source=,target= ` + +Por exemplo, para bindar o seu diretório /Documents para o diretório /Documents de um container ubuntu, basta usar o seguinte comando: + +`docker run -ti --mount type=bind,source=/home//Documents,target=/Documents ubuntu` + +Para fins de segurança, é possível fazer um bind read-only, basta adicionar a keyword `readonly`, separada por vírgula, após o argumento target. \ No newline at end of file