• Algoritmos de Matching
• Arquitetura do Software
• Backend do CaronaShow
• Cronograma
• Entradas e saídas do algorimo
• Escolha da biblioteca de interface
• Grupo no Zotero
• Interface do CaronaShow
• Kubernetes
• Levantamento de dados para hipótese
• Many to one
• One to many
• Oracle ARM64 Ubuntu 24.04 quirks for K3s
• Pesquisas
• Requisitos
• Revisão bibliográfica - Como vamos proceder
• Setup Flux Operator em Produção
• Setup K3d + FluxCD + Git genérico
• Setup K3s + FluxCD + GitLab
• Setup secrets (Flux + sops + age)
• Sistema de Ranks dos Motoristas

---

O backend do CaronaShow é baseado na arquitetura de microsserviços e desenhada para executar em um cluster Kubernetes.
Também seguimos os conceitos de Twelve Factor Apps.

Entradas do algoritmo

Dados dos usuários

• Origem e destino da viagem (OD pair)

• Janela de horário de saída

• Janela de horário de chegada

• Número de passageiros

• Quantidade de bagagens

• Preferências/restrições de viagem

Dados espaciais e de rota

• Coordenadas geográficas

• Vetores de direção das rotas

• Similaridade entre trajetos

• Distâncias entre pontos

• Taxa máxima aceitável de desvio (detour)

Dados operacionais

• Capacidade dos veículos

• Quantidade disponível de veículos

• Velocidade média estimada

• Tempo médio de embarque/desembarque

• Custos operacionais por distância

Parâmetros do algoritmo

• Limiar de similaridade de rota

• Número máximo de iterações

• Parâmetros do ALNS (Adaptive Large Neighborhood Search)

• Fatores de otimização

Saídas do algoritmo

Resultado do pareamento

• Grupos de usuários compatíveis para carona

• Associação usuário ↔ veículo

Rotas otimizadas

• Sequência de embarque/desembarque

• Trajeto compartilhado final

• Distância total percorrida

Métricas operacionais

• Número de veículos necessários

• Quilometragem total economizada

• Taxa de sucesso dos pareamentos

• Tempo médio de espera

• Taxa média de desvio da rota

Métricas de sustentabilidade

• Redução estimada de emissões de CO₂

• Redução de veículos em circulação

• Taxa de ocupação média dos veículos

A decisão também foi influenciada por reflexões apresentadas por Theo Browne, nesse vídeo, que discute diferentes abordagens de estilização e bibliotecas de UI no ecossistema React.

Com base nas ideias apresentadas no vídeo, concluiu-se que abordagens que dão maior controle direto sobre os componentes da interface — como o shadcn/ui — tendem a favorecer manutenção, escalabilidade e personalização da aplicação. Essa característica foi considerada particularmente relevante para o desenvolvimento do CaronaShow.

https://www.zotero.org/groups/6458720/caronashow/library

Existem duas coleções:

1. "Tudo": para guardar qualquer tipo de referência que seja minimamente relevante, tenha sido lido ou não por algum de nós

2. "Selecionado": para guardar uma referência relevante que foi minimamente lida (abstrato, introdução e conclusão ao mínimo).

Todas as referências que existem em "Selecionado" existem também em "Tudo"

Paleta de cores: https://tweakcn.com/themes/cmn0zcoz0000004ju2p8eg89i

Executive Summary

We reviewed the literature on carpooling/ride-sharing and its impacts on vehicle counts and CO₂ emissions. A high-level synthesis is as follows:

• Global modeling: The IPCC (AR6 WG3) reports that shifting 20% of solo car trips into carpools can cut transport GHGs by ~12%【43†L840-L843】. In the same report, carpooling is said to reduce vehicle‐km by ~11% and emissions by ~12% compared to an all-solo baseline【44†L1253-L1260】.

• Simulation studies: A recent simulation for on-demand ride-share in Beijing found that optimized carpooling/dispatch could cut fleet size by ~25.3% and pollutant emissions by ~21.7%【7†L83-L90】. This represents an upper bound under intensive ride-sharing.

