================================================================================
                        VPS ARDUMAKER - GUÍA COMPLETA
                    Para Sistemas Externos y Agentes de IA
================================================================================

VERSIÓN: 1.0
FECHA: 13 de febrero de 2026
PROPÓSITO: Guía completa para comprender y gestionar VPS en ArduMaker

URL Base de la plataforma: https://ardumaker.com

================================================================================
¿QUÉ ES UN VPS EN ARDUMAKER?
================================================================================

Los VPS son instancias LXD ejecutándose en un host dedicado.

Características principales:
  ✓ Todos los puertos cerrados por defecto (seguridad máxima)
  ✓ Diseñados para desarrollo web (freelancers, equipos, empresas)
  ✓ Interfaz gráfica simple + acceso SSH completo
  ✓ Cada compañía tiene sus VPS aislados y separados
  ✓ Deploy automático desde Git con compilación personalizable
  ✓ SSL automático incluido sin configuración adicional
  ✓ No se permiten Docker ni virtualizaciones internas

Ideal para:
  - Freelancers que gestionan múltiples clientes/empresas
  - Equipos que necesitan deploy rápido y colaborativo
  - Proyectos web de cualquier lenguaje o framework

================================================================================
CREAR UN VPS
================================================================================

Pasos:
  1. Ve a https://ardumaker.com/dashboard?tab=vps
  2. Haz clic en "Crear VPS"
  3. Selecciona el plan (CPU, RAM, almacenamiento)
  4. Espera unos minutos mientras se provisiona

Resultado:
  - VPS activo con Ubuntu
  - Acceso a internet habilitado
  - Sin puertos públicos abiertos (por seguridad)
  - Cada miembro de la compañía obtiene un usuario Linux automático
  - Por defecto los usuarios NO tienen sudo

================================================================================
ESTRUCTURA DEL VPS - PESTAÑAS
================================================================================

Al entrar al VPS (/vps/:id) encontrarás estas pestañas:

  1. Status        → Consumo de recursos y control de encendido
  2. Deploy        → Vincular repositorios Git y desplegar proyectos
  3. Servicios     → Instalar PostgreSQL, MySQL, N8N
  4. Terminal      → Terminal bash en el navegador
  5. Puertos       → Gestión de puertos, dominios y redirecciones
  6. Configuración → Usuarios, accesos, historial y zona de peligro

================================================================================
PESTAÑA 1: STATUS
================================================================================

Muestra el estado general del VPS en tiempo real:
  - Uso de CPU
  - Uso de RAM
  - Uso de disco
  - Estado: Activo / Apagado / Error

Acciones disponibles:
  - Reiniciar el VPS
  - Apagar el VPS
  - Encender el VPS
  - Cambiar de plan

IMPORTANTE:
  Apagar el VPS NO exime de pagos mensuales.
  El VPS sigue existiendo y generando costos aunque esté apagado.
  Para dejar de pagar, debes ELIMINAR el VPS desde Configuración.

================================================================================
PESTAÑA 2: DEPLOY (Despliegue desde Git)
================================================================================

Permite vincular repositorios Git al VPS para deploy automático.

Funcionamiento:
  1. Asocias un repositorio Git con una rama específica
  2. Cada nuevo commit en esa rama dispara un deploy automático
  3. El bot (Ardumaker_bot) ejecuta las acciones configuradas

Puedes tener:
  - Múltiples repositorios en un mismo VPS
  - Un mismo repositorio con diferentes ramas
  - Proyectos de cualquier lenguaje (Node, Python, PHP, Go, etc.)

────────────────────────────────────────────────────────────────────────────────
DEPLOY → Sub-pestaña: Info
────────────────────────────────────────────────────────────────────────────────

Historial de operaciones:
  - Lista de todas las operaciones ejecutadas sobre el deploy
  - Cada commit dispara: Ardumaker_bot ejecuta las acciones programadas
  - Puedes ver los scripts que el bot o cualquier persona ejecutaron

Flujo por defecto de cada deploy:
  1. script-prepull    (acciones antes del git pull)
  2. git pull          (descarga los cambios)
  3. script-postpull   (compilación y preparación)
  4. Reinicio de servicios asociados (si los hay)

