NebulOus - Cloud Platform

NebulOus es una plataforma de orquestación de clusters en la nube que permite gestionar clusters Docker Swarm en AWS y GCP de manera sencilla y visual.

Comment

NebulOus - Cloud Orchestration Platform

NebulOus es una plataforma de orquestación de clusters en la nube que permite gestionar clusters Docker Swarm en AWS y GCP de manera sencilla y visual.

🔗 Repositorio

https://github.com/aiuoki/NebulOus

📋 Características

  • 🚀 Creación automatizada de clusters Docker Swarm
  • ☁️ Soporte para AWS y GCP
  • 🔄 Gestión de nodos (master y workers)
  • 📦 Despliegue de aplicaciones con Docker Compose
  • 🔐 Autenticación y gestión de usuarios
  • 💻 Interfaz web moderna y responsive

🛠️ Requisitos Previos

  • Python 3.9+
  • Node.js 16+
  • npm o yarn
  • Credenciales de AWS y/o GCP
  • Par de claves SSH (se generará automáticamente si no existe)

📁 Estructura del Proyecto

NebulOus/
├── backend/           # API FastAPI
│   ├── app/          # Código principal de la aplicación
│   ├── aws/          # Utilidades para AWS
│   ├── gcp/          # Utilidades para GCP
│   └── scripts/      # Scripts auxiliares
├── database/         # Módulo de base de datos SQLite
├── frontend/         # Aplicación React + TypeScript
├── config/           # Archivos de configuración
└── credentials/      # Credenciales (no incluido en git)

🚀 Instalación y Configuración

1. Configurar Credenciales

⚠️ IMPORTANTE: Los archivos de credenciales NO están incluidos en el repositorio por seguridad. Debes crearlos manualmente.

Crea la carpeta credentials/ en la raíz del proyecto:

mkdir credentials

📁 Estructura de la carpeta credentials/

credentials/
├── aws-credentials.json      # Credenciales de AWS
├── gcp-sa-key.json          # Service Account de GCP
├── master.key               # Clave privada SSH (se genera con ssh-keygen)
└── master.key.pub           # Clave pública SSH (se genera con ssh-keygen)

☁️ AWS Credentials (credentials/aws-credentials.json)

Crea este archivo con tus credenciales de AWS:

{
  "AWS_ACCESS_KEY_ID": "AKIAIOSFODNN7EXAMPLE",
  "AWS_SECRET_ACCESS_KEY": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}

Cómo obtener estas credenciales:

  1. Accede a la consola de AWS
  2. Ve a IAM → Users → Tu usuario
  3. Pestaña "Security credentials"
  4. Crea un nuevo Access Key

Permisos necesarios: EC2 Full Access

☁️ GCP Service Account (credentials/gcp-sa-key.json)

Descarga el archivo JSON de service account desde la consola de GCP:

  1. Ve a Google Cloud Console
  2. IAM & Admin → Service Accounts
  3. Crea o selecciona una Service Account
  4. Añade Key → Create new key → JSON
  5. Guarda el archivo descargado como credentials/gcp-sa-key.json

Permisos necesarios: Compute Engine Admin

El archivo tendrá este formato:

{
  "type": "service_account",
  "project_id": "tu-proyecto-id",
  "private_key_id": "...",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "tu-service-account@proyecto.iam.gserviceaccount.com",
  "client_id": "...",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "..."
}

🔑 Claves SSH

Genera un par de claves SSH para acceso a las instancias:

ssh-keygen -t rsa -b 4096 -f credentials/master.key -N ""

Esto creará automáticamente:

  • credentials/master.key (clave privada) - NO COMPARTIR
  • credentials/master.key.pub (clave pública)

⚠️ Importante: Asegúrate de que la clave privada tenga los permisos correctos:

chmod 600 credentials/master.key

2. Configurar Backend

# Navegar a la carpeta backend
cd backend

# Instalar dependencias de Python
pip3 install -r requirements.txt

3. Inicializar Base de Datos