• Empirical programs: In practice, corporate carpool programs can yield large relative benefits. For example, an Italian corporate ridesharing network (Jojob, 2025) reported that 641,390 shared trips in one year saved 9.66 million km and removed 367,192 private cars from roads. This implies roughly a 57% reduction in vehicles for those trips (with 1,256 tCO₂ avoided)【63†L109-L117】. In contrast, a one-month pilot at a Brazilian company (Localiza, 2017) saw 660 shared rides result in 211 fewer cars on the road (~32% fewer cars) and ~2.28 tCO₂ saved【61†L103-L107】.

• Other findings: Long-distance carpooling (BlaBlaCar in Europe) shows doubling of passenger-km traveled per vehicle and about a 26% direct CO₂ reduction vs. the alternative modes【10†L95-L103】. Smaller corporate pilots (e.g. SLC Máquinas, Brazil) report a few tonnes of CO₂ saved in early stages【64†L135-L140】.

In summary, multiple sources suggest moderate percent reductions at plausible adoption levels. The evidence supports assuming on the order of 10–20% fewer vehicles and ~10–15% lower CO₂ when ~20% of commutes become carpools. We propose using ≈12% CO₂ reduction (range ~8–15%) and roughly 10% fewer vehicles (range ~5–20%) as a conservative operational hypothesis. These figures align with (a) IPCC’s 12% CO₂ figure at 20% adoption【43†L840-L843】 and (b) mid-range values from empirical programs and simulations【7†L83-L90】【63†L109-L117】.

The recommendation: Use ~12% CO₂ reduction (10% as a floor, 15% as a ceiling) and ~10% vehicle reduction (5–20% range) for 20% carpool adoption. This accounts for uncertainty and variability in contexts, and is backed by the cited studies below.

Key Studies Comparison

Notes: All studies vary in context. The IPCC figure is scenario-based (global fleet). The Nature study and corporate surveys reflect intensive shared-ride usage. Real-world corporate cases (Italy, Brazil) show large percentage cuts among participants but on small absolute scales (hundreds to thousands of trips). Overall, sources cluster around a ~10–25% range of reductions for moderate carpool uptake.

Recommended Hypothesis

Based on these results, we recommend assuming ~12% CO₂ reduction from baseline commuting and about 10% fewer vehicles in use, under a 20% adoption of carpooling. As a plausible range, use roughly 8–15% CO₂ and 5–20% vehicle reductions. This aligns with the IPCC’s 12% estimate for 20% uptake【43†L840-L843】, while allowing for higher gains seen in some pilots【7†L83-L90】【63†L109-L117】 and lower gains if uptake is weaker. In practice, factors like trip length, baseline occupancy, and overall demand could push effects toward either end of these ranges.

Given data from diverse sources, the midpoint (12% CO₂, ~10% vehicles) is justified by the IPCC guidance and recent evidence【43†L840-L843】【7†L83-L90】. The extended ranges reflect the best (≈20% reductions in trials) and worst (only ~5% if uptake limited) cases observed. These values should be used in the TCC as the operational hypothesis (point estimate ± range) for 20% carpool participation.

flowchart LR
    IPCC["IPCC AR6 (2022):\n20% carpool → ~12% GHG drop【43†L840-L843】"] 
    Chang["Chang et al. (2024):\nBeijing ride-share → 21.7% CO₂↓, 25.3% cars↓【7†L83-L90】"]
    Jojob["Jojob (2025):\nItaly corp ride-share (641k trips) → 367k cars↓ (57%)【63†L109-L117】"]
    Localiza["Localiza (2017):\nPilot (660 rides) → 211 cars↓ (32%), 2.276 tCO₂↓【61†L103-L107】"]
    Hypothesis["**Recommended:** ~12% CO₂↓ (range 8–15%), ~10% cars↓ (5–20%)"]

    IPCC --> Hypothesis
    Chang --> Hypothesis
    Jojob --> Hypothesis
    Localiza --> Hypothesis

Prioritized Sources

1. IPCC AR6 WG3, Chapter 10 (2022) – Global transport decarbonization scenarios【43†L840-L843】.

2. Chang et al., npj Sustainable Mobility 2024 – Real-world ridesourcing (Beijing) simulation【7†L83-L90】.

3. Jojob Real Time Carpooling Observatory 2025 – Italy corporate carpooling data【63†L109-L117】.

