eCommerce Accessible Platform for You - Capi-vara Cart

Capi ou carinhosamente chamado de Capivara Cart é um e-commerce open source construido em svelte e python para ser usadocomo principal solução self-host.

Esse projeto ainda está em pré-alpha mas, pode ser usado.

Gateway de pagamentos compactiveis

• Mercado pago
• Stripe
• Cielo (Wip)

Feature

• Cupons
• Afiliados (Pode afiliar pessoas a produtos ou ao e-commerce)
• Co-produtor (Pode criar participação a um co-produtor)
• Pagamento em Cartão
• Pagamento em Pix
• Controle de estoque
• Controle de logística
• Calculo de frete via Correios

Estrutura

• Front shopping
• Backend
• Admin

Como rodar localmente?

Este guia te ajuda a subir o CapiCart na sua máquina. Tem três caminhos — escolha o que combina com você:

• Cenário A (Recomendado): Docker só pra infra (banco, cache, fila) + back e frontends rodando manual na sua máquina. Mais leve, melhor pra dev do dia-a-dia.
• Cenário B: Tudo manual, sem Docker nenhum. Você instala Postgres, Redis e RabbitMQ direto na máquina.
• Cenário C: Tudo dentro de containers (docker compose up -d). Mais lento pra dev, mas funciona sem instalar nada além do Docker.

Antes de tudo, leia a seção "O que é isso?" pra entender o que cada ferramenta faz.

---

O que é isso? (Glossário rápido)

Não tem vergonha de não saber — bootcamp ensina framework, não ensina o resto do mundo. Aqui vai o que cada coisa faz:

Git submodule: um repositório Git dentro de outro. Cada pasta do projeto (back/, admin/, gattorosa-front/, crowdfunding-front/, front-shopping/) é um repositório Git separado, linkado dentro deste monorepo. Quando você clona o monorepo, essas pastas vêm vazias — você precisa rodar git submodule update --init --recursive pra preencher.

Docker: programa que roda "containers" (mini-máquinas virtuais leves). A gente usa pra rodar Postgres, Redis, RabbitMQ sem precisar instalar eles direto na sua máquina. É mais leve que uma VM tradicional.

uv: instalador de Python ultra-rápido (substituto moderno do pip e do pyenv). Gerencia versões do Python + dependências do projeto num único comando (uv sync). Substitui um monte de coisa que antes era chato de configurar.

nvm (Node Version Manager): programa que deixa você ter várias versões do Node instaladas na mesma máquina. A gente usa Node 24+ no admin e gattorosa-front, e Node 20+ no front-shopping. Sem nvm você teria que ficar instalando/desinstalando Node na mão.

pnpm: gerenciador de pacotes JavaScript (alternativa ao npm e ao yarn). Mais rápido e economiza espaço em disco. A gente usa em todos os frontends deste projeto.

alembic: ferramenta que controla a "versão" do banco de dados (migrations). Cada mudança na estrutura do banco vira um arquivo novo versionado, e alembic upgrade head aplica todas as migrations pendentes na ordem. Sem isso, recriar o banco do zero seria um inferno.

psql: cliente de linha de comando do PostgreSQL. Você usa pra rodar SQL direto no banco (criar roles, ajustar dados, conferir tabelas).

make: utilitário que roda "atalhos" definidos num arquivo Makefile. No backend, make run é o mesmo que digitar uv run uvicorn main:app --reload, só que mais curto. Tem em qualquer sistema Unix-like (e no WSL).

---

Pré-requisitos

Você precisa ter instalado na sua máquina. Tabela com comandos por sistema operacional:

