DEV Community: Alexandre Fernandes dos Santos

Docker Compose - Observability made easy

Alexandre Fernandes dos Santos — Sat, 14 Feb 2026 21:52:25 +0000

Hello, JavaScript backend veterans! I bring you an observability stack based on OpenTelemetry, using VictoriaMetrics for metrics, VictoriaLogs for logs, and Jaeger for traces.

It's a stack focused on a development environment, but nothing prevents it from being used in a low-volume production application with some adjustments.

Show me the code

This time I couldn't bring just a single Docker Compose YAML 😢, but it's only a little bit more, I promise 🙏.

otel_config.yaml

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: :4317

exporters:
  otlp:
    endpoint: jaeger:4317
    tls:
      insecure: true

  otlphttp:
    logs_endpoint: http://victoria_logs:9428/insert/opentelemetry/v1/logs
    metrics_endpoint: http://victoria_metrics:8428/opentelemetry/v1/metrics
    tls:
      insecure: true

service:
  pipelines:
    logs:
      receivers: [otlp]
      exporters: [otlphttp]

    metrics:
      receivers: [otlp]
      exporters: [otlphttp]

    traces:
      receivers: [otlp]
      exporters: [otlp]

This file is responsible for the OpenTelemetry Collector configuration.

It basically defines how we will receive our application data (receivers), allows us to add some processing (like compression and batching) if we want, and configures how data will be exported (exporters).

datasources.yaml

apiVersion: 1
datasources:
  - name: VictoriaMetrics
    type: victoriametrics-metrics-datasource
    access: proxy
    url: http://victoria_metrics:8428
    isDefault: true

  - name: VictoriaLogs
    type: victoriametrics-logs-datasource
    access: proxy
    url: http://victoria_logs:9428
    isDefault: false

We need this file to configure the Grafana datasources—in our case, the metrics and logs sources that will be used.

docker-compose.yaml

services:
  grafana:
    image: "grafana/grafana:12.3.3"
    volumes:
      - grafana:/var/lib/grafana
      - ./datasources.yaml:/etc/grafana/provisioning/datasources/datasources.yaml:ro
    networks:
      - monitoring 
    ports:
      - 3000:3000
    environment:
      GF_PLUGINS_PREINSTALL: victoriametrics-metrics-datasource,victoriametrics-logs-datasource
      GF_SECURITY_ADMIN_USER: admin
      GF_SECURITY_ADMIN_PASSWORD: admin

  otlp_collector:
    image: "otel/opentelemetry-collector-contrib:0.145.0"
    volumes:
      - ./otel_config.yaml:/etc/otelcol/config.yaml:ro
    command: ["--config=/etc/otelcol/config.yaml"]
    ports:
      - 4317:4317
    networks:
      - monitoring 

  victoria_metrics:
    image: "victoriametrics/victoria-metrics:v1.135.0"
    volumes:
      - metrics:/victoria-metrics-data
    environment:
      storageDataPath: "victoria-metrics-data"
      retentionPeriod: "1d"
    networks:
      - monitoring 

  victoria_logs:
    image: "victoriametrics/victoria-logs:v1.45.0"
    volumes:
      - logs:/victoria-metrics-data
    environment:
      storageDataPath: "victoria-metrics-data"
      retentionPeriod: "1d"
    networks:
      - monitoring 

  jaeger:
    image: "cr.jaegertracing.io/jaegertracing/jaeger:2.15.0" 
    networks:
      - monitoring 
    ports:
      - 16686:16686
    environment:
      MEMORY_MAX_TRACES: 10000

volumes:
  grafana:
  metrics:
  logs:

networks:
  monitoring:

Here is where the fun begins. I don't think it's worth going into too much detail because everything can be found better explained elsewhere than a mere mortal like me could do, so I'll just leave a few points of attention:

Logs and metrics will be exposed by Grafana on port 3000. So, by connecting to localhost:3000 and using the credentials set in the YAML, you'll have access to them.
Traces will be exposed similarly, but the Jaeger tool uses port 16686.
This Jaeger instance was configured without persistence, so upon restarting the container, previously ingested traces will be lost. In case you want an easy way to add persistence, you can use Badger as a Storage Backend.

Arrivederci

Until later, my friends! I hope this article is useful in your journey to spin up OTLP locally.

That's all! In case you have any doubts or suggestions, just let me know. I'll be happy to answer!

Docker Compose - Stack de Observabilidade sem complicação

Alexandre Fernandes dos Santos — Sat, 14 Feb 2026 21:20:09 +0000

Olá, veteranos do JavaScript no backend! Trago para vocês uma stack de observabilidade baseada em OpenTelemetry, usando VictoriaMetrics para métricas, VictoriaLogs para logs e Jaeger para Traces.

É uma stack focada em ambiente de desenvolvimento, mas nada impede que, com alguns ajustes, possa ser usada em uma aplicação em produção de baixo volume.

Show me the code

Dessa vez não vai dar para ser só um YAML de docker compose 😢, mas é pouca coisa a mais, prometo 🙏.

otel_config.yaml

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: :4317

exporters:
  otlp:
    endpoint: jaeger:4317
    tls:
      insecure: true

  otlphttp:
    logs_endpoint: http://victoria_logs:9428/insert/opentelemetry/v1/logs
    metrics_endpoint: http://victoria_metrics:8428/opentelemetry/v1/metrics
    tls:
      insecure: true

service:
  pipelines:
    logs:
      receivers: [otlp]
      exporters: [otlphttp]

    metrics:
      receivers: [otlp]
      exporters: [otlphttp]

    traces:
      receivers: [otlp]
      exporters: [otlp]

Esse arquivo é responsável pela configuração do Collector do OpenTelemetry.

Ele basicamente define como devemos receber os dados da nossa aplicação (receivers), adiciona alguns processamentos (como compressão e batch) se quisermos, e configura para onde os dados serão exportados (exporters).

datasources.yaml

apiVersion: 1
datasources:
  - name: VictoriaMetrics
    type: victoriametrics-metrics-datasource
    access: proxy
    url: http://victoria_metrics:8428
    isDefault: true

  - name: VictoriaLogs
    type: victoriametrics-logs-datasource
    access: proxy
    url: http://victoria_logs:9428
    isDefault: false