4. Travel3 news (2017) – Localiza corporate carpool pilot (Belo Horizonte, Brazil)【61†L103-L107】.

5. Prêmio ECO (2024) – SLC Máquinas corporate carpool program (Brazil)【64†L135-L140】.

6. BlaBlaCar “Zero Empty Seats” study (2019) – European long-distance carpooling (via Adigital)【10†L95-L103】.

Further reading includes systematic reviews of shared mobility environmental impacts【17†L430-L442】 and Project Drawdown’s analysis of carpooling. These substantiate the above figures and helped set the recommended ranges.

Changes

These were the changes made to each instance:

1. Remove iptables rules

# Apply live
sudo iptables -D FORWARD -j REJECT --reject-with icmp-host-prohibited 2>/dev/null
sudo iptables-legacy -D FORWARD -j REJECT --reject-with icmp-host-prohibited 2>/dev/null

# Persist changes
sudo vim /etc/iptables/rules.v4

# COMMENT OUT OR DELETE:
# -A INPUT -j REJECT --reject-with icmp-host-prohibited
# COMMENT OUT OR DELETE:
# -A FORWARD -j REJECT --reject-with icmp-host-prohibited

2. Increase limits via sysctl

# Apply live
sudo sysctl fs.inotify.max_user_watches=524288
sudo sysctl fs.inotify.max_user_instances=512

# Persist changes
echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.d/99-kubernetes.conf
echo "fs.inotify.max_user_instances=512" | sudo tee -a /etc/sysctl.d/99-kubernetes.conf
sudo sysctl --system

3. Use legacy iptables backend

update-alternatives --set iptables /usr/sbin/iptables-legacy
update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy

Additional notes

• Do NOT run Docker alongside K3s.

• Do NOT use ufw / firewalld or any other firewall.

https://excalidraw.com/#room=5756f3abce0bb2e5170e,LP0nodguJIl6PmlIO5E8dg

Planilha para anotações das referências selecionadas: https://cloud.zerowhy.org/f/1330488

Explicação dos campos da planilha:

Zotero para fazer as referências (em nossa biblioteca compartilhada aqui)

Armazenar PDFs aqui: https://cloud.zerowhy.org/f/1331338

Fontes de pesquisa

• Google Scholar

• IEEE Xplore

• ResearchGate

• CORE

• Semantic Scholar (Ferramenta de IA)

• arXiv

• ACM Digital Library

• dblp

• CAPES

É importante manter a consistência e a rotina de leitura!

Setup com um nó

Seguindo esse setup você terá um k3s rodando em uma máquina Linux, se tornando um "cluster" de apenas um nó.

Requisitos

Requisitos do K3s: Requirements | K3s

Flux Operator CLI instalado na sua máquina

Conta no GitLab

Repositório já criado no GitLab

Passo-a-passo

Entre na máquina onde será instalado o K3s via SSH.

Instalação do K3s

Baseada na documentação oficial. Aqui apenas descrevo o passo a passo para o nosso caso de uso.

Execute o seguinte comando para instalar o K3s: curl -sfL https://get.k3s.io | sh -

Após a finalização, confirme o funcionamento: sudo k3s kubectl get node:

~$ sudo k3s kubectl get node 
NAME               STATUS   ROLES           AGE   VERSION
caronashow-dev-0   Ready    control-plane   40m   v1.34.6+k3s1

Acesso remoto do cluster

Para acessar o cluster sem precisar ficar manualmente entrando no shell da máquina via SSH, copie o kubeconfig do k3s via SSH.

O kubeconfig fica localizado em /etc/rancher/k3s/k3s.yaml

Após copiar, abra o arquivo e altere o IP do server no YAML para apontar para o IP da máquina remota.

Configure seu kubectl para usar esse kubeconfig. Pronto!

Bootstrap do Flux Operator

Agora vamos instalar o Flux Operator no cluster de produção utilizando o repositório Git que já estamos usando para o cluster de dev.

Para isso, na pasta clusters/prd, crie o flux-instance.yaml baseado no arquivo do cluster de dev. Basta copiar o arquivo e mudar o .spec.sync.path para a pasta de prd.

Após criar o arquivo novo, dê commit e mande para o GitLab as mudanças para a pasta existir quando o Flux for inicializar (a instalação falha caso a pasta não exista)

