Do desenvolvimento local ao deploy: o que aprendi criando o Kado

João Ramajo — Sat, 30 May 2026 08:00:30 +0000

Nos últimos meses, tenho desenvolvido, para uso pessoal, uma plataforma para gerenciar meu dinheiro de uma maneira mais consciente. Não gosto de planilhas e também queria estudar algo novo. Essa união de fatores me levou inicialmente ao Filament PHP e, depois, a uma arquitetura com frontend e backend independentes.

Antes de tudo

Kado é um projeto de gestão de finanças pessoais. Com certeza, existem poucos por aí e nem deve existir um subreddit sobre isso. Mas, enfim, minha intenção nunca foi criar um produto, e sim resolver dois problemas: controle de gastos e falta de ideias para projetos de estudo. Então, comecei a desenvolver este projeto com o objetivo de estudar conceitos mais complexos, como: proxy reverso, integração entre front e back, pipelines de automação de deploy, configuração de Nginx, certificados SSL, projetos em produção e alguns outros conceitos nos quais não pretendo me aprofundar muito.

No fim, cheguei a um MVP que atende à minha necessidade de maneira satisfatória. Consigo registrar o que ganho e o que gasto, com categorização e controle de fontes de entrada e saída, o que me ajuda a realmente ter um panorama de para onde meu dinheiro está indo.

Meu intuito aqui não é explicar a fundo os conceitos, deixo isso para outro momento, mas sim compartilhar um pouco do que fiz até aqui.

O que o Filament tem a ver?

Minha ideia inicial era apenas desenvolver algo localmente em cima da biblioteca de painéis administrativos Filament, e assim segui por um tempo. Estudei a documentação, comecei a criar resources e as telas foram tomando forma, com tabelas de despesas e métricas de entrada e saída de dinheiro. Estava tudo indo bem, mas chegou um momento em que senti que não era o suficiente.

Talvez por limitação de não conhecer bem a ferramenta, certas coisas acabaram me limitando: tipos de interação que eu queria fazer, designs diferentes, entre outras coisas.

Esses foram fatores que me levaram a quebrar o projeto em duas frentes: o backend como uma API Laravel e o frontend como uma aplicação React + TypeScript com Vite e MUI (Material UI), que também veio como um laboratório de estudos para o frontend, já que eu havia acabado de entrar em um projeto que utiliza essa biblioteca de componentes.

O que eu aprendi

Trabalhando neste projeto tive a oportunidade de entender melhor ferramentas e conceitos usados no ciclo de vida de projetos reais, como:

Proxy Reverso

Tenho uma VPS que rodava outro projeto de maneira simples: Nginx e PHP-FPM rodando sem containers na porta 80, e uma linda história feliz, até o momento em que eu quis subir outro projeto nessa mesma VPS e não tive ideia de como fazer.

Para resolver esse problema, optei por utilizar um servidor Nginx instalado direto na VPS como servidor principal, configurado para apontar para diferentes projetos rodando dentro de containers Docker, cada um com seu próprio Nginx e subdomínio configurado para acessá-los.

Assim, resolvo o problema de ter múltiplos projetos em uma mesma VPS de maneira simples.

Mas fico pensando se não existia alguma maneira mais simples, foi um ponto excelente para estudar sobre Docker e servidores mas foi uma dor de cabeça entender como tudo isso deveria funcionar e me rendeu com certeza alguns dias testando maneiras diferentes de fazer isso funcionar.

Domínios e SSL

Fica feio ter um projeto rodando e, na hora de mandar para um amigo, a URL ser o IP do servidor, além de, claro, não ser nada seguro.

Com isso, comecei a ver como eu poderia configurar um domínio e subdomínios para utilizar nos meus projetos. Usando a própria plataforma de hospedagem, peguei um domínio e comecei a configurar o DNS para permitir o uso de subdomínios.

Com isso, tendo um único domínio eu posso ter vários projetos em seus subdomínios, o que se encaixa bem com a estratégia que utilizei para configurar o proxy reverso.

Mas isso não resolve um problema: segurança mínima. Requisições HTTP geralmente podem servir em casos simples, para quem não quer muito trabalho, mas configurar um certificado SSL para permitir tráfego em HTTPS hoje em dia está bem simples e é uma camada a mais de segurança que você adiciona ao seu projeto.

Basta utilizar o Certbot para gerar os certificados e, junto da configuração correta do Nginx, podemos ter isso funcionando bem rápido.

Deploy e CI/CD

Rodar o projeto localmente é fácil: basta dar um php artisan serve ou npm run dev, mas, ao fazer o deploy de um projeto real, a história muda.

Você precisa se preocupar com configuração do ambiente, acessos e permissões de pastas. Muita atenção aqui, porque muitos erros que você pode encontrar acontecem justamente nesse ponto.

