Documentação - Ambiente Fullstack

🚀 Ambiente de Desenvolvimento Fullstack - Documentação Completa

Documentação completa do ambiente de desenvolvimento fullstack com infraestrutura compartilhada.

📋 Índice

Visão Geral
Arquitetura
Acesso ao Ambiente
Serviços Compartilhados
Criando Projetos
Gerenciamento de Projetos
Estrutura de Diretórios
Configuração de Portas
Nginx e Domínios
Banco de Dados
Object Storage (MinIO)
Redis
Scripts de Automação
Segurança
Troubleshooting
Comandos Úteis

Visão Geral

O Que É Este Ambiente?

Este é um ambiente de desenvolvimento fullstack projetado para:

✅ Múltiplos projetos rodando simultaneamente
✅ Infraestrutura compartilhada (PostgreSQL, MinIO, Redis)
✅ Projetos rodam nativamente (fora do Docker) para melhor desempenho
✅ Domínios automáticos via wildcard *.dev.alav.cloud
✅ SSL configurado para todos os projetos
✅ Portas gerenciadas automaticamente

Stack Tecnológica

Componente	Tecnologia
Backend	Go (Gin Framework)
Frontend	Vue.js (Vite) ou Next.js
Banco de Dados	PostgreSQL 16
Object Storage	MinIO (S3-compatible)
Cache/Filas	Redis 7
Proxy Reverso	Nginx
Containerização	Docker + Docker Compose

Arquitetura

┌─────────────────────────────────────────────────────────────┐
│                    INTERNET                                  │
│                    *.dev.alav.cloud                          │
└─────────────────────┬───────────────────────────────────────┘
                      │ HTTPS (443)
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                    NGINX (Docker)                            │
│              Proxy Reverso + SSL Termination                 │
│  caixa.dev.alav.cloud     → http://localhost:3000 (Frontend)│
│  caixa.dev.alav.cloud/api → http://localhost:8000 (Backend) │
└─────────────────────┬───────────────────────────────────────┘
                      │
         ┌────────────┼────────────┐
         │            │            │
         ▼            ▼            ▼
┌─────────────┐ ┌──────────┐ ┌──────────┐
│  FRONTEND   │ │ BACKEND  │ │  OUTROS  │
│  (Vite/     │ │  (Go/    │ │  PROJETOS│
│   Next.js)  │ │   Gin)   │ │          │
│  Porta 3000 │ │ Porta 800│ │          │
└─────────────┘ └──────────┘ └──────────┘
         │            │
         └─────┬──────┘
               │
               ▼
┌──────────────────────────────────────────────────────────────┐
│              INFRAESTRUTURA COMPARTILHADA (Docker)           │
│  ┌──────────────┐  ┌──────────┐  ┌─────────────────────┐   │
│  │  PostgreSQL  │  │  Redis   │  │       MinIO         │   │
│  │   (5432)     │  │  (6379)  │  │   (9000 API)        │   │
│  │  devdb       │  │  Cache   │  │   (9001 Console)    │   │
│  │  proj_caixa  │  │  Filas   │  │   Buckets S3        │   │
│  └──────────────┘  └──────────┘  └─────────────────────┘   │
└──────────────────────────────────────────────────────────────┘

Acesso ao Ambiente

1. Acesso SSH

# Acessar a VPS
ssh root@<IP-DA-VPS>

# Ou como usuário desenvolvedor
ssh dev@<IP-DA-VPS>

2. Usuários Disponíveis

Usuário	Permissões
`root`	Root completo
`dev`	Sudo sem senha + Docker

3. Criar Senha para Usuário `dev`

# Como root
passwd dev

4. Acessar como `dev`

# Do terminal SSH (como root)
su - dev

# Ou direto no login
ssh dev@<IP-DA-VPS>

Serviços Compartilhados

PostgreSQL

Dados de Conexão:

Host: localhost (ou shared-postgres dentro da rede Docker)
Porta: 5432
Database: devdb
Usuário: dev_app
Senha: dev123456

Acessar PostgreSQL:

# Via Docker
docker exec -it shared-postgres psql -U dev_app -d devdb

# Via linha de comando (se PostgreSQL estiver instalado)
psql -h localhost -U dev_app -d devdb

# Dentro de um projeto (usando variáveis do .env)
export PGPASSWORD=dev123456
psql -h localhost -U dev_app -d devdb