Ferramenta	Versão	Linux (Ubuntu/Debian)	macOS	Windows
Git	latest	sudo apt install git	brew install git (ou Xcode Tools)	https://git-scm.com
Docker + Compose	latest	https://docs.docker.com/engine/install	https://docs.docker.com/desktop/mac	Docker Desktop + WSL2
Python	3.13+	vem com uv	brew install python@3.13 ou vem com uv	vem com uv
uv	latest	curl -LsSf https://astral.sh/uv/install.sh | sh	mesmo comando (no Terminal)	mesmo comando (no WSL2)
nvm	latest	https://github.com/nvm-sh/nvm#install--update-script	mesmo	nvm-windows (link no repo)
Node (via nvm)	24 (admin, gattorosa)	nvm install 24	mesmo	mesmo
Node (via nvm)	20 (front-shopping)	nvm install 20	mesmo	mesmo
pnpm	latest	npm install -g pnpm (depois de instalar Node)	mesmo	mesmo

Windows: use WSL2 (Windows Subsystem for Linux). Todos os comandos deste README foram testados em Linux/macOS. No WSL2 funcionam idênticos.

Instalando o nvm (passo a passo)

# Linux/macOS (rode no terminal):
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Feche e reabra o terminal, depois confirme:
nvm --version

No Windows, baixe o instalador em https://github.com/coreybutler/nvm-windows/releases (arquivo nvm-setup.exe).

Instalando o pnpm

# Depois de instalar Node (via nvm ou direto):
npm install -g pnpm

# Alternativa mais moderna (se tiver Node 16.13+):
corepack enable pnpm

# Confirme:
pnpm --version

---

Primeiro passo: clonar o repositório

git clone <url-do-repo> capicart
cd capicart
git submodule update --init --recursive

Por que dois comandos? O git clone baixa só o monorepo. As 5 pastas de submodule vêm vazias até você rodar o git submodule update. Esqueceu o segundo comando? As pastas vão estar vazias e nada vai funcionar — esse é o erro nº 1 de quem é novo no projeto.

---

Git básico para este monorepo

Este projeto é um monorepo com submodules. Cada pasta é um repositório Git independente. Por isso, comandos Git rodam em dois níveis: o nível do monorepo (raiz) e o nível de cada submodule.

Atualizar tudo (puxar mudanças novas do servidor)

# Da raiz do monorepo:
git pull
git submodule update --init --recursive

O segundo comando é essencial — sem ele, mesmo depois do git pull, os submodules ficam na versão antiga.

Ver o que mudou em cada lugar

# Status do monorepo (vê se algum submodule precisa atualizar o ponteiro):
git status

# Status de um submodule específico (vê arquivos modificados dentro dele):
git -C back status
git -C admin status

Fazer commit em UM submodule (ex: mudou algo no back)

cd back
# edita os arquivos que você quer
git add .
git commit -m "feat(back): o que você mudou"
git push origin main        # IMPORTANTE: subir pro remote do próprio submodule
cd ..

Fazer commit no monorepo (atualizar o ponteiro do submodule)

Depois de commitar e fazer push dentro do submodule, volte pra raiz e commite a mudança do ponteiro:

cd ..
git add back                # adiciona a mudança do ponteiro
git commit -m "chore: update back submodule"
git push origin main

Pegadinha comum (e como perder trabalho): se você commitar no submodule mas NÃO der push lá, depois alguém (ou você em outra máquina) fizer git submodule update, vai perder o commit porque o ponteiro aponta pra um commit que não existe no remote. Sempre: commit → push no submodule → commit no monorepo → push no monorepo.

Trabalhando em vários submodules ao mesmo tempo

Abra um terminal pra cada um, ou use tmux/screen pra dividir a tela.

---

Cenário A — Recomendado: Docker só pra infra + back/frontends manuais

Esse é o caminho mais leve. Você sobe Postgres + Redis + RabbitMQ + Mailhog em Docker (uma linha) e roda o back e os frontends direto na sua máquina (mais rápido pra ver mudanças no código — hot reload funciona).

Passo 1 — Subir a infra no Docker

docker compose up -d postgres redis rabbitmq mailhog

Aguarde uns 30 segundos. Pra confirmar que subiu:

docker compose ps

postgres deve aparecer como healthy (não só running — leva um tempo pra ficar pronto).

Passo 2 — Rodar o backend (FastAPI)

Abra um terminal novo:

cd back

# Instalar Python 3.13 e dependências (primeira vez pode demorar 1-2 min):
uv sync