Historial de commits:
  - Muestra solo los commits que llegaron vía webhook
  - Si el webhook falló, el commit no aparece en el historial
  - Esto NO significa que el commit no exista en el VPS

────────────────────────────────────────────────────────────────────────────────
DEPLOY → Sub-pestaña: Compilación
────────────────────────────────────────────────────────────────────────────────

Configuración de scripts pre-pull y post-pull.

Pre-pull (antes del git pull):
  Por defecto: git checkout .
  Propósito: Evitar conflictos con cambios locales

Post-pull (después del git pull):
  Propósito: Compilar y preparar el proyecto para ejecución

⚠️  REGLA CRÍTICA: Los scripts DEBEN TERMINAR
  - NO son para ejecutar servidores ni servicios permanentes
  - SOLO para compilar y preparar
  - Timeout: 300 segundos (5 minutos), luego se mata con kill
  - La ejecución de servidores va en la sub-pestaña "Servicio"

Ejemplo para proyecto Vite/React:
──────────────────────────────────
  npm install
  npm run build
  echo "🚀 Post-pull completed successfully"

Ejemplo para proyecto Python:
──────────────────────────────
  set -e
  python3 -m venv venv
  source ./venv/bin/activate
  pip install --upgrade pip
  if [ -f "requirements.txt" ]; then
      pip install -r requirements.txt --upgrade
  fi
  echo "🚀 Post-pull completed successfully"

────────────────────────────────────────────────────────────────────────────────
DEPLOY → Sub-pestaña: Servicio (systemd)
────────────────────────────────────────────────────────────────────────────────

Aquí se crea un servicio systemd para EJECUTAR el proyecto.

  - Se ejecuta en la misma carpeta del repositorio clonado
  - Este es el lugar para ejecutar servidores y procesos permanentes

Ejemplos de comandos de ejecución:

  Python (Gunicorn):
    /home/github/proyecto/venv/bin/gunicorn --workers 4 --bind 127.0.0.1:8040 config.wsgi:application

  Node.js:
    npm run start

IMPORTANTE:
  - La compilación va en "Compilación" (post-pull)
  - La ejecución del servidor va aquí en "Servicio"
  - No mezclar compilación con ejecución

────────────────────────────────────────────────────────────────────────────────
DEPLOY → Sub-pestaña: Puertos y Dominios
────────────────────────────────────────────────────────────────────────────────

Si tu proyecto es web, aquí lo publicas bajo un dominio.

Opciones de dominio:
  A) Crear un subdominio: xxx.arducloud.com
  B) Usar tu propio dominio: apuntando DNS a la IP del host

Flujo automático al asociar un dominio:
  1. Creas o apuntas el dominio
  2. Se tramita SSL automáticamente (HTTPS incluido)
  3. El tráfico llega al puerto 4430 de tu VPS
  4. Configuras Nginx para servir tu proyecto

⚠️  REGLA DE ARQUITECTURA: Todo el tráfico web llega al puerto 4430

El host se encarga del SSL, tu VPS NO necesita certificados.
Lo que llega al puerto 4430 ya es una solicitud válida (sin SSL).

Configuración Nginx - SIEMPRE inicia con:
──────────────────────────────────────────

  server {
      listen 4430;
      listen [::]:4430;
      server_name tu-dominio.com;
      access_log /var/log/nginx/tu-dominio.com_access.log;
      error_log /var/log/nginx/tu-dominio.com_error.log;

      # ... tu configuración aquí ...
  }

Ejemplo Nginx para proyecto estático (Vite/React):
───────────────────────────────────────────────────

  server {
      listen 4430;
      listen [::]:4430;
      server_name mi-app.arducloud.com;
      access_log /var/log/nginx/mi-app_access.log;
      error_log /var/log/nginx/mi-app_error.log;

      root /home/github/mi-proyecto/dist;
      index index.html;

      location / {
          try_files $uri $uri/ /index.html;
      }

      location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
          expires 1y;
          add_header Cache-Control "public, immutable";
      }
  }