Tive vários problemas relacionados à forma como o deploy automatizado rodava alguns comandos, o que causava erros de permissão nas pastas de logs ou cache. Esse é um problema que encontro com certa frequência ao tentar rodar projetos Laravel em containers.

Além disso, ninguém gosta de ficar acessando o SSH do servidor a cada alteração que fazemos no projeto, né? Aí que entra o GitHub Actions.

Com o GitHub Actions, conseguimos configurar uma pipeline de deploy dentro de um evento no GitHub, como a criação de uma nova release. Assim, podemos definir as etapas de acesso ao servidor, atualização do código, execução das migrations, entre outras etapas necessárias.

Foi assim que configurei o deploy da API do Kado, já que a Vercel disponibiliza isso de maneira simplificada para projetos em React, sendo necessário apenas configurar o projeto dentro da própria Vercel uma única vez. Após isso, ela irá realizar o deploy a cada push que você fizer na main ou na branch especificada.

Também podemos configurar etapas de segurança para PRs, como execução de testes, linters ou alguma outra ação. Optei por não configurar, pois somente eu desenvolvo atualmente no código do Kado e não há necessidade desse nível de complexidade para algo simples, que só eu trabalho ou utilizo.

Integrando Frontend com Backend

Em projetos monolíticos, muitas vezes não precisamos lidar com questões como CORS, autenticação via tokens, entre outros problemas que podemos encontrar durante o desenvolvimento, mas isso muda quando você separa o front do back.

Neste projeto a separação foi proposital. Para mim, fazia muito mais sentido trabalhar em cima de um projeto em React com deploy feito na Vercel, pela praticidade de visualizar as alterações e pela simplicidade de publicá-las. Essa foi uma das maiores vantagens que isso pode trazer para um projeto, mas nem tudo são vantagens.

Quando se tem uma arquitetura com backend e frontend separados, devemos ter noção de que um contrato bem definido é o caminho para a felicidade. Uma pena que eu não entendia isso muito bem até sentir na pele, porque até mesmo a menor alteração pode causar grandes mudanças na base de código e aumentar o espaço para novos bugs ao longo do tempo.

Com isso, posso garantir uma coisa: não existe aliado maior do desenvolvedor do que testes automatizados e linters.

Para o frontend, não criei efetivamente testes automatizados por questão de praticidade, mas configurar o Biome (linter) para padronização de estilo de código e sugestões de refatoração foi essencial para garantir qualidade no código e, assim, evitar possíveis problemas que encontrei.

No backend, fui mais a fundo: montei testes automatizados utilizando o Pest, análise estática de código com o PHPStan, ajustes de estilo com o Laravel Pint e refatoração com o Rector. E de uma coisa tenho certeza, você com certeza deveria conhecer essas bibliotecas se trabalha em projetos PHP.

Qualidade de código não resolve todos os problemas, mas aumenta bastante as chances de você encerrar a sexta-feira com mais tranquilidade, sem medo de ser acionado no fim de semana porque esqueceu de retirar um dd() em produção.

O que eu faria diferente hoje

Olhando agora, vejo que tenho um projeto bem legal como laboratório de estudos, mas existem, sim, coisas que eu faria diferente se pudesse.

Planejamento antes do código: mesmo sendo um projeto pessoal, gostaria de ter planejado melhor e montado os fluxos de maneira mais estruturada no começo. Isso teria evitado muito retrabalho e dor de cabeça.
Linters e testes desde o começo: no começo do projeto, eu fui bem no estilo "moda da casa", então acabei fazendo bastante coisa que tive que reescrever para passar nas ferramentas de qualidade, e testes nem se fala.
Publicar sobre o processo de desenvolvimento: se eu pudesse, teria dado um pouco mais de atenção a documentar melhor (seja no LinkedIn ou no Dev.to) o processo de desenvolvimento deste projeto. Expressar ideias e conhecimento é a base de um bom profissional em meio a tantas incertezas na área.

Mas não é porque eu faria diferente hoje que não gostei do resultado atual. Ter um projeto feito de ponta a ponta é realmente algo muito bom de se ter, é uma prova de que você é capaz de realizar coisas que antes nem fazia ideia de por onde começar.

Conclusão

No fim, o Kado pode ser só mais um aplicativo de gestão financeira entre os muitos que existem, mas, para mim, ele é a prova de que eu evoluí como desenvolvedor no último ano, tanto em código quanto em visão de produto.

Fico feliz com a situação atual dele, mas claro que não vou parar de trabalhar nele. Sempre há o que inventar, e agora, pelo menos eu sei por onde começar.

Link do projeto: https://kado-tan.vercel.app/inicio

DEV Community: João Ramajo