Precisamos desse arquivo para configurarmos a fontes de informações do grafana, no caso as fontes de métricas e logs que vão ser utilizadas.

docker-compose.yaml

services:
  grafana:
    image: "grafana/grafana:12.3.3"
    volumes:
      - grafana:/var/lib/grafana
      - ./datasources.yaml:/etc/grafana/provisioning/datasources/datasources.yaml:ro
    networks:
      - monitoring 
    ports:
      - 3000:3000
    environment:
      GF_PLUGINS_PREINSTALL: victoriametrics-metrics-datasource,victoriametrics-logs-datasource
      GF_SECURITY_ADMIN_USER: admin
      GF_SECURITY_ADMIN_PASSWORD: admin

  otlp_collector:
    image: "otel/opentelemetry-collector-contrib:0.145.0"
    volumes:
      - ./otel_config.yaml:/etc/otelcol/config.yaml:ro
    command: ["--config=/etc/otelcol/config.yaml"]
    ports:
      - 4317:4317
    networks:
      - monitoring 

  victoria_metrics:
    image: "victoriametrics/victoria-metrics:v1.135.0"
    volumes:
      - metrics:/victoria-metrics-data
    environment:
      storageDataPath: "victoria-metrics-data"
      retentionPeriod: "1d"
    networks:
      - monitoring 

  victoria_logs:
    image: "victoriametrics/victoria-logs:v1.45.0"
    volumes:
      - logs:/victoria-metrics-data
    environment:
      storageDataPath: "victoria-metrics-data"
      retentionPeriod: "1d"
    networks:
      - monitoring 

  jaeger:
    image: "cr.jaegertracing.io/jaegertracing/jaeger:2.15.0" 
    networks:
      - monitoring 
    ports:
      - 16686:16686
    environment:
      MEMORY_MAX_TRACES: 10000

volumes:
  grafana:
  metrics:
  logs:

networks:
  monitoring:

Aqui é onde a brincadeira começa, não acho que vale muito entrar em detalhes porque tudo pode ser achado de uma forma muito melhor explicada que um mero mortal como eu faria, então vou só deixar alguns pontos de atenção.

Logs e métricas vão ser expostas pelo grafana que está na porta 3000, logo entrando em localhost:3000 e colocando as senhas que estão explicitadas no yaml, você terá acesso a eles.
Traces vão estar expostos de forma parecida mas na ferramenta do Jaeger na porta 16686.
O Jaeger foi configurado sem persistência, então ao reiniciar o container os traces ingeridos vão ser perdidos, caso queira uma forma fácil de adicionar persistência pode usar o Badger como Storage Backend.

Arrivederci

Até mais meus caros espero ter sido útil na jornada de subir um oltp localmente.

É isso, caso tenham alguma dúvida ou sugestão basta me avisar. Ficarei feliz em responder!.

Docker Compose - SFTP: Managing files securely

Alexandre Fernandes dos Santos — Sun, 25 Jan 2026 21:29:40 +0000

Good morning everyone! I hope this finds you well. Today I want to share with you almost a version 2.0 of my old article Docker Compose - Server FTP. This text was born from my desire to bring some security improvements and best practice tips.

Don't get me wrong, the previous text has its charm. If you want to spin up a basic and fast FTP server, that's your go-to.

Well, in case you don't know the SFTP protocol (Secure File Transfer Protocol or SSH File Transfer Protocol), it is a network file transfer protocol like FTP, but it uses SSH to encrypt commands and data (during transmission).

Who can, can; who can't, won't

I advise creating a directory with two subdirectories: one for files and another to persist credentials.

sftp
|-- files
|-- creds

To avoid permission problems, we should guarantee the correct access rights to prevent issues when erasing or editing files created by the Docker container.

To do this, I advise finding out which user will be used and adding the directories to that user's group, as well as setting permissions via chmod.

Note: If the user who created the directories is the same one who will execute the docker container, this step might not be necessary, though it is recommended.

For simplicity's sake, I'll assume that the user being used in the shell is the same one running Docker, so let's go!

1 - Discover the current user using whoami:

➜ whoami
alexandre

2 - In my case, the user is alexandre. Now let's check the user's ID:

➜ id
uid=1000(alexandre) gid=1000(alexandre) grupos=1000(alexandre),4(adm),24(cdrom),27(sudo),30(dip),46(plugdev),100(users),116(lpadmin),987(docker)

3 - Do you see the uid value preceding our username in parentheses? The value inside it is what we want. In my case, it's 1000. We'll need this when we create the users with access to SFTP.

4 - Add the necessary directories to the group using the chown command on the folder we are working in, with the user and group in the following format: user:group.

chown -R alexandre:alexandre ./sftp

5 - Adding permissions: the creator of the file and the group can read, edit, and delete data, while others can only execute read operations (774).

chmod 774 -R ./sftp

Creating the users file

The application we are using today allows users to be passed via a file. I think this method is easier to manage than via command line or env vars, so let's create this file.

Just create a file named users.conf and add the user information in the following format username:password:uid. I will explain each field:

username: Can be any username, including your current user (my case).
password: I will leave it blank because we'll use an SSH key to authenticate.
uid: The UID we got in the previous step (if you're in a hurry, try 1000 or 1001).

My users.conf content will look like this:

alexandre::1000

Generating SSH keys

To generate the keys, I will use ssh-keygen, which usually comes installed on Ubuntu.

1 - Enter the creds directory inside /sftp.

2 - Use the command ssh-keygen -t rsa and type the filename. It can be any name; I used key.

3 - After that, it asks if you want to add a passphrase. It's optional. I usually don't set one, remembering that if added, it'll be requested upon every access.

After the Odyssey, Ulysses returns home

Now for the best part. Here is the docker compose of happiness:

services:
  sftp:
    image: atmoz/sftp
    restart: 'unless-stopped' 
    volumes:
        - ./files:/home/alexandre/upload                          # The files will be maintained here
        - ./creds/key.pub:/home/alexandre/.ssh/keys/key.pub:ro    # Sharing keys with the service
        - ./users.conf:/etc/sftp/users.conf:ro                    # Adding users
    ports:
        - 2222:22                                                 # The exposed port will be 2222

And to spin it up, you just need to execute:

docker compose up -d

How to connect

If you want a tip for a client to connect to your freshly created service, I recommend the classic FileZilla. See below how to use it:

1 - Open the Site Manager in the File tab:

2 - Follow the suggested config:

Protocol: SFTP
Host: localhost
Port: 2222 - Normally port 22 is used, but I redirected it to 2222 to avoid conflicts with other ports.
Logon Type: Key file
User: alexandre - Add the user from the users.conf file.
Key file: Use the private key (without .pub) we created in the step [Generating SSH keys].
Background color: It depends on your taste.

3 - Voilá! Now just enjoy making your dubious deployments or keeping your "green steam" files on your favorite SFTP (a father's and mother's love knows no bounds).

That's all, folks!

I hope this text is useful for you. It became a little longer than I expected, but I wanted to explain everything thoroughly (I hope I achieved that 😅).

However, if you have any questions, just leave a comment below and I'll be happy to answer them!

Docker Compose - SFTP gerenciando arquivos com segurança

Alexandre Fernandes dos Santos — Wed, 21 Jan 2026 00:54:13 +0000

Bom dia a todos! Espero que tenha os encontrado bem. Hoje gostaria de compartilhar com vocês quase uma versão 2.0 do meu antigo texto de Docker Compose - Servidor FTP, comigo querendo trazer algumas melhorias de segurança e dicas de boas práticas esse texto surgiu.

Não me entenda mal, o texto anterior ele tem seu charme, se você quer subir um FTP básico e rápido ele é sua pedida.

Bem caso não conheça o protocolo SFTP (Secure File Transfer Protocol ou SSH File Transfer Protocol)ele é um protocolo de transferência de arquivos pela rede como o FTP mas utiliza o SSH para criptografar os comandos e dados (durante a transmissão).

Quem pode, pode, quem não pode não vai estar podendo

Aconselho a criar uma pasta com dois subdiretórios, um de arquivos (files) e outro para persistir as credenciais creds).

sftp
|-- files
|-- creds

E para não termos problemas de permissionamento é bom já garantirmos os acessos a quem deve, para evitarmos problemas ao apagar ou editar arquivos criados pelo container Docker.

Para evitar isso aconselho descobrir o usuário que vai ser utilizado e adicionar as pastas no mesmo grupo deste usuário, além de setar as permissões via chmod.

Obs.: Caso o usuário que criou as pastas seja o mesmo que vai executar o container docker, **provável que esse passo não seja necessário embora seja recomendado**

Por facilidade vou pressupor que o usuário que está sendo utilizado na shell é o mesmo que vai subir o docker, então vamos lá!

1 - Utilizar o comando whoami para descobrir o usuário atual

➜ whoami
alexandre

2 - No meu caso o usuário se chama alexandre agora vamos checar qual o id do usuário

➜ id
uid=1000(alexandre) gid=1000(alexandre) grupos=1000(alexandre),4(adm),24(cdrom),27(sudo),30(dip),46(plugdev),100(users),116(lpadmin),987(docker)

3 - Está vendo o valor de uid que precede o nome do nosso usuário em parenteses? O valor dentro dele que queremos, no meu caso é 1000, vamos precisar disso quando formos criar os usuários com acesso ao SFTP

4 - Adicione as pastas necessárias no grupo, com o comando chown na pasta que estamos trabalhando, com o usuário e grupo no seguinte formato usuario:grupo

chown -R alexandre:alexandre ./sftp

5 - Adicionando as permissões, para quem criou o arquivo e quem está no grupo poder tanto ler, editar e excluir os dados e para o resto poder só executar a leitura (774)

chmod 774 -R ./sftp

Criar o arquivo de usuários

Essa aplicação que vamos utilizar hoje ela permite que os usuários sejam passados via arquivo, eu acho essa forma mais fácil de gerenciar que via comando ou env então bora criar esse arquivo.

Basta criar um arquivo users.conf e adicionar cada informação do usuário no seguinte formato usuario:senha:uid vou explicar cada campo:

usuario: Pode ser qualquer nome de usuario, inclusive o do seu usuário atual (meu caso)
senha: Vou deixar vazio esse campo pois vamos utilizar uma chave SSH para autenticação
uid: O uid que pegamos no ponto passado (caso seja um apressadinho tente 1000 ou 1001).

O conteúdo do meu users.conf ficará desse jeito:

alexandre::1000

Gerando as chaves SSH

Para gerar as chaves eu vou utilizar o ssh-keygen que já vem instalado no ubuntu normalmente.

1 - Entre na pasta creds dentro de /sftp

2 - Utilize o comando ssh-keygen -t rsa e digite o nome do arquivo, pode ser qualquer um eu coloquei key

3 - Após isso ele pergunta se você quer adicionar uma senha, é opcional, eu não costumo adicionar, lembrando que se adicionada ela será pedida em cada acesso

Após a Odisséia Ulisses retorna à casa

Agora é a melhor hora, segue o docker compose da felicidade:

services:
  sftp:
    image: atmoz/sftp
    restart: 'unless-stopped' 
    volumes:
      - ./files:/home/alexandre/upload                          # Os arquivos serão mantidos aqui
      - ./creds/key.pub:/home/alexandre/.ssh/keys/key.pub:ro    # Compartilhando as chaves com o serviço
      - ./users.conf:/etc/sftp/users.conf:ro                    # Adicionando os usuários
    ports:
      - 2222:22                                                 # A porta exposta será a 2222

E para subir tudo basta executar:

Como conectar

Caso queira uma dica de um client para conectar ao seu recém criado serviço eu recomendo o clássico Filezilla, segue abaixo como o utilizar:

1 - Abra o gerenciador de sites na aba _Arquivo

2 - Segue as configurações sugeridas:

Protocolo: SFTP
Host: localhost
Porta: 2222 - Normalmente é a 22 mas redireciono para a 2222, faço isso para evitar conflitos
Tipo de Logon: Arquivo chave
Usuário: alexandre - Adicione o usuário do arquivo users.conf
Arquivo com chave: Aponte para a chave privada (sem o .pub) que criou no passo [Gerando a chave SSH]
Cor de fundo: ai vai do seu gosto

3 - Voilá, agora é só aproveitar para realizar seus deploys duvidosos ou guardar seus arquivos da steam verde no seu SFTP favorito (amor de pai e mãe não tem medida)