Ejemplo Nginx para proyecto con servidor backend:
──────────────────────────────────────────────────

  server {
      listen 4430;
      listen [::]:4430;
      server_name api.mi-dominio.com;
      access_log /var/log/nginx/api_access.log;
      error_log /var/log/nginx/api_error.log;

      client_max_body_size 100M;

      location / {
          proxy_pass http://127.0.0.1:8000;
          proxy_http_version 1.1;
          proxy_set_header Upgrade $http_upgrade;
          proxy_set_header Connection 'upgrade';
          proxy_set_header Host $host;
          proxy_set_header X-Real-IP $remote_addr;
          proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
          proxy_set_header X-Forwarded-Proto $scheme;
          proxy_cache_bypass $http_upgrade;
          proxy_read_timeout 86400;
          proxy_send_timeout 86400;
      }

      location /webhook/ {
          proxy_pass http://127.0.0.1:8000;
          proxy_http_version 1.1;
          proxy_set_header Host $host;
          proxy_set_header X-Real-IP $remote_addr;
          proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
          proxy_set_header X-Forwarded-Proto $scheme;
      }
  }

Un mismo deploy puede tener varios dominios apuntando a él.

────────────────────────────────────────────────────────────────────────────────
DEPLOY → Sub-pestaña: Logs
────────────────────────────────────────────────────────────────────────────────

Muestra los logs del deploy:
  - Logs de acceso/error de los dominios (Nginx)
  - Journal del servicio systemd asociado

Equivalente a ejecutar:
  cat /var/log/nginx/dominio_access.log
  journalctl -u servicio.service

================================================================================
PESTAÑA 3: SERVICIOS
================================================================================

Servicios disponibles para instalar:
  - PostgreSQL (base de datos relacional)
  - MySQL (base de datos relacional)
  - N8N (automatización de workflows)

Instalación:
  1. Haz clic en "Instalar" en el servicio deseado
  2. Espera varios minutos mientras se instala
  3. Si falla, reintenta (se actualiza y/o completa)
  4. Si muestra un log de error, hay que solucionarlo por terminal/SSH

────────────────────────────────────────────────────────────────────────────────
SERVICIO: N8N
────────────────────────────────────────────────────────────────────────────────

Después de instalar N8N:
  - Estado del servicio (activo/inactivo)
  - Puertos y datos de conexión
  - Usuarios y procesos
  - Variables de entorno (CRUD completo)
  - Asociar un dominio para hacerlo público

Por defecto:
  N8N solo es accesible localmente dentro del VPS.
  Al asociar un dominio, queda público en esa URL.

────────────────────────────────────────────────────────────────────────────────
SERVICIO: PostgreSQL / MySQL
────────────────────────────────────────────────────────────────────────────────

Después de instalar la base de datos:
  - Puerto local disponible (solo accesible desde localhost del VPS)
  - Opción de hacerla PÚBLICA (expone TCP con IP y puerto público)

⚠️  Hacer pública una base de datos la expone 100% por TCP.
    Asegúrate de tener contraseñas seguras.

Funciones de gestión:

  Bases de datos:
    - Listar bases de datos
    - Ver tablas de cada base de datos
    - Ver los últimos 5 registros de cada tabla

  Usuarios:
    - CRUD completo de usuarios de la BD
    - Crear, editar, eliminar usuarios

  Permisos:
    - Asignar permisos de un usuario sobre una base de datos específica
    - Control granular de acceso

Protección del sistema:
  - No se pueden eliminar usuarios por defecto (root, postgres, mysql)
  - No se pueden eliminar bases de datos del sistema

================================================================================
PESTAÑA 4: TERMINAL
================================================================================

Terminal bash directa en el navegador:
  - Se ejecuta con tu usuario Linux asignado
  - Acceso inmediato sin configuración

SSH externo:
  - Puedes habilitar el puerto SSH (22)
  - Se mantiene abierto por 12 horas máximo
  - Luego se cierra automáticamente por seguridad

Contraseña por defecto:
  - La contraseña de todos los usuarios es el SLUG del VPS
  - El slug aparece debajo del nombre del VPS, junto a la IP
  - Es un string alfanumérico de 6 a 10 caracteres
  - Puedes cambiar contraseñas desde Configuración

================================================================================
PESTAÑA 5: PUERTOS Y DOMINIOS
================================================================================