# Criar o arquivo .env (o `settings.toml` já tem defaults; o .env sobrescreve só o essencial):
cat > .env <<'EOF'
DYNACONF_DATABASE_URL=postgresql://postgres_user:pass123@localhost:5433/ecommerce
DYNACONF_DATABASE_URI=postgresql+asyncpg://postgres_user:pass123@localhost:5433/ecommerce
DYNACONF_BROKER_URL=amqp://guest:guest@localhost:5672/
DYNACONF_REDIS_URL=redis://localhost:6380
DYNACONF_ENVIRONMENT=development
EOF

# Aplicar as migrations no banco (cria as tabelas):
make migrate

# Seed inicial (cria roles + config de parcelamento). Sem isso a API quebra:
docker exec -i ecommercedb psql -U postgres_user -d ecommerce <<'EOF'
INSERT INTO public."role" (role_id, "role", active) VALUES(1, 'ADMIN', true);
INSERT INTO public."role" (role_id, "role", active) VALUES(2, 'USER', true);
INSERT INTO public."role" (role_id, "role", active) VALUES(3, 'AFFILIATE', true);
INSERT INTO public.credit_card_fee_config (credit_card_fee_config_id, min_installment_with_fee, max_installments, fee, active_date) VALUES(1, 4, 12, 0.12, NOW());
EOF

# Subir a API:
make run

A API vai estar em http://localhost:8001 e a documentação Swagger em http://localhost:8001/docs.

Passo 3 — Rodar o painel admin

Abra outro terminal:

cd admin

# Garantir Node 24:
nvm use 24                  # ou: nvm install 24 (se ainda não baixou essa versão)

# Instalar dependências (pnpm lockfile é commitado, então é rápido):
pnpm install

# Criar o .env (o exemplo já vem correto pra dev):
cp .env.example .env

# Subir (hot reload ativo):
pnpm dev

Painel em http://localhost:3000.

Passo 4 — Rodar a loja Gattorosa

Abra outro terminal:

cd gattorosa-front

nvm use 24
pnpm install
cp .env.example .env