Criar Schema para Projeto:

docker exec -it shared-postgres psql -U dev_app -d devdb -c \
  "CREATE SCHEMA IF NOT EXISTS proj_meuprojeto;"

Listar Schemas:

docker exec -it shared-postgres psql -U dev_app -d devdb -c "\dn"

Backup do Banco:

# Criar backup
docker exec shared-postgres pg_dump -U dev_app devdb > backup_$(date +%Y%m%d).sql

# Restaurar backup
docker exec -i shared-postgres psql -U dev_app -d devdb < backup_20260309.sql

MinIO (Object Storage S3-Compatible)

Dados de Acesso:

Endpoint: http://<IP-DA-VPS>:9000
Console:  http://<IP-DA-VPS>:9001
Access Key: minioadmin
Secret Key: minio123456

Acessar Console Web:

Abra no navegador: http://<IP-DA-VPS>:9001
Login: minioadmin / minio123456

Usando MinIO Client (mc):

# Adicionar endpoint
docker run --rm --network infra_dev-network \
  minio/mc:latest alias set dev http://shared-minio:9000 minioadmin minio123456

# Listar buckets
docker run --rm --network infra_dev-network minio/mc:latest ls dev

# Criar bucket
docker run --rm --network infra_dev-network minio/mc:latest mb dev/meu-bucket

# Upload de arquivo
docker run --rm --network infra_dev-network \
  minio/mc:latest cp /caminho/do/arquivo.txt dev/meu-bucket/

# Download de arquivo
docker run --rm --network infra_dev-network \
  minio/mc:latest cp dev/meu-bucket/arquivo.txt /caminho/local/

# Deletar bucket
docker run --rm --network infra_dev-network minio/mc:latest rm -r --force dev/meu-bucket

Redis

Dados de Conexão:

Host: localhost (ou shared-redis dentro da rede Docker)
Porta: 6379
Senha: redis123456

Acessar Redis CLI:

# Via Docker
docker exec -it shared-redis redis-cli -a redis123456

Comandos Úteis:

# Testar conexão
docker exec -it shared-redis redis-cli -a redis123456 PING

# Listar todas as chaves
docker exec -it shared-redis redis-cli -a redis123456 KEYS "*"

# Ver tipo de chave
docker exec -it shared-redis redis-cli -a redis123456 TYPE minha-chave

# Deletar chave
docker exec -it shared-redis redis-cli -a redis123456 DEL minha-chave

Criando Projetos

Método 1: Interativo (Recomendado)

/srv/scripts/novo-projeto.sh

O script fará as seguintes perguntas:

Nome do projeto: caixa
Frontend:
- 1. Vite + Vue.js
- 1. Next.js
- 1. Nenhum
Stack completa? (y/N) - Para usar infraestrutura própria

Método 2: Via Linha de Comando

# Projeto com Vite + Vue.js
/srv/scripts/novo-projeto.sh --nome=caixa --frontend=vite

# Projeto com Next.js
/srv/scripts/novo-projeto.sh --nome=financeiro --frontend=next

# Projeto sem frontend (apenas backend/API)
/srv/scripts/novo-projeto.sh --nome=api --frontend=none

# Projeto com infraestrutura própria
/srv/scripts/novo-projeto.sh --nome=estoque --stack-completa

O Que o Script Faz Automaticamente:

✅ Verifica se nome do projeto é válido
✅ Aloca portas disponíveis (frontend: 3000+, backend: 8000+)
✅ Cria estrutura de diretórios em /srv/projects/{nome}
✅ Cria schema no PostgreSQL: proj_{nome}
✅ Cria bucket no MinIO: proj-{nome}
✅ Gera configuração do Nginx para https://{nome}.dev.alav.cloud
✅ Cria arquivo .env com todas as variáveis de ambiente
✅ Cria project.conf com configurações do projeto
✅ Gera template Go backend (Gin framework)
✅ Gera template frontend (Vite ou Next.js)
✅ Recarrega Nginx automaticamente

Gerenciamento de Projetos

Listar Todos os Projetos

/srv/scripts/listar-projetos.sh

Saída de exemplo:

========================================
    PROJETOS CADASTRADOS
========================================