# Desde la raíz del proyecto
cd database
python3 -c "from database_manager import init_db, create_default_user; init_db(); create_default_user()"

Esto creará:

  • La base de datos SQLite (database/nebulous.db)
  • Las tablas necesarias (users, clusters, nodes, applications)
  • Un usuario por defecto:
    • Username: dceban
    • Password: password123

4. Configurar Frontend

# Navegar a la carpeta frontend
cd frontend

# Instalar dependencias
npm install

5. Configuración Cloud (Opcional)

Edita config/cloud_config.json para ajustar:

  • Regiones de AWS/GCP
  • AMIs e imágenes de sistema operativo
  • Tipos de instancia disponibles
  • Security Groups (AWS)

▶️ Ejecución

Backend

cd backend
python3 -m uvicorn app.main:app --reload --port 8000

El backend estará disponible en: http://localhost:8000

Frontend

cd frontend
npm run dev

El frontend estará disponible en: http://localhost:5173

📝 Uso

  1. Acceder a la aplicación: Abre http://localhost:5173 en tu navegador
  2. Login: Usa las credenciales por defecto (dceban / password123)
  3. Crear Cluster:
    • Haz clic en "Create New Cluster"
    • Elige el proveedor (AWS o GCP)
    • Selecciona el tipo de instancia y almacenamiento
    • Espera a que se complete el despliegue
  4. Añadir Nodos Worker:
    • Entra en los detalles del cluster
    • Haz clic en "Add Worker Node"
    • Configura y despliega
  5. Desplegar Aplicaciones:
    • En los detalles del cluster, haz clic en "Deploy Application"
    • Proporciona un nombre y el archivo Docker Compose (YAML)
    • La aplicación se desplegará como un stack de Docker Swarm

🔧 Mantenimiento

Resetear Base de Datos

rm database/nebulous.db
cd database
python3 -c "from database_manager import init_db, create_default_user; init_db(); create_default_user()"

Ver Logs del Backend

Los logs se muestran en la terminal donde se ejecuta Uvicorn.

Regenerar Claves SSH

rm credentials/master.key credentials/master.key.pub
ssh-keygen -t rsa -b 4096 -f credentials/master.key -N ""

🐛 Solución de Problemas

Error: "No module named 'database'"

  • Asegúrate de ejecutar los comandos desde la raíz del proyecto
  • Verifica que database/ esté en el PYTHONPATH

Error: "Unable to locate credentials" (AWS)

  • Verifica que credentials/aws-credentials.json existe y tiene el formato correcto
  • Comprueba que las credenciales son válidas

Error: "Connection timeout" al acceder a aplicaciones

  • Verifica que los Security Groups permiten el tráfico en los puertos necesarios
  • Comprueba que los nodos están en estado "running"
  • Revisa los logs de Docker Swarm: ssh -i credentials/master.key ubuntu@<MASTER_IP> docker service logs <service_name>

Puerto 30008 (u otros NodePorts) no accesibles

  • Asegúrate de que el Security Group en AWS permite el rango de puertos 30000-32767
  • Ejecuta el script de actualización de Security Group si es necesario: bash python3 backend/scripts/update_sg.py

🔒 Seguridad

⚠️ ADVERTENCIA: Este proyecto está configurado para desarrollo. Para producción:

  • Cambia las credenciales por defecto
  • Usa variables de entorno en lugar de archivos JSON
  • Configura HTTPS/TLS
  • Restringe CORS en el backend
  • Implementa rate limiting
  • Usa secrets management (AWS Secrets Manager, GCP Secret Manager)

📚 Tecnologías Utilizadas

Backend

  • FastAPI: Framework web moderno y rápido
  • SQLite: Base de datos ligera
  • boto3: SDK de AWS para Python
  • google-cloud-compute: SDK de GCP
  • paramiko: Cliente SSH para Python

Frontend

  • React: Biblioteca de interfaz de usuario
  • TypeScript: JavaScript tipado
  • Vite: Build tool rápido
  • Lucide React: Iconos

Built With

Share this project:

Updates