Agora, no cluster de produção, precisamos criar o secret para o Flux poder acessar o GitLab. Crie um PAT (Personal Access Token) e use-o para criar o secret flux-system no cluster com o comando abaixo (referenciado pelo flux-instance.yaml em .spec.sync.pullSecret):

kubectl create ns flux-system || true && \
  kubectl create secret generic \
    --from-literal=username='CaronaShow FluxCD Prd' \
    --from-literal=password="$(read)" \
    -n flux-system flux-system

Com o secret criado, inicialize o flux usando o flux-operator via cli:

flux-operator install -f flux-instance.yaml

Após a inicialização do Flux, basta configurar os apps para executar em produção!

Conclusão

Agora o cluster vai observar os arquivos dentro do clusters/prd e aplicar automaticamente no cluster.

Requisitos do sistema operacional

• Debian Linux ou qualquer distro Linux bem atualizada. Nota: WSL não suportado!

  • Foi utilizado Arch Linux para a criação do passo-a-passo

• Docker Engine instalado (guia instalação)

• K3d instalado

• FluxCD CLI instalado

Passo-a-passo

Para configurar um K8s (Kubernetes) cluster local, vamos usar o K3d para gerenciar o cluster local, que executa todos os components do K3s (distribuição de K8s lightweight) dentro de containers do Docker, facilitando a inicialização e removendo o acoplamento com o sistema operacional tradicional do K3s.

Criaremos um cluster local de desenvolvimento: caronashow-localdev

Em cada etapa abaixo, 

Criação do cluster de K8s

Inicialização básica

# Comando para criação abaixo
$ k3d cluster create caronashow-localdev

[...] # Logs do comando

# Fim com sucesso
INFO[0012] Cluster 'caronashow-localdev' created successfully!
INFO[0012] You can now use it like this:                
kubectl cluster-info

# Confirme se está tudo funcionando:
$ kubectl cluster-info
Kubernetes control plane is running at https://0.0.0.0:33531
CoreDNS is running at https://0.0.0.0:33531/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
Metrics-server is running at https://0.0.0.0:33531/api/v1/namespaces/kube-system/services/https:metrics-server:https/proxy

To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.

Criação de repositório Git

É necessário criar um repositório Git.

Ele será usado para definir o estado de todos os manifests (os arquivos .yaml) do cluster. Qualquer repositório git que seja acessível pelo cluster é suficiente. Recomendo criar um repositório pessoal no GitLab para seus testes.