PROJETO              FRONTEND     FE_PORT    BE_PORT    DOMÍNIO
-------              --------     -------    -------    -------
caixa                vite         3000       8000       caixa.dev.alav.cloud
financeiro           next         3001       8001       financeiro.dev.alav.cloud
api                  none         -          8002       -

========================================
    PORTAS DISPONÍVEIS
========================================

TIPO            FAIXA      PRÓXIMA
----            -----      -------
frontend        3000-3099  3002
backend         8000-8099  8003
auxiliary       9000-9099  9000
postgres        5400-5499  5400
redis           6400-6499  6400
minio           9500-9599  9500

Remover Projeto

# Remover projeto (pede confirmação)
/srv/scripts/remover-projeto.sh caixa

# Remover sem confirmação
/srv/scripts/remover-projeto.sh caixa --force

# Remover mantendo dados (banco e bucket)
/srv/scripts/remover-projeto.sh caixa --keep-data

O que é removido:

✅ Diretório do projeto
✅ Configuração do Nginx
✅ Portas liberadas no registry
✅ Schema do PostgreSQL (a menos que --keep-data)
✅ Bucket do MinIO (a menos que --keep-data)

Estrutura de Diretórios

Visão Geral

/srv/
├── infra/                      # Infraestrutura compartilhada
│   ├── docker-compose.yml      # PostgreSQL, MinIO, Redis
│   ├── secrets/                # Credenciais dos serviços
│   └── init-scripts/           # Scripts de inicialização do DB
│
├── projects/                   # SEUS PROJETOS AQUI
│   └── {nome-do-projeto}/
│       ├── backend/            # Código Go (Gin)
│       ├── frontend/           # Código Frontend
│       ├── .env                # Variáveis de ambiente
│       ├── project.conf        # Configurações (JSON)
│       └── infra/              # (Opcional) Docker se stack-completa
│
├── nginx/
│   ├── docker-compose.yml      # Nginx em Docker
│   ├── nginx.conf              # Configuração principal
│   ├── sites/                  # Configs por projeto
│   ├── certs/                  # Certificados SSL
│   └── logs/                   # Logs do Nginx
│
├── scripts/                    # Scripts de Automação
│   ├── novo-projeto.sh
│   ├── listar-projetos.sh
│   ├── remover-projeto.sh
│   ├── allocate-port.sh
│   └── setup-ssl.sh
│
├── ports.registry.json         # Controle de portas (JSON)
└── README.md                   # Documentação

Estrutura de um Projeto

/srv/projects/caixa/
├── backend/
│   ├── main.go                 # Ponto de entrada Go
│   ├── go.mod                  # Dependências Go
│   ├── handlers/               # Handlers HTTP
│   ├── models/                 # Modelos de dados
│   ├── services/               # Lógica de negócio
│   └── repositories/           # Acesso a dados
│
├── frontend/
│   ├── src/
│   │   ├── App.vue
│   │   ├── main.js
│   │   ├── components/
│   │   └── views/
│   ├── package.json
│   ├── vite.config.js
│   └── index.html
│
├── .env                        # Variáveis de ambiente
├── project.conf                # Configurações do projeto
└── README.md                   # Documentação do projeto

Configuração de Portas

Faixas de Portas

Tipo	Faixa	Uso	Exemplo
Frontend	3000-3099	Dev server Vite/Next.js	3000, 3001, 3002
Backend	8000-8099	Servidor HTTP Go	8000, 8001, 8002
Auxiliar	9000-9099	Workers, WebSockets	9000, 9001
PostgreSQL	5400-5499	DB dedicado (stack completa)	5400, 5401
Redis	6400-6499	Redis dedicado (stack completa)	6400, 6401
MinIO	9500-9599	MinIO dedicado (stack completa)	9500, 9501

Alocar Porta Manualmente

# Sintaxe
/srv/scripts/allocate-port.sh <tipo> <nome-projeto>

# Exemplos
/srv/scripts/allocate-port.sh frontend meuapp
# Retorna: 3002

/srv/scripts/allocate-port.sh backend meuapp
# Retorna: 8002

Nginx e Domínios

Configuração de Domínio Wildcard

Para que os subdomínios funcionem, configure o DNS:

Tipo: A
Nome: *.dev
Valor: <IP-DA-VPS>

Tipo: A
Nome: @
Valor: <IP-DA-VPS>

Comandos Úteis do Nginx

# Testar configuração
docker exec dev-nginx nginx -t