Gestión centralizada de toda la red del VPS:

  Dominios:
    - Listado de todos los dominios conectados
    - A qué deploy pertenece cada dominio
    - Crear subdominios xxx.arducloud.com
    - Asociar dominios propios

  Redirecciones:
    - TCP y UDP personalizadas
    - Habilitar/deshabilitar SSH

  Reglas de subdominios arducloud.com:
    - Máximo 16 caracteres
    - Solo letras a-z
    - Mínimo 3 letras por segmento
    - Sin palabras prohibidas

================================================================================
PESTAÑA 6: CONFIGURACIÓN
================================================================================

Historial de actividad:
  - Registro completo de todas las acciones realizadas en el VPS

Usuarios del sistema Linux:
  - Ver todos los usuarios
  - Asignar/quitar sudo
  - Cambiar contraseñas
  - Cada miembro de la compañía tiene su usuario automático

Control de acceso:
  - Restringir qué miembros de la compañía pueden ver/gestionar el VPS
  - Listas de usuarios permitidos y excluidos

Administración:
  - Cambiar nombre del VPS
  - Transferir a otra compañía (requiere ser admin en ambas)

Zona de peligro:
  - Eliminar el VPS
  - ⚠️  La eliminación es PERMANENTE, sin respaldo de datos

================================================================================
FLUJO COMPLETO DE DEPLOY
================================================================================

1. CREAR VPS
────────────
  Ve a https://ardumaker.com/dashboard?tab=vps
  Selecciona plan → Espera creación → VPS activo

2. VINCULAR REPOSITORIO
────────────────────────
  Pestaña Deploy → Agregar repo Git → Seleccionar rama
  El webhook se configura automáticamente

3. CONFIGURAR COMPILACIÓN
──────────────────────────
  Sub-pestaña Compilación → Configurar post-pull script
  Ejemplo: npm install && npm run build

4. CONFIGURAR SERVICIO
───────────────────────
  Sub-pestaña Servicio → Crear systemd
  Ejemplo: npm run start (si es un servidor)
  Nota: Para sitios estáticos (Vite/React), no necesitas servicio

5. ASOCIAR DOMINIO
───────────────────
  Sub-pestaña Puertos → Crear dominio o apuntar DNS
  SSL se tramita automáticamente

6. CONFIGURAR NGINX
─────────────────────
  Terminal → Editar /etc/nginx/sites-available/tu-dominio.conf
  Recordar: Todo escucha en puerto 4430
  sudo nginx -t && sudo systemctl reload nginx

7. LISTO
────────
  Tu proyecto está desplegado y accesible por HTTPS
  Cada nuevo commit en la rama configurada redespliega automáticamente

================================================================================
RESUMEN DE ARQUITECTURA DE RED
================================================================================

  Internet → DNS → Host (SSL) → Puerto 4430 del VPS → Nginx → Tu app

  - El host gestiona los certificados SSL
  - Tu VPS recibe tráfico limpio en el puerto 4430
  - Nginx dentro del VPS decide qué servir
  - Puedes tener múltiples dominios, todos llegan al 4430
  - Nginx diferencia por server_name

================================================================================
RESTRICCIONES Y LÍMITES
================================================================================

  ✗ No se permite Docker
  ✗ No se permiten virtualizaciones internas
  ✗ Scripts de compilación: máximo 300 segundos (5 min)
  ✗ SSH se cierra automáticamente después de 12 horas
  ✗ Apagar el VPS NO cancela el cobro mensual

  ✓ Acceso completo como contenedor Linux (Ubuntu)
  ✓ Instalar paquetes con apt (si tienes sudo)
  ✓ Múltiples proyectos en un mismo VPS
  ✓ Múltiples dominios por VPS
  ✓ SSL automático e incluido
  ✓ TODAS LAS CONTRASENHAS POR DEFAULT SON EL SLUG DEL VPS. Se ecuntra debajo del nombre junto con la ip.

================================================================================
RESUMEN PARA IMPLEMENTACIÓN RÁPIDA
================================================================================

  1. Crea un VPS en https://ardumaker.com/dashboard?tab=vps
  2. Vincula tu repositorio Git desde la pestaña Deploy
  3. Configura el script de compilación (post-pull)
  4. Si es un servidor, crea el servicio systemd
  5. Asocia un dominio desde Puertos
  6. Configura Nginx para escuchar en puerto 4430
  7. Cada commit en la rama configurada redespliega automáticamente

¡Eso es todo lo que necesitas para desplegar!

================================================================================