Isso é tudo, pessoal!

Espero que tenha sido útil para vocês, ele ficou um pouco mais extenso que do que eu desejava porém quis deixar tudo bem explicado (eu espero que esteja mesmo 😅).

Porém caso tenha dúvidas só me chamar na caixa de comentários que vou estar feliz em responder qualquer pergunta!.

Dockerfile - Node with TypeScript

Alexandre Fernandes dos Santos — Sat, 20 Dec 2025 21:38:01 +0000

Good morning! Hope you’re all doing well. My fellow tech enthusiasts from the land of AI hype still waiting for them to take our jobs so we can finally retire, right? 🙏

But while that doesn't happen, I’d like to share a Dockerfile structure I’ve been working on. Modesty aside, I think the result is pretty solid 😎. In my case, the initial image was around 1GB, and after some tweaks, it dropped to about 161MB (according to Dive)); it’s worth noting this was for a simple app built with [Hono](https://hono.dev/.

**Note:** Keep in mind that your application might not end up the exact same size. It could be larger or smaller depending on your codebase and the dependencies installed in your project.

FROM node:lts-alpine AS builder
WORKDIR /usr/src/app
COPY --chown=node:node package*.json tsconfig.json ./
COPY --chown=node:node /src ./src
RUN npm ci --silent
RUN npm run build
RUN npm ci --silent --omit=dev 

FROM node:lts-alpine AS runner
WORKDIR /usr/src/app
COPY --from=builder /usr/src/app/node_modules ./node_modules
COPY --from=builder /usr/src/app/dist ./dist
USER node
EXPOSE 3000
ENTRYPOINT ["node", "./dist/index.js"]

For those not in a rush

While this Dockerfile covers most use cases, I’ll share some tips on how to use it and explain what happens in each step so you can customize it for your own needs.

Exposing the application

First and most importantly: for your application to be accessible, it must be listening on the correct network interface (remember 0.0.0.0?). You also need to publish the container ports to the host machine. Here is an example command for an app using port 3000, which is the same one defined in the Dockerfile:

docker run image_name:image_tag -p 3000:3000

If you are using Docker Compose, the ports field handles this for you. A basic configuration would look like this:

services:
  node_api:
    build: .
    ports:
      - "3000:3000"

Breaking it down

Now, let's look at the specifics:

1. Multi-stage Build: The first block (the build phase) handles downloading dependencies and compiling the application. Once the code is transpiled, dev dependencies are removed to shrink the final image size.
2. Base Image: I’m using the latest lts-alpine image (it makes keeping this post updated easier 😅). However, a best practice would be to specify both the Node and Alpine versions or use an image hash; this makes your build even more predictable and less prone to breaking changes.
```
 FROM node:24.12.0-alpine3.23 as BUILDER
```
or
```
FROM     node@sha256:c921b97d4b74f51744057454b306b418cf693865e73b8100559189605f6955b8 AS builder
```
3. Security & Execution: In the second stage, I only copy what is strictly necessary for the runtime. I then set the user to node (which comes by default in official images). This is crucial because, if omitted, Docker defaults to the root user, which can create security vulnerabilities.
4. Entrypoint: Finally, I expose port 3000 (adjust to whichever port your app uses) and use the ENTRYPOINT command. Here, I run the transpiled JavaScript directly. Note that you could also use a script defined in your package.json if you prefer.

Goodbye! 👏

That’s it! Thanks for reading. I hope this article was helpful. I’ve looked for many Docker images in the past, but they always seemed too complex or lacked something I needed. While this model might not solve every single case, it serves as a great foundation for using Docker with Node and TypeScript.

Dockerfile - Node com Typescript

Alexandre Fernandes dos Santos — Sat, 20 Dec 2025 18:23:53 +0000

Bom dia, tudo bem? Espero que sim! Meus caros conterrâneos da terra do hype em Inteligência Artificial sigo no aguardo esperançoso de que elas tirem nossos trabalhos 🙏.

Mas, enquanto isso não acontece, gostaria de compartilhar uma estrutura de Dockerfile que criei durante alguns estudos. E não querendo faltar com humildade, acredito que o resultado ficou muito bom 😎.

No meu caso, a imagem inicial tinha cerca de 1GB e após alguns ajustes ficou com cerca de 161MB (segundo o Dive), vale ressaltar que é uma app
simples feita em Hono.

**Observação:** Lembrando que isso não quer dizer que sua aplicação terá esse mesmo tamanho, pode ficar maior ou menor, isso vai depender do tamanho da base de código e das dependências instaladas no projeto.

FROM node:lts-alpine AS builder
WORKDIR /usr/src/app
COPY --chown=node:node package*.json tsconfig.json ./
COPY --chown=node:node /src ./src
RUN npm ci --silent
RUN npm run build
RUN npm ci --silent --omit=dev 

FROM node:lts-alpine AS runner
WORKDIR /usr/src/app
COPY --from=builder /usr/src/app/node_modules ./node_modules
COPY --from=builder /usr/src/app/dist ./dist
USER node
EXPOSE 3000
ENTRYPOINT ["node", "./dist/index.js"]

Para quem não está com pressa

Embora esse Dockerfile contemple muitos casos, vou passar algumas dicas de como usar e explicar um pouco melhor o que fiz em cada passo para que você possa customizar e poder rodar sua aplicação da melhor forma possível!

Expor a aplicação

Primeiro e mais importante para sua aplicação ser exposta, além dela estar aceitando requisições externas (lembra do 0.0.0.0?), é preciso também publicar as portas do container para a máquina que está executando a imagem.

Segue comando de exemplo para uma aplicação que utiliza a porta 3000, que é a mesma definida no Dockerfile:

docker run nome_da_imagem:tag_da_imagem -p 3000:3000

Caso esteja utilizando Docker Compose, o campo ports já se encarrega disso. Um manifesto básico para essa aplicação seria algo como:

services:
  node_api:
    build: .
    ports:
      - 3000:3000

Trocando em miúdos

Agora gostaria de explicar de forma mais detalhada o que estou fazendo.