# Recarregar configuração
docker exec dev-nginx nginx -s reload

# Ver logs
docker logs dev-nginx -f

# Reiniciar Nginx
docker restart dev-nginx

SSL Wildcard

Obter certificado:

# 1. Verificar se DNS está configurado
dig caixa.dev.alav.cloud

# 2. Executar Certbot
certbot certonly --manual --preferred-challenges dns \
  -d dev.alav.cloud -d '*.dev.alav.cloud' \
  --email admin@alav.cloud --agree-tos

# 3. Copiar certificados
cp /etc/letsencrypt/live/dev.alav.cloud/*.pem /srv/nginx/certs/

# 4. Recarregar Nginx
docker restart dev-nginx

Script de setup:

/srv/scripts/setup-ssl.sh

Banco de Dados

Estrutura de Schemas

PostgreSQL (devdb)
├── schema: public (padrão)
├── schema: proj_caixa
├── schema: proj_financeiro
└── schema: proj_estoque

Conectar ao Banco

# Via Docker
docker exec -it shared-postgres psql -U dev_app -d devdb

# Com PGPASSWORD
export PGPASSWORD=dev123456
psql -h localhost -U dev_app -d devdb

Variáveis de Ambiente (.env)

# PostgreSQL
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=devdb
POSTGRES_USER=dev_app
POSTGRES_PASSWORD=dev123456
POSTGRES_SCHEMA=proj_caixa

Object Storage (MinIO)

Acessar Console Web

Navegador: http://<IP-DA-VPS>:9001
Login: minioadmin / minio123456

Operações via MinIO Client

# Configurar alias
docker run --rm --network infra_dev-network \
  minio/mc:latest alias set dev http://shared-minio:9000 minioadmin minio123456

# Listar buckets
docker run --rm --network infra_dev-network minio/mc:latest ls dev

# Criar bucket
docker run --rm --network infra_dev-network minio/mc:latest mb dev/proj-caixa

# Upload
docker run --rm --network infra_dev-network \
  minio/mc:latest cp arquivo.txt dev/proj-caixa/

# Listar conteúdo
docker run --rm --network infra_dev-network minio/mc:latest ls dev/proj-caixa

Redis

Comandos Básicos

# Acessar CLI
docker exec -it shared-redis redis-cli -a redis123456

# Testar conexão
docker exec -it shared-redis redis-cli -a redis123456 PING
# Resposta: PONG

# Set/Get
docker exec -it shared-redis redis-cli -a redis123456 SET minha-chave "valor"
docker exec -it shared-redis redis-cli -a redis123456 GET minha-chave

# Listar chaves
docker exec -it shared-redis redis-cli -a redis123456 KEYS "*"

Scripts de Automação

novo-projeto.sh

Localização: /srv/scripts/novo-projeto.sh

# Interativo
/srv/scripts/novo-projeto.sh

# Com argumentos
/srv/scripts/novo-projeto.sh --nome=caixa --frontend=vite

Opções: - --nome=NAME - Nome do projeto - --frontend=TYPE - Tipo: vite, next, none - --stack-completa - Usar infraestrutura própria

listar-projetos.sh

Localização: /srv/scripts/listar-projetos.sh

/srv/scripts/listar-projetos.sh

remover-projeto.sh

Localização: /srv/scripts/remover-projeto.sh

# Com confirmação
/srv/scripts/remover-projeto.sh caixa

# Sem confirmação
/srv/scripts/remover-projeto.sh caixa --force

# Manter dados
/srv/scripts/remover-projeto.sh caixa --keep-data

Segurança

Firewall (UFW)

Status:

ufw status verbose

Portas liberadas:

Porta	Serviço	Acesso
22	SSH	Público
80	HTTP	Público
443	HTTPS	Público
4096	Opencode Web	Público

Usuário `dev`

# Criar senha
passwd dev

# Acessar
su - dev

# Permissões:
# - Sudo sem senha
# - Grupo docker
# - Acesso a /srv/projects

Troubleshooting

Nginx não carrega

# Testar configuração
docker exec dev-nginx nginx -t

# Ver logs
docker logs dev-nginx

# Recarregar
docker exec dev-nginx nginx -s reload

# Reiniciar
docker restart dev-nginx

Projeto não acessa banco de dados

# Verificar se PostgreSQL está rodando
docker ps | grep postgres

# Testar conexão
docker exec -it shared-postgres psql -U dev_app -d devdb -c "SELECT 1;"

# Verificar schema existe
docker exec -it shared-postgres psql -U dev_app -d devdb -c "\dn"

# Verificar .env do projeto
cat /srv/projects/{nome}/.env | grep POSTGRES

Porta já em uso

# Verificar o que está usando a porta
netstat -tlnp | grep :8000

# Ver portas alocadas no registry
cat /srv/ports.registry.json | jq '.allocations[] | select(.port == 8000)'

SSL não funciona

# Verificar se certificado existe
ls -la /srv/nginx/certs/

# Renovar certificado
certbot renew

# Recarregar Nginx
docker restart dev-nginx

Redis não conecta

# Verificar se está rodando
docker ps | grep redis

# Testar conexão
docker exec -it shared-redis redis-cli -a redis123456 PING

# Reiniciar
docker restart shared-redis

Comandos Úteis

Docker

# Listar containers
docker ps

# Ver logs
docker logs <container> -f

# Reiniciar container
docker restart <container>

# Ver uso de recursos
docker stats

Docker Compose

# Iniciar serviços
cd /srv/infra && docker compose up -d

# Parar serviços
cd /srv/infra && docker compose down

# Ver status
cd /srv/infra && docker compose ps

# Ver logs
cd /srv/infra && docker compose logs -f

Sistema

# Ver uso de CPU/Memória
htop

# Ver uso de disco
df -h

# Ver portas em uso
netstat -tlnp

# Reiniciar VPS
reboot

Logs

# Nginx
docker logs dev-nginx -f

# PostgreSQL
docker logs shared-postgres -f

# MinIO
docker logs shared-minio -f

# Redis
docker logs shared-redis -f

Fluxo de Trabalho Recomendado

1. Criar Novo Projeto

ssh dev@<IP-VPS>
/srv/scripts/novo-projeto.sh --nome=meuapp --frontend=vite
cd /srv/projects/meuapp

2. Desenvolver Backend

cd backend
go mod tidy
BACKEND_PORT=8002 go run main.go

3. Desenvolver Frontend

cd ../frontend
npm install
npm run dev

4. Testar

# Backend
curl http://localhost:8002/health

# Frontend
curl http://localhost:3002

# Via domínio
curl https://meuapp.dev.alav.cloud
curl https://meuapp.dev.alav.cloud/api/health

Referências

Última atualização: 2026-03-09
Versão: 1.0.0
Manutenção: Equipe de Infraestrutura

🚀 Ambiente de Desenvolvimento Fullstack - Documentação Completa

📋 Índice

Visão Geral

O Que É Este Ambiente?

Stack Tecnológica

Arquitetura

Acesso ao Ambiente

1. Acesso SSH

2. Usuários Disponíveis

3. Criar Senha para Usuário dev

4. Acessar como dev

Serviços Compartilhados

PostgreSQL

MinIO (Object Storage S3-Compatible)

Redis

Criando Projetos

Método 1: Interativo (Recomendado)

Método 2: Via Linha de Comando

O Que o Script Faz Automaticamente:

Gerenciamento de Projetos

Listar Todos os Projetos

Remover Projeto

Estrutura de Diretórios

Visão Geral

Estrutura de um Projeto

Configuração de Portas

Faixas de Portas

Alocar Porta Manualmente

Nginx e Domínios

Configuração de Domínio Wildcard

Comandos Úteis do Nginx

SSL Wildcard

Banco de Dados

Estrutura de Schemas

Conectar ao Banco

Variáveis de Ambiente (.env)

Object Storage (MinIO)

Acessar Console Web

Operações via MinIO Client

Redis

Comandos Básicos

Scripts de Automação

novo-projeto.sh

listar-projetos.sh

remover-projeto.sh

Segurança

Firewall (UFW)

Usuário dev

Troubleshooting

Nginx não carrega

Projeto não acessa banco de dados

Porta já em uso

SSL não funciona

Redis não conecta

Comandos Úteis

Docker

Docker Compose

Sistema

Logs

Fluxo de Trabalho Recomendado

1. Criar Novo Projeto

2. Desenvolver Backend

3. Desenvolver Frontend

4. Testar

Referências

3. Criar Senha para Usuário `dev`

4. Acessar como `dev`

Usuário `dev`