Anote a URL usada para clonar o repositório via SSH (ssh://) e clone ele localmente no seu computador (git clone).

Dentro do repositório, crie a seguinte estrutura de pastas:

├── clusters
│   └── dev

Os arquivos do cluster serão criados em /clusters/dev/. Essa estrutura permitirá a criação de múltiplos clusters nesse repositório no futuro.

Inicialização do FluxCD

O FluxCD é responsável por manter o estado do cluster em sincronismo com o estados dos manifests no repositório Git.

flux bootstrap git \
    --url=<ssh://seugit:22/meu/repositorio> \
    --path=clusters/dev \
    --private-key-file=<path até sua chave privada>

► cloning branch "main" from Git repository "ssh://seugit.org:22/seu/caronashow-local-clusters.git"
✔ cloned repository
► generating component manifests
✔ generated component manifests
✔ component manifests are up to date
► installing components in "flux-system" namespace
✔ installed components
✔ reconciled components
► determining if source secret "flux-system/flux-system" exists
► generating source secret
✔ public key: <sua chave pública>

Esse comando vai executar e chegar em um pergunta. Apenas responda y.

Please give the key access to your repository: y
► applying source secret "flux-system/flux-system"
✔ reconciled source secret
► generating sync manifests
✔ generated sync manifests
✔ committed sync manifests to "main" ("redacted")
► pushing sync manifests to "ssh://seugit.org:22/seu/caronashow-local-clusters.git"
► applying sync manifests
✔ reconciled sync configuration
◎ waiting for GitRepository "flux-system/flux-system" to be reconciled
✔ GitRepository reconciled successfully
◎ waiting for Kustomization "flux-system/flux-system" to be reconciled
✔ Kustomization reconciled successfully
► confirming components are healthy
✔ helm-controller: deployment ready
✔ kustomize-controller: deployment ready
✔ notification-controller: deployment ready
✔ source-controller: deployment ready
✔ all components are healthy

Para verificar que funcionou corretamente, atualize sua branch local (git pull) e observe se o Flux criou um commit no seu repositório adicionando os arquivos como visto abaixo:

├── clusters
│   └── dev
│       └── flux-system
│           ├── gotk-components.yaml
│           ├── gotk-sync.yaml
│           └── kustomization.yaml

Setup com um nó (ambiente de dev)

Seguindo esse setup você terá um k3s rodando em uma máquina Linux, se tornando um "cluster" de apenas um nó.

Requisitos

• Requisitos do K3s: Requirements | K3s

• Flux CLI instalado na sua máquina

• Conta no GitLab

• Repositório já criado no GitLab

Passo-a-passo

Entre na máquina onde será instalado o K3s via SSH.

Instalação do K3s

Baseada na documentação oficial. Aqui apenas descrevo o passo a passo para o nosso caso de uso.

Execute o seguinte comando para instalar o K3s: curl -sfL https://get.k3s.io | sh -

Após a finalização, confirme o funcionamento: sudo k3s kubectl get node:

~$ sudo k3s kubectl get node 
NAME               STATUS   ROLES           AGE   VERSION
caronashow-dev-0   Ready    control-plane   40m   v1.34.6+k3s1

Acesso remoto do cluster

Para acessar o cluster sem precisar ficar manualmente entrando no shell da máquina via SSH, copie o kubeconfig do k3s via SSH.

O kubeconfig fica localizado em /etc/rancher/k3s/k3s.yaml

Após copiar, abra o arquivo e altere o IP do server no YAML para apontar para o IP da máquina remota.

Configure seu kubectl para usar esse kubeconfig. Pronto!

Bootstrap do FluxCD

Agora o Flux vai criar os arquivos no repositório Git e manter o sincronismo do estado no Git com o cluster.

Baseado na documentação oficial: Flux bootstrap for GitLab

Para isso execute o bootstrap. Ele pedirá seu Gitlab PAT (token de autenticação):

# Explicação do Comando
flux bootstrap gitlab \
        --components-extra=source-watcher \
        --deploy-token-auth \
        --owner=<grupo do gitlab> \
        --repository=<nome do repositório> \
        --branch=<branch default do git> \
        --path=<caminho raíz aonde ficará os manifests>
        
# Nossa execução
flux bootstrap gitlab \
        --components-extra=source-watcher \
        --deploy-token-auth \
        --owner=caronashow \
        --repository=kubernetes \
        --branch=main \
        --path=clusters/dev

Conclusão

Agora o cluster vai observar os arquivos dentro do path configurado no bootstrap e automaticamente atualizar seu estado para manter o sincronismo. Por padrão, o cluster verifica atualizações uma vez por minuto.

Setup com múltiplos nós (ambiente de prd)

TODO

Como funciona

Para armazenar os secrets do Kubernetes de forma declarativa e versionada no Git, é necessário criptografar esses secrets antes de salvá-los no repositório.

Para isso, usamos o SOPS juntamente ao age para criptografar os valores dentro dos manifests dos secrets. Após criptografado, no momento da reconcile do Flux, o secret é automaticamente descriptografado ao ser aplicado.

Como configurar no cluster

Esse guia assume que você já configurou o Flux no cluster e está com seu repositório Git sincronizando com o cluster. Siga os comandos abaixo dentro da pasta específica do cluster.

# Nome do cluster
export CLUSTER_NAME=dev

# Criar chave de criptografia
age-keygen -o sops-$CLUSTER_NAME.agekey

# Criar secret no cluster com a chave de criptografia
cat sops-$CLUSTER_NAME.agekey | kubectl create secret generic sops-age \
      --namespace=flux-system \
      --from-file=age.agekey=/dev/stdin
      

Dados de entrada

• Viagens completas

• Avaliações

• Tempo desde primeira viagem

• Ter uma foto

Ranks

Bronze

• Inicio

Prata

• 3 viagem completa

• 1 mês da primeira viagem

Ouro

• Ter uma foto

• Mais viagens

• Avaliação Boa