1. Build Multistage: O primeiro bloco que seria a fase de build se encarrega de além de baixar as dependências realizar o build da aplicação. Inclusive após gerar o código transpilado, as dependências de desenvolvimento são removidas para diminuir o tamanho final da imagem.
2. Imagem Base: Aqui vale um ponto de atenção pois estou utilizando a última imagem do Node e do Alpine disponibilizada (fica mais fácil manter o texto atualizado dessa forma😅).

Porém uma melhor prática seria especificar tanto a versão do Node quanto a do Alpine ou utilizar a hash da imagem dessa forma teríamos uma imagem ainda menos passível de alterações no comportamento.
```
FROM node:24.12.0-alpine3.23 as BUILDER
```
ou
```
FROM node@sha256:c921b97d4b74f51744057454b306b418cf693865e73b8100559189605f6955b8 AS builder
```
3. Segurança e Execução: Na segunda parte, só realizei a cópia do que é estritamente necessário para a execução da aplicação. Após isso, determino que o usuário node (que já vem por padrão nas imagens oficiais) seja utilizado. Isso é importante, pois, caso não seja feito, o usuário root será utilizado e isso pode deixar brechas de segurança na imagem.
4. Entrypoint: E então finalmente exponho a porta 3000 que é a utilizada pela minha aplicação não deixe de colocar a que sua aplicação está utilizando e utilizo o comando ENTRYPOINT.
Aqui executo o JavaScript transpilado na camada anterior de forma direta, mas um comando explicitado no package.json também poderia estar sendo utilizado.

Tchau 👏

Então é isso, obrigado pela leitura! Espero que esse artigo tenha sido de alguma ajuda.

Eu já pesquisei algumas imagens mas sempre pareciam um pouco complexas demais ou faltava algo que eu precisava. Dessa forma, acho que este modelo não resolve todos os casos, mas serve como uma boa base para utilizar Docker em conjunto com Node e Typescript.

🧩 Automated Documentation using MkDocs and Python

Alexandre Fernandes dos Santos — Mon, 27 Oct 2025 21:39:11 +0000

Something I really enjoy is browsing through library documentation — honestly, good documentation is something I find beautiful to see and also difficult to maintain 😅.

Now imagine: every time a change is made to a behavior, having to go to the page that explains it, copy and paste the code, write what changed, run the build, check if everything is correct... wait, that's not how it should be! — I'm already tired just thinking about it 😤.

🐛 Tool to be documented

I created a very simple tool that makes a call to the PokeAPI, fetches information about a Pokémon, and displays the result in the terminal.

The source code can be found here: Automated Documentation

Talking a bit more about the project: I used Poetry to manage the virtual environment and keep the libraries isolated from the rest of the system (nobody wants to clutter their PC with libs, right?).
But you can use any other tool, like pyenv or virtualenvwrapper — it doesn't matter.

The installed libraries are listed in pyproject.toml, so just install them and start playing.

📝 How to document