ATENÇÃO: o .env.example aponta pra API de PRODUÇÃO (https://api.gattorosa.com.br). Se você não editar, vai mexer em dados reais. Abra o .env no seu editor e mude a linha:

VITE_SERVER_BASE_URL=http://localhost:8001
PUBLIC_MERCADO_PAGO_PUBLIC_KEY=TEST-sua-chave-aqui

pnpm dev

Loja em http://localhost:5175.

Passo 5 (opcional) — Crowdfunding e Front Shopping legado

# Crowdfunding:
cd crowdfunding-front
pnpm install
cat > .env <<'EOF'
PUBLIC_API_URL=http://localhost:8001
PUBLIC_FARO_URL=
PUBLIC_FARO_APP_NAME=crowdfunding-front
EOF
pnpm dev
# Abre em http://localhost:5174

# Front Shopping (legado — usa pnpm apesar de alguns docs antigos falarem yarn):
cd ../front-shopping
nvm use 20
pnpm install
cat > .env <<'EOF'
VITE_SERVER_BASE_URL=http://localhost:8001
EOF
pnpm dev
# Abre em http://localhost:5173

Passo 6 — Criar seu primeiro admin

1. Abra a loja Gattorosa (http://localhost:5175) e cadastre um usuário novo normal.
2. Promova ele pra admin no banco:

docker exec -it ecommercedb psql -U postgres_user -d ecommerce

UPDATE "user" SET role_id = 1 WHERE email = 'seu-email@example.com';
\q

3. Faça login no painel admin (http://localhost:3000).

---

Cenário B — Tudo manual (sem Docker)

Se você não quer/usa Docker, instale Postgres 17, Redis e RabbitMQ direto na máquina:

# Ubuntu/Debian:
sudo apt install postgresql-17 redis-server rabbitmq-server

# macOS:
brew install postgresql@17 redis rabbitmq
brew services start postgresql@17
brew services start redis
brew services start rabbitmq

Crie o banco e o usuário (uma vez só):

sudo -u postgres psql <<'EOF'
CREATE USER postgres_user WITH PASSWORD 'pass123';
CREATE DATABASE ecommerce OWNER postgres_user;
GRANT ALL PRIVILEGES ON DATABASE ecommerce TO postgres_user;
\q
EOF

Depois siga os mesmos passos do Cenário A a partir do "Passo 2", mas ajustando o back/.env:

• Troque localhost:5433 por localhost:5432 (porta padrão do Postgres local)
• Troque localhost:6380 por localhost:6379 (porta padrão do Redis local)
• RabbitMQ localhost:5672 já é o padrão

No Passo 6 (criar admin), troque docker exec -it ecommercedb psql ... por sudo -u postgres psql -U postgres_user -d ecommerce.

---

Cenário C — Tudo dentro de containers

Mais simples de subir, mas mais lento pra dev (qualquer mudança no código precisa rebuildar o container, ou você monta volume — depende da config do docker-compose.yml).

# Subir tudo (api + postgres + redis + rabbitmq + mailhog + admin + gattorosa + crowdfunding + front-shopping):
docker compose up -d

# Aguardar (postgres pode levar 30s pra ficar healthy):
docker compose ps

# Aplicar migrations no banco (uma vez, depois disso o banco já tá pronto):
docker compose exec api uv run alembic upgrade head

# Seed inicial (roles + parcelamento):
docker compose exec postgres psql -U postgres_user -d ecommerce <<'EOF'
INSERT INTO public."role" (role_id, "role", active) VALUES(1, 'ADMIN', true);
INSERT INTO public."role" (role_id, "role", active) VALUES(2, 'USER', true);
INSERT INTO public."role" (role_id, "role", active) VALUES(3, 'AFFILIATE', true);
INSERT INTO public.credit_card_fee_config (credit_card_fee_config_id, min_installment_with_fee, max_installments, fee, active_date) VALUES(1, 4, 12, 0.12, NOW());
EOF

Acesse:

• API: http://localhost:8001
• Admin: http://localhost:3000
• Gattorosa: http://localhost:5175
• Crowdfunding: http://localhost:5174
• Front Shopping: http://localhost:5173
• Mailhog (ver emails enviados): http://localhost:8025

Siga o "Passo 6 — Criar seu primeiro admin" do Cenário A.

---

Verificando se está tudo OK

Rode estes comandos pra confirmar:

# API responde?
curl http://localhost:8001/docs
# Esperado: HTML com "Swagger UI"

# Admin carrega?
curl -s http://localhost:3000 | head -5
# Esperado: começa com <!DOCTYPE html>

# Gattorosa carrega?
curl -s http://localhost:5175 | head -5
# Esperado: HTML

# Banco tá healthy?
docker exec ecommercedb pg_isready
# Esperado: "accepting connections"

# Redis tá up?
docker exec <redis-container> redis-cli ping
# Esperado: PONG

# RabbitMQ tá up?
docker logs <rabbitmq-container> --tail 10
# Esperado: sem erros vermelhos

---

Problemas comuns

"Porta X já está em uso"

# Descobrir o que tá usando (exemplo porta 8001):
lsof -i :8001                   # macOS/Linux
sudo netstat -tlnp | grep 8001  # Linux só

# Matar o processo (substitua PID):
kill -9 <PID>

Pastas de submodule vazias

Você pulou o git submodule update --init --recursive. Rode:

git submodule update --init --recursive

Postgres não sobe (Permission denied em pg17/)

sudo rm -rf pg17               # deixa o Docker recriar
# OU
sudo chown -R 999:999 pg17     # ajusta o dono pro UID do Postgres no container

pnpm install reclama da versão do Node

Você não tá com a versão certa. Use o nvm pra trocar:

cd admin          # ou gattorosa-front
nvm use 24        # ou: nvm install 24 se ainda não baixou

cd ../front-shopping
nvm use 20

"Estou vendo dados de produção!"

Você esqueceu de mudar o VITE_SERVER_BASE_URL no gattorosa-front/.env. Edite, salve, e reinicie o pnpm dev.

alembic upgrade head falha

Provavelmente o Postgres ainda não tá healthy. Espere mais:

docker compose ps               # olha o STATUS do postgres
docker compose logs postgres    # vê os logs

Como iniciar em produção?

Docker-compose

• WIP

Dokku

Requisitos

• Um bucket compáctivel com S2 recomendando o Wasabi
• Servidor com pelo menos 2Gb de Ram (vai depender da sua carga)
• Gateway de Pagamento no momento é compáctivel com Mercado Pago, Cielo e Stripe.
• Gateway de entregas no momento é compactivel com os Correios
• Servidor SMTP hoje é compactive com Sendgrid
• Sentry não é mandatório mas, é importando pra analisar erros.

Instalação

A instalação do Dokku pode ser feita através da documentação abaixo: Documentação do Dokku

É necessário instalar o plugin do rabbitmq, postgres e redis para isso é possível usar o comando abaixo:

# on 0.19.x+
sudo dokku plugin:install https://github.com/dokku/dokku-rabbitmq.git --name rabbitmq
sudo dokku plugin:install https://github.com/dokku/dokku-postgres.git
sudo dokku plugin:install https://github.com/dokku/dokku-redis.git --name redis

Recomendamos usar um servidor com pelo menos 2Gb de Ram, mas dependendo da quantidade de apps e a carga isso pode variar.

Criando os projetos no servidor

É necessário criar 3 projetos o frontend, admin e API que serão usados para a instalação.

dokku apps:create api-example
dokku apps:create front-example
dokku apps:create admin-example

Próximo passo é criar um banco de dados do postgres, redis e uma fila no rabbitmq e linka-lo a nossa API

# postgres
dokku postgres:create db-example
dokku postgres:link db-example api-example

# redis
dokku redis:create redis-example
dokku redis:link redis-example api-example

# rabbitmq
dokku rabbitmq:create rabbit-example
dokku rabbitmq:link rabbit-example api-example

deployment

Ir para o projeto local e adicionar o IP do Servidor e o APP como um remote do git. É importante que você adicione uma chave SSH ao ssh-agent do servidor.

ssh-add -k ~/<your private key>

Agora criamos o remote para cada projeto:

git remote add dokku dokku@100.100.100.100:admin-example
git remote add dokku dokku@100.100.100.100:front-example
git remote add dokku dokku@100.100.100.100:api-example

Agora precisamos colocar as variáveis de ambiente nos projetos.

#backend
dokku config:set api-example DYNACONF_ACCESS_TOKEN_EXPIRE_MINUTES=90 DYNACONF_ADMIN_URL=https://demo.admin.example.com DYNACONF_API_MAIL_URL=https://testapi.com/ DYNACONF_AWS_ACCESS_KEY_ID="xxxxxxx" DYNACONF_AWS_SECRET_ACCESS_KEY="xxxxxx" DYNACONF_BROKER_URL=amqp://example:xxxxxx@dokku-rabbitmq-staging:5672/example DYNACONF_BUCKET_NAME=cdn.example.com DYNACONF_COMPANY=Capivara DYNACONF_CORREIOSBR_API_SECRET="xxxxxxx" DYNACONF_CORREIOSBR_CEP_ORIGIN=1000000 DYNACONF_CORREIOSBR_PASS=usercorreios DYNACONF_CORREIOSBR_POSTAL_CART=000011111 DYNACONF_CORREIOSBR_USER="111111gr." DYNACONF_DATABASE_URI=postgresql+psycopg://postgres:xxxxx@dokku-postgres-example:5432/example DYNACONF_DATABASE_URL=postgresql+psycopg://postgres:xxxxx@dokku-postgres-example:5432/example DYNACONF_EMAIL_FROM=contact@jonatasoliveira.dev DYNACONF_ENDPOINT_UPLOAD_CLIENT=https://s3.us-east-2.wasabisys.com/ DYNACONF_ENDPOINT_UPLOAD_REGION=us-east-2 DYNACONF_ENVIRONMENT=production DYNACONF_FILE_UPLOAD_CLIENT=WASABI DYNACONF_FILE_UPLOAD_PATH=https://cdn.example.com/ DYNACONF_FRONTEND_URL=https://demo.capicart.com DYNACONF_FRONTEND_URLS=https://demo.capicart.com DYNACONF_GATEWAY_API=API_KEY DYNACONF_GATEWAY_CRYP=CRYP_KEY DYNACONF_MERCADO_PAGO_ACCESS_TOKEN=PROD-xxx-xxxx-xxx-xxxx DYNACONF_MERCADO_PAGO_PUBLIC_KEY=PROD-xxxxx-xxx-xx-xx-xxxx DYNACONF_MERCADO_PAGO_URL=https://api.mercadopago.com DYNACONF_PAYMENT_GATEWAY_URL=URL_GATEWAY DYNACONF_REDIS_DB=0 DYNACONF_REDIS_URL=redis://:xxxxx@dokku-redis-example:6379 DYNACONF_RESULT_BACKEND=rpc:// DYNACONF_SENDGRID_API_KEY="SG.xxx.xxxw-xxxxx" DYNACONF_SETRY_DSN=https://xxxx@o11111eee.ingest.sentry.io/ss12333 DYNACONF_STRIPE_API_KEY="pk_xxxxxxxl" DYNACONF_STRIPE_SECRET_KEY="sk_xxxxxxxxxx"

#frontend
dokku config:set front-example VITE_MERCADO_PAGO_PUBLIC_KEY="PROD-xxxxx-xxx-xxx-xxxx-xxxx" VITE_MERCADO_PAGO_ACCESS_TOKEN="PROD-xxxxx-xxxx-xxxx-xxxxxx" VITE_SERVER_BASE_URL=https://demo.api.capicart.com/docs WHATSAPP_NUMBER="+5511123456789" URL_LOGO="https://site.com/logo.svg" RECAPTCHA_KEY="xxxx" RECAPTCHA_SECRET_KEY="xxxxx" SENTRY_DSN="xxx" SENTRY_ENV="production" ALT_LOGO="logo" GTAG_ID="xxxxx"

#admin
dokku config:set admin-example SERVER_BASE_URL=https://api.api.com
dokku docker-options:add admin-gattorosa build '--build-arg PUBLIC_SERVER_BASE_URL'

Adicionar o header:

dokku nginx:set api-example client-max-body-size 50m

O que faz cada variável?

[WIP]

Configuração pré deploy

Por hora a API não tem seed automático por conta disso vamos ter que adicionar manualmente as roles e configuração de parcelamento no banco de dados.

INSERT INTO public."role"
(role_id, "role", active)
VALUES(1, 'ADMIN', true);
INSERT INTO public."role"
(role_id, "role", active)
VALUES(2, 'USER', true);
INSERT INTO public."role"
(role_id, "role", active)
VALUES(3, 'AFFILIATE', true);

INSERT INTO public.credit_card_fee_config
(credit_card_fee_config_id, min_installment_with_fee, max_installments, fee, active_date)
VALUES(1, 4, 12, 0.12, '2023-10-17 11:14:22.822');

Para fazer o deploy em cada projeto usamos:

git push dokku main

Agora é necessário definir a url e ativar o SSL:

dokku domains:set api-example api.example.com
dokku domains:set admin-example admin.example.com
dokku domains:set front-example example.com

Agora par ativar o SSL após configurar o DNS é só usar os commandos abaixo:

# Instalar o plugin
sudo dokku plugin:install https://github.com/dokku/dokku-letsencrypt.github

# Configura o -email para o dokku-letsencrypt
dokku letsencrypt:set --global email your-email@your.domain.com

# Habilitar nos sites
dokku letsencrypt:enable api-example
dokku letsencrypt:enable front-example
dokku letsencrypt:enable admin-example

Agora o projeto já pode ser executado.

Obs: Ainda é necessário depois de subir os projetos criar um usuário pelo front e ir manualmente e transforma-lo em admin.