🚀 DevOps Items Management - Proyecto by RoxsRoss

Proyecto educativo de DevOps creado por roxsross para aprender conceptos fundamentales de desarrollo, contenedores, orquestación y monitoreo.

📸 Screenshots del Ecosistema ROXS

📦 Aplicación Principal	📋 Gestión de Items	📊 Prometheus Metrics	🏠 Grafana Home

Sistema de gestión de items con FastAPI + PostgreSQL	CRUD completo con items creados y funcionalidad de edición	Métricas de servicios en Prometheus	Panel de bienvenida de Grafana

📋 Dashboard List	🚀 Dashboard Principal	💾 Monitoreo Completo	🐳 Docker Containers

Lista de dashboards disponibles en Grafana	Dashboard principal con métricas de performance	Vista completa del monitoreo de DB e infraestructura	Stack completo ejecutándose en Docker

🎯 Descripción

Esta es una aplicación fullstack de gestión de items diseñada específicamente para aprender DevOps. Incluye:

Backend: API REST con FastAPI y PostgreSQL
Frontend: Interfaz web moderna con JavaScript vanilla
Contenedores: Todo dockerizado para facilitar el despliegue
Monitoreo: Stack completo con Prometheus y Grafana
Métricas: Instrumentación completa de la aplicación
Automatización: Makefile con comandos útiles

✨ Características Principales

✅ CRUD completo de items (Crear, Leer, Actualizar, Eliminar)
✅ Interfaz responsiva y moderna
✅ API documentada automáticamente con Swagger/OpenAPI
✅ Base de datos persistente con PostgreSQL
✅ Monitoreo en tiempo real con métricas personalizadas
✅ Dashboards visuales con Grafana
✅ Health checks y status de servicios
✅ Logs estructurados para debugging
✅ Fácil escalabilidad horizontal

🏗️ Arquitectura

┌─────────────────────────────────────────────────────────┐
│                    ARQUITECTURA DEL SISTEMA             │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐  │
│  │   Frontend  │────│   Backend   │────│  PostgreSQL │  │
│  │   (Nginx)   │    │  (FastAPI)  │    │     DB      │  │
│  │   Port 80   │    │  Port 3000  │    │  Port 5432  │  │
│  └─────────────┘    └─────────────┘    └─────────────┘  │
│         │                   │                           │
│         │                   │                           │
│  ┌─────────────────────────────────────────────────────┐│
│  │              STACK DE MONITOREO                     ││
│  │                                                     ││
│  │  ┌─────────────┐    ┌─────────────┐    ┌─────────┐  ││
│  │  │   Grafana   │────│ Prometheus  │────│   Node  │  ││
│  │  │ Port 3001   │    │  Port 9090  │    │Exporter │  ││
│  │  └─────────────┘    └─────────────┘    │Port 9100│  ││
│  │                                        └─────────┘  ││
│  └─────────────────────────────────────────────────────┘│
│                                                         │
└─────────────────────────────────────────────────────────┘

🔄 Flujo de Datos

Usuario → Frontend (Nginx) → Backend (FastAPI) → PostgreSQL
Métricas → Prometheus recolecta datos del Backend y Node Exporter
Visualización → Grafana consulta Prometheus para mostrar dashboards

📋 Requisitos

Requisitos Mínimos

Docker: 27+
Docker Compose: 2.34+
Make: Para usar el Makefile (opcional)
Sistema: Linux, macOS o Windows con WSL2

Requisitos de Hardware

RAM: 4GB mínimo (8GB recomendado)
Disco: 5GB libres
CPU: 2 cores mínimo

Verificar Requisitos

# Verificar Docker
docker --version
docker compose --version

# Verificar Make (opcional)
make --version

# Verificar recursos disponibles
docker system df

🚀 Instalación Rápida

Opción 1: Usando Makefile (Recomendado)

# 1. Clonar el repositorio
git clone https://github.com/roxsross/roxs-devops-stack
cd roxs-devops-stack

# 2. Preparar el entorno
make install

# 3. Levantar la aplicación
make up

# 4. Verificar que todo funciona
make health

# 5. Ver URLs disponibles
make urls

Opción 2: Usando Docker Compose Directamente

# 1. Crear redes necesarias
docker network create roxs-devops-network
docker network create roxs-monitoring-network

# 2. Levantar la aplicación
docker-compose up -d

# 3. Verificar servicios
docker-compose ps

🎯 Todo en Uno

# Levantar aplicación + monitoreo completo
make all

🎮 Uso

Comandos Principales

# Ver todos los comandos disponibles
make help

# Gestión de la aplicación
make up           # Levantar aplicación
make down         # Detener aplicación  
make restart      # Reiniciar aplicación
make logs         # Ver logs en tiempo real

# Monitoreo
make monitoring        # Levantar Prometheus + Grafana
make stop-monitoring   # Detener monitoreo
make monitoring-logs   # Ver logs del monitoreo

# Utilidades
make health       # Verificar salud de servicios
make status       # Ver estado de contenedores
make test         # Ejecutar tests básicos
make backup       # Backup de la base de datos

🌐 URLs de Acceso

Después de ejecutar make up y make monitoring:

Servicio	URL	Credenciales
Frontend	http://localhost	-
Backend API	http://localhost:3000	-
API Docs	http://localhost:3000/docs	-
Prometheus	http://localhost:9090	-
Grafana	http://localhost:3001	admin/admin

📱 Usando la Aplicación

Accede al Frontend: http://localhost
Crea tu primer item:
- Nombre: "Mi primer item"
- Descripción: "Esta es una prueba"
- Haz clic en "Crear Item"
Ve la lista actualizada automáticamente
Edita o elimina items usando los botones de cada card

📊 Monitoreo

Dashboard de Grafana

El dashboard incluye:

🚀 Estado General: Status de todos los servicios
🔧 Performance del Backend: RPS, latencia, errores
💾 Base de Datos: Conexiones, total de items
🖥️ Infraestructura: CPU, memoria del servidor
📈 Rankings: Top endpoints, errores más frecuentes

Métricas Disponibles

Métrica	Descripción
`http_requests_total`	Total de requests HTTP
`http_request_duration_seconds`	Latencia de requests
`database_items_total`	Total de items en BD
`database_status`	Estado de conexión a BD
`app_uptime_seconds`	Tiempo de actividad

Alertas Configuradas

❌ Servicio caído
⚠️ Latencia > 500ms
🚨 Error rate > 5%
💾 BD desconectada

📚 API Documentation

Endpoints Principales

Método	Endpoint	Descripción
`GET`	`/`	Información de la API
`GET`	`/health`	Health check
`GET`	`/metrics`	Métricas de Prometheus
`GET`	`/items`	Listar todos los items
`POST`	`/items`	Crear nuevo item
`GET`	`/items/{id}`	Obtener item por ID
`PUT`	`/items/{id}`	Actualizar item
`DELETE`	`/items/{id}`	Eliminar item

Ejemplos de Uso

# Listar items
curl http://localhost:3000/items

# Crear item
curl -X POST http://localhost:3000/items \
  -H "Content-Type: application/json" \
  -d '{"name": "Laptop", "description": "MacBook Pro 16"}'

# Health check
curl http://localhost:3000/health

Documentación Interactiva

Visita http://localhost:3000/docs para explorar la API de forma interactiva con Swagger UI.

📁 Estructura del Proyecto

.
├── app/
│   ├── backend/                 # Backend FastAPI
│   │   ├── Dockerfile          # Imagen del backend
│   │   ├── main.py             # Aplicación principal
│   │   └── requirements.txt    # Dependencias Python
│   └── frontend/               # Frontend estático
│       ├── css/
│       │   └── styles.css      # Estilos CSS
│       ├── js/
│       │   ├── app.js          # Lógica principal
│       │   └── config.js       # Configuración
│       ├── index.html          # Página principal
│       ├── default.conf        # Configuración Nginx
│       └── Dockerfile          # Imagen del frontend
├── monitoring/                 # Stack de monitoreo
│   ├── grafana/
│   │   ├── dashboards/
│   │   │   └── simple-dashboard.json
│   │   └── provisioning/
│   │       ├── dashboards/
│   │       │   └── dashboards.yml
│   │       └── datasources/
│   │           └── datasources.yml
│   └── prometheus/
│       └── prometheus.yml      # Configuración Prometheus
├── docker-compose.yml          # Aplicación principal
├── docker-compose.monitoring.yml # Stack de monitoreo
├── Makefile                    # Comandos automatizados
└── README.md                   # Esta documentación

🛠️ Tecnologías

Backend

FastAPI: Framework web moderno y rápido
SQLAlchemy: ORM para Python
PostgreSQL: Base de datos relacional
Prometheus Client: Métricas y monitoreo
Uvicorn: Servidor ASGI

Frontend

HTML5/CSS3: Estructura y estilos
JavaScript ES6+: Lógica del cliente
Nginx: Servidor web estático

DevOps

Docker: Contenedores
Docker Compose: Orquestación
Prometheus: Recolección de métricas
Grafana: Visualización de datos
Node Exporter: Métricas del sistema

Características DevOps

Multi-stage builds: Optimización de imágenes
Health checks: Verificación de servicios
Logging estructurado: Para troubleshooting
Configuración por variables: 12-factor app
Persistencia de datos: Volúmenes Docker

🔧 Troubleshooting

Problemas Comunes

❌ Error: "network not found"

# Solución: Crear las redes manualmente
make install
# o
docker network create roxs-devops-network
docker network create roxs-monitoring-network

❌ Error: "port already in use"

# Ver qué proceso usa el puerto
sudo lsof -i :80
sudo lsof -i :3000

# Cambiar puertos en variables de entorno
export FRONTEND_PORT=8080
export BACKEND_PORT=3001
make up

❌ Backend no conecta a la BD

# Verificar logs de la BD
make logs-db

# Verificar logs del backend
make logs-backend

# Reiniciar servicios
make restart

❌ Grafana no muestra datos

# Verificar que Prometheus esté activo
curl http://localhost:9090

# Verificar métricas del backend
curl http://localhost:3000/metrics

# Reiniciar monitoreo
make stop-monitoring
make monitoring

Comandos de Diagnóstico

# Estado general
make status
make health

# Logs específicos
make logs-backend
make logs-frontend  
make logs-db

# Información del sistema
make info

# Test de conectividad
make test

Limpiar y Reiniciar

# Limpiar recursos
make clean

# Limpiar todo (incluyendo imágenes)
make clean-all

# Reconstruir desde cero
make clean
make build
make up

🤝 Contribuir

Para Contribuir

Fork el repositorio
Crea una rama para tu feature (git checkout -b feature/nueva-funcionalidad)
Commit tus cambios (git commit -am 'Agregar nueva funcionalidad')
Push a la rama (git push origin feature/nueva-funcionalidad)
Crea un Pull Request

Desarrollo Local

# Modo desarrollo (rebuild automático)
make dev

# Acceder a contenedores
make exec-backend
make exec-frontend
make exec-db

✅ Despliegue Local - Ya completado con Docker Compose

📋 TODO List - Próximos Pasos

🔄 CI/CD Pipeline

GitHub Actions
Security Scanning
Automated Deployment
Rollback Strategy

☸️ Kubernetes Deployment

Helm Charts
Kubernetes Manifests
Persistent Volumes

🔄 ArgoCD - GitOps

ArgoCD Setup
Application Sets
GitOps Workflow

🔧 Tooling & Automation

... y Mucho más

📖 Recursos Adicionales

Documentación

Tutoriales DevOps

📄 Licencia

Este proyecto está licenciado bajo MIT License - ver el archivo LICENSE para detalles.

👨‍💻 Autor

roxsross - Instructor DevOps y Cloud

🐦 Twitter: @roxsross
🔗 LinkedIn: roxsross
☕ Ko-fi roxsross
▶️ Youtube 295devops
📧 Email: [email protected]

⭐ ¡Dale una estrella si este proyecto te ayudó! ⭐

💡 Tip: Este proyecto está diseñado para fines educativos. Úsalo para aprender DevOps, contenedores, y monitoreo.

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
app		app
docs/images		docs/images
monitoring		monitoring
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
docker-compose.monitoring.yml		docker-compose.monitoring.yml
docker-compose.yml		docker-compose.yml

License

roxsross/roxs-devops-stack

Folders and files

Latest commit

History

Repository files navigation