This is a small piece of the code I'll use as an example.
You must have noticed those """ — they are Docstrings, used to document code. It's a very common convention for documenting modules, classes, functions... well, anything.
If you're going to document something, I highly recommend using docstrings 😜.

These docstrings are what make the magic happen: we'll make them be automatically read and inserted into the corresponding documentation pages.
With the docstrings ready and explaining what each function does, we can proceed.

⬆️ Installing MkDocs

To install using Poetry it's very simple — just use poetry add, or pip install if you're not using it.

Note: When installing mkdocstrings, replace [python] with the language you're using.
Check the official documentation to verify support: Mkdocstrings Docs.

We installed MkDocs, a nice theme called mkdocs-material (a matter of taste, but I really like it 😄), and finally mkdocstrings, a plugin that scans the project and inserts the docstrings into the corresponding pages.

So now? What do we do with all this? 🤔 Don't worry, you don't need to send a letter to a TV show — it's much simpler than that 😂.
Following the step-by-step below, your documentation will be ready in no time:

Step 1️⃣

Open a terminal inside the project folder and use the command:

mkdocs new .

This will create the configuration files and the docs folder.

Step 2️⃣

Now you should have a file called mkdocs.yml in the project root.
In it, add the following configurations:

    site_name: Automated Documentation # You can use your application's name

    theme:
        name: material # Adds the nice theme

        plugins:
        - search # Plugin that enables search in the documentation
        - mkdocstrings: # This one makes the magic happen!
            default_handler: python

Note: Yeah, the code looks a bit ugly, but this way you can just copy and paste — my laziness salutes yours 🙏

The mkdocstrings plugin is responsible for reading the docstrings and automatically adding them to the corresponding pages.

Step 3️⃣

Run the commands:

mkdocs build
mkdocs serve

Then, access the documentation through your browser at:
👉 http://127.0.0.1:8000/

You'll see something similar to the image below:

Step 4️⃣

When you access it, you'll see an introduction explaining how to add pages — it's very simple!
Just create a .md file inside the docs folder in the project root, and it will be automatically added to the documentation structure.

Your structure should look similar to this:

Step 5️⃣

Now let's go to the pokemon page, used to document the pokemon module we saw at the beginning.

In the page content, we have a brief introduction and then something like:

::: src.pokemon

But what is this?
This command maps the module to be automatically documented — the path is the same one used in the import.
Don't believe it works? Take a look at the result:

Step 6️⃣

Enjoy! 😁

🎉 The End

In just a few steps, we already have pretty nice documentation!
If you add new modules or want to create more pages, just include the file inside the docs folder, and you're done.

I hope you enjoyed it!
And if you have any questions (or found any errors — it happens to the best of us 😅), just leave a comment below!

Building an Organized API in Golang Using Fiber

Alexandre Fernandes dos Santos — Mon, 27 Oct 2025 21:33:03 +0000

After spending some time exploring Go and struggling a bit with its package system (here I must admit it's actually a great system when used properly), I found myself thinking a lot about the best way to organize the study API I was building.

I gathered many examples, including from the Fiber repository, and arrived at a structure that I find quite readable and easy to extend with new features.

Disclaimer: I'm not saying this is the best way to organize a Go API, but it worked for my needs and I believe it can be useful in many cases where a generic API is required.

What Does This API Do?

Repository Link

This API was created to store information about books and has only three endpoints:

GET: Returns information about a book
PUT: Adds or updates information about a book
DELETE: Deletes book information

I implemented just the basics, using the Fiber framework which has an approach similar to Express.js that I really liked, combined with Go's advantages like lower memory allocation and incredible speed. The data is stored in Redis, which can be initialized using a docker-compose file.

Structure

| api_simples
├── docker-compose.yml
├── docs
│   └── estrutura.png
├── go.mod
├── go.sum
├── main.go
├── pkg
│   ├── configurations
│   │   └── database.go
│   ├── entities
│   │   └── book.go
│   ├── handlers
│   │   └── book_handler.go
│   ├── repositories
│   │   ├── book_repository.go
│   │   └── commons.go
│   └── routes
│       ├── book_router.go
│       └── routes.go
└── README.md

I believe it's more valuable to explain the reasoning behind this organization rather than just listing what each folder contains. I won't follow the exact order above since I think it's clearer to explain in a different sequence:

go.mod


module github.com/XandeCoding/codigos-de-artigos/golang/api_simples

go 1.19

require (
    github.com/go-redis/redis/v9 v9.0.0-beta.2
    github.com/gofiber/fiber/v2 v2.36.0

This file helps resolve various Go workspace issues, allowing me to create a Go repository anywhere without problems accessing external or local packages.

To create it, I ran the go mod init command with the GitHub project path as argument (github.com/XandeCoding/codigos-de-artigos/golang/api_simples). While it's not strictly necessary to use the full GitHub path (the project name api_simples would work), I chose to include it since this is a public project. This makes it easier to reference specific files from the project.

pkg and main.go

The pkg folder contains the main API code where all features are implemented. The main.go file is only used to initialize the application and contains no implementation logic, serving solely to start the API.

main.go:


package main

import (
    "github.com/XandeCoding/codigos-de-artigos/golang/api_simples/pkg/routes"
    "github.com/gofiber/fiber/v2"
)

func main() {
    app := fiber.New()
    routes.AddRoutes(app)

    app.Listen(":3000")
}

pkg/configurations

This contains configuration files. In this case, database.go configures database access. If we had other application or tool configurations used by one or more parts of the application, they would also go here - such as custom Fiber configurations or environment variables.

Example Redis connection configuration in database.go:


package configurations

import "github.com/go-redis/redis/v9"

func CreateClient() *redis.Client {
    redisDatabase := redis.NewClient(&redis.Options{
        Addr: "localhost:6379",
        Password: "",
        DB: 0,
    })

    return redisDatabase
}

pkg/entities

Entities can be used in various places, particularly in this case where I use them both for receiving data in endpoints and for database operations. Placing them in a common location is quite useful, though in feature-separated package structures, this approach might not be as ideal.
pkg/repositories

This package contains functions that work directly with the Redis database. They receive the book entity and have functions that insert, update, and delete it from the database. If there were another entity to handle, such as library, it would be in a separate file containing only functions related to that data.

Fragment from book_repository.go:


type Repository struct {
    database *redis.Client
}

...

func (rdb Repository) GetBook(name string) string {
    ctx, cancel := getContext()
    defer cancel()
    book, _ := rdb.database.Get(ctx, name).Result()

    return book
}

pkg/routes

Following the example of other parts of the application, I separated routes into different files. Even though we have a routes.go file that initializes these routes, it's helpful to keep routes for specific resources separate for better readability and understanding for others who might maintain the code.

Route initialization in routes.go:


func AddRoutes(app *fiber.App) *fiber.App {
    bookRouter(app)

    return app
}

In book_router.go, I only specify the routes, methods, and handler functions located in another part of the application. Another important aspect is that this structure allows us to create instances that can be reused across all endpoints for this specific resource - in this case, a Redis database connection instance.

Fragment from book_router.go:


func bookRouter(app *fiber.App) *fiber.App {
    bookRepository := repositories.NewRepository()

    app.Get("/book/:name", handlers.GetBookHandler(bookRepository))
    app.Put("/book", handlers.SetBookHandler(bookRepository))
    app.Delete("/book/:name", handlers.DeleteBookHandler(bookRepository))

    return app
}

pkg/handlers

In handlers, I place the functions called by the endpoints. For example, the PUT /book endpoint calls the SetBookHandler function in book_handler.go, which returns the function to be executed when this resource is accessed.

Code for the SetBookHandler function:


func SetBookHandler(bookRepository *repositories.Repository) fiber.Handler {
    return func(c *fiber.Ctx) error {
        book := new(entities.Book)
        err := c.BodyParser(book)

        if err != nil {
            message := map[string]string{"message": "Invalid entry data"}
            return c.Status(400).JSON(message)
        }

        book_name_normalized := strings.ReplaceAll(
            strings.ToLower(book.Name), " ", "_",
        )
        key := "book:" + book_name_normalized
        bookRepository.SetBook(key, book)
        return c.Send(c.Body())
    }
}

That's It!

I hope this helps with some of the initial challenges when building an API, especially in a language we're not very familiar with. This initial structure worked well for me, but any comments or feedback are always welcome for continuous improvement. Until next time! 👋

Docker Compose - Simple Kafka

Alexandre Fernandes dos Santos — Mon, 27 Oct 2025 21:30:16 +0000

Hey folks! How’s it going? 😄

I’m here to share a simple script I learned while working on a college project using Kafka and Python. Maybe later I’ll make another post showing how I connected everything and created the consumers and producers in Python.

The goal is to keep the setup as simple as possible, since most of the examples I found were a bit complex and included tools I didn’t actually need.

In this final version, I only kept Zookeeper (used by Kafka to coordinate services), Kafka itself, and a dashboard to easily visualize what’s going on — which helps a lot!

You can access the dashboard through your browser at localhost:8080.

🐳 Docker Compose

version: '3'
services:
  zookeeper:
      image: confluentinc/cp-zookeeper:latest
          environment:
                ZOOKEEPER_CLIENT_PORT: 2181
                      ZOOKEEPER_TICK_TIME: 2000
                          ports:
                                - 2181:2181

                                    kafka:
                                        image: confluentinc/cp-kafka:latest
                                            depends_on:
                                                  - zookeeper
                                                      ports:
                                                            - 29092:29092
                                                                environment:
                                                                      KAFKA_BROKER_ID: 1
                                                                            KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
                                                                                  KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092,PLAINTEXT_HOST://localhost:29092
                                                                                        KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT
                                                                                              KAFKA_INTER_BROKER_LISTENER_NAME: PLAINTEXT
                                                                                                    KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1

                                                                                                      kafka-ui:
                                                                                                          image: provectuslabs/kafka-ui
                                                                                                              container_name: kafka-ui
                                                                                                                  ports:
                                                                                                                        - "8080:8080"
                                                                                                                            restart: always
                                                                                                                                environment:
                                                                                                                                      - KAFKA_CLUSTERS_0_NAME=local
                                                                                                                                            - KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS=kafka:9092
                                                                                                                                                  - KAFKA_CLUSTERS_0_ZOOKEEPER=zookeeper:2181

🧭 A Few Notes ❗

The Kafka service is exposed on port 29092, so when connecting, use localhost:29092.
If you make any changes, check that all services are still connected properly. For example: if you change Kafka’s port, you’ll also need to update it in both kafka-ui and zookeeper.

And that’s all for today, folks! See you next time! 👋

🥖 Bun e Node – Será que o pãozinho tem chance?

Alexandre Fernandes dos Santos — Thu, 07 Aug 2025 22:13:15 +0000

Bem-vindos, meus companheiros marginalizados, insultados e que passam por vexames apenas por usar JavaScript no backend (e jogar no bicho às sextas — com fé vem coelho dessa vez 🙏).

Como muitos têm acompanhado, nosso ecossistema vem crescendo bastante, não só com novas bibliotecas e funcionalidades, mas também com novas runtimes para executar código JavaScript no backend — seja para realizar consultas em bancos, fornecer dados via API REST, entregar arquivos estáticos ou outras aplicações.

Mas queria me aprofundar mais no contexto de runtimes neste momento. Assim como os dinossauros do Jurassic Park 🦖 evoluíram, começaram a se reproduzir e formar belas famílias devoradoras de pessoas, as runtimes também evoluíram. Hoje temos três pesos pesados no ringue nosso amado Node.js, o Deno (que inclusive é do mesmo criador — o que o ressentimento pela ex não faz, hein? 😅), e o Bun.

Como já brinquei um pouco com o famoso Deno neste artigo sobre páginas estáticas, agora chegou a vez de testar o Bun.

⏪ Um breve resumo dos últimos episódios

O Node.js foi lançado em 2009 e possibilitou utilizar JavaScript no backend. Desde então, tem crescido em popularidade. Acredito que isso se deve ao fato de ser uma linguagem de fácil adaptação, até mesmo para quem não tem muita intimidade com programação. Também pesa a sua forte presença no frontend e a acessibilidade direta pelo navegador — para muitos, foi a primeira linguagem com a qual tiveram contato.

E tudo isso com uma performance admirável, graças à V8, a engine do Chrome ⚙️. Que sempre foi um navegador perfomático, e usar a mesma engine para rodar código no servidor foi um golaço. Estamos há mais de uma década criando bugs e queries mal otimizadas em JavaScript. 🫠

Mas nada é perfeito. Mesmo sendo mantido por engenheiros e engenheiras muito talentosos, o Node.js começou a enfrentar alternativas — e uma delas é o Bun, que é o foco deste texto.

🍔 O que é o Bun? (É de comer? Às vezes, sim)

Para começar: o Bun é uma runtime feita do zero com uma linguagem recente chamada Zig, pensada com foco em segurança e performance.

O objetivo do Bun é entregar performance e uma API padrão que ajude na produtividade. O package manager que o acompanha funciona muito bem, inclusive.

Diferente do Node.js e do Deno, o Bun utiliza a engine do Safari para rodar o JavaScript — famosa por sua velocidade, mas também conhecida por ser mais difícil de se desenvolver para ela. Um ponto muito positivo é o suporte nativo ao TypeScript (sim, eu sou um junkie por tipos, me julgue 😅 — mas se eu for concatenar uma string com um objeto, quero saber conscientemente que estou fazendo uma cachorrada).

📌 Obs.: O Node.js tem melhorado muito o suporte a TypeScript, mas algumas funcionalidades ainda estão em fase experimental 🧪.

🧪 O que dá pra fazer com o Bun?

Agora que já contei muita lorota 😄, queria mostrar um humilde benchmark que fiz para testar o brinquedo. Nele, foi feita a leitura de um arquivo JSON, que depois era parseado e respondido numa requisição. Simples assim:

📊 Obs.:

Benchmark realizado em um i7-1255U com 8GB de memória

Low Load: 125 conexões e 100.000 requisições

Medium Load: 1.000 conexões e 100.000 requisições

Heavy Load: 10.000 conexões e 1.000.000 requisições

Os testes foram feitos com o bombardier. Aqui está o repositório com os testes: bun-e-node

Também recomendo um benchmark mais completo e profissional: Deno vs. Node.js vs. Bun: Performance Comparison 2025

Analisando com cuidado, vemos algumas qualidades e defeitos também:

⚡ Velocidade – Realmente entregou uma performance superior. No último teste de carga intensa, teve média de 300.96ms, enquanto o Node respondia em 1000.42ms — cerca de 3x mais rápido.
🧠 Recursos – Aqui surgem controvérsias. No primeiro teste, o Bun consumiu menos memória e CPU. No segundo, porém, teve um pico de 1.51 GiB de memória! Isso já foi corrigido na issue #17063, mas é um risco a ser considerado para quem quer ser early adopter 🧪.

💭 Considerações

Embora os benchmarks sejam empolgantes, nem tudo são flores no dia a dia. Nos meus testes, por exemplo, usar o roteador padrão do Bun trouxe um overhead muito maior do que implementar algo manualmente. A diferença foi tão grande que achei que havia um bug no código.

Apesar de ter sido feito do zero, com base nos aprendizados das outras runtimes e com forte foco em performance, o Bun ainda não tem a bagagem do Node.js. São mais de 10 anos de história e uma comunidade gigantesca.

Isso faz muita diferença. Caso surja um problema no Node.js, é bem provável que alguém já tenha passado por isso e compartilhado uma solução. Sem contar que muitas bibliotecas são construídas com o Node como base.

Portanto, se estiver pensando em fazer uma troca, analise bem: sua aplicação realmente vai ganhar algo com isso? Porque dificilmente ela vai se comportar exatamente igual — para o bem ou para o mal.

✅ Conclusão

É isso! Espero ter dado uma visão panorâmica sobre essas duas runtimes. O ecossistema de Backend com JavaScript está em plena expansão, e isso é ótimo para nós devs. A cada dia surgem ferramentas mais modernas, estáveis e interessantes, disputando espaço com os irmãos mais velhos 🧓.

Spinning Up PostgreSQL with Docker Compose + Dashboard

Alexandre Fernandes dos Santos — Mon, 21 Apr 2025 15:26:09 +0000

Hello, database lovers! (I know that doesn’t really exist, but hey — I'm trying to break the ice here 🫠)

I want to share a script to spin up PostgreSQL using docker-compose, which can be useful for anyone
looking for something really simple: just get it running, with a pretty dashboard to visualize data and run some queries too.

Without further ado, let’s get to the code:

services:
  database_postgres:    
    image: postgres:latest
    ports:
      - 5432:5432
    environment:
      POSTGRES_PASSWORD: password
      POSTGRES_USER: username
      POSTGRES_DB: database_name 
    volumes:
      - ${HOME}/postgres-data/:/var/lib/postgresql/data    

  pgweb:
    container_name: pgweb
    restart: always
    image: sosedoff/pgweb
    ports:
      - 8081:8081
    links:
      - database_postgres:database_postgres
    environment:
      - PGWEB_DATABASE_URL=postgres://username:password@database_postgres:5432/database_name?sslmode=disable
    depends_on:
      - database_postgres

🛠 Explaining in Detail

`database_postgres`

Nothing new under the sun here. Just some variables to initialize the database with a user.

But the trick is in the volumes:

Here we make sure the data is saved in a directory inside your HOME,

so all database data will persist there.

👉 This way, if you run docker-compose down (or docker compose down, depending on your version),

you won’t lose your data.

It's not ideal for production, but it can help you in a lot of cases! 😂

`pgweb` (Dashboard)

We’ve got two cool things here:

The connection URL is passed via environment variable, which is super convenient.
links creates a connection between the services — it defines an alias, allowing the pgweb container to access the database_postgres by name.

Also, depends_on ensures that the database starts before the dashboard,

which helps prevent connection issues.

🚀 Running Everything

After running a simple:

docker-compose up

You can access your dashboard in the browser at:

http://localhost:8081/

There you can run queries or just visualize your data — all right in your browser,

no need to install anything else.

✌️ That’s it!

I hope you found this article useful.

If you have any questions, feel free to reach out in the comments 🤙

Docker Compose - FTP Server

Alexandre Fernandes dos Santos — Wed, 16 Apr 2025 15:03:50 +0000

Hello everyone! I'm here to share another docker-compose script I put together to save some files at home,
using an old PC I had lying around.

So, if you've got a little unused PC and want to use it for backups or to store files —
without filling up the disk on your main computer or relying on the internet — I think this could be a great option!

I used ProFTPD, which was the easiest and simplest FTP service I found.

I also tested vsftpd, but I found it a bit more complex to set up.

services:
  ftp-container:
    image: kibatic/proftpd
    network_mode: host
    restart: always
    environment:
      FTP_LIST: "username:password"
      USERADD_OPTIONS: "-o --gid 33 --uid 33"
    volumes:
      - "./files:/home/data"

Now I'll explain some of the configurations you might want to tweak for your own setup:

network_mode — This option makes the container use the same network as the host machine
(the PC running the FTP server).
That way, the service becomes visible on your local network — so you can access it from your phone or any other device connected to the same network.
FTP_LIST — Here you set the username and password in the format username:password.
You can add more users by separating them with ;.
```
Note: The password cannot contain special characters.
```
USERADD_OPTIONS — Sets the group and default user inside the container.
With this setup, it can create and read files normally.
volumes — The first path (./files) is the folder on your computer that will be shared with the FTP.
That’s where your files will be saved. I recommend creating an empty folder named files in the same directory as the script.
The second path (/home/data) is the directory inside the container — this name can be anything you like.
The important part is making sure the first path is correct.

That's it! Hope it helps. If you have any questions, feel free to reach out. See you next time! 👋

DEV Community: Alexandre Fernandes dos Santos

Docker Compose - Observability made easy

Show me the code

otel_config.yaml

datasources.yaml

docker-compose.yaml

Arrivederci

Docker Compose - Stack de Observabilidade sem complicação

Show me the code

otel_config.yaml

datasources.yaml

docker-compose.yaml

Arrivederci

Docker Compose - SFTP: Managing files securely

Who can, can; who can't, won't

Creating the users file

Generating SSH keys

After the Odyssey, Ulysses returns home

How to connect

That's all, folks!

Docker Compose - SFTP gerenciando arquivos com segurança

Quem pode, pode, quem não pode não vai estar podendo

Criar o arquivo de usuários

Gerando as chaves SSH

Após a Odisséia Ulisses retorna à casa

Como conectar

Isso é tudo, pessoal!

Dockerfile - Node with TypeScript

For those not in a rush

Exposing the application

Breaking it down

Goodbye! 👏

Dockerfile - Node com Typescript

Para quem não está com pressa

Expor a aplicação

Trocando em miúdos

Tchau 👏

🧩 Automated Documentation using MkDocs and Python

🐛 Tool to be documented

📝 How to document

⬆️ Installing MkDocs

Step 1️⃣

Step 2️⃣

Step 3️⃣

Step 4️⃣

Step 5️⃣

Step 6️⃣

🎉 The End

Building an Organized API in Golang Using Fiber

What Does This API Do?

Structure

go.mod

pkg and main.go

pkg/configurations

pkg/entities

pkg/routes

pkg/handlers

That's It!

Docker Compose - Simple Kafka

🐳 Docker Compose

🧭 A Few Notes ❗

🥖 Bun e Node – Será que o pãozinho tem chance?

⏪ Um breve resumo dos últimos episódios

🍔 O que é o Bun? (É de comer? Às vezes, sim)

🧪 O que dá pra fazer com o Bun?

💭 Considerações

✅ Conclusão

Spinning Up PostgreSQL with Docker Compose + Dashboard

🛠 Explaining in Detail

database_postgres

pgweb (Dashboard)

🚀 Running Everything

✌️ That’s it!

Docker Compose - FTP Server

`database_postgres`

`pgweb` (Dashboard)