Documentación de KuboRun

Ayuda para dar el siguiente paso.

Crea tu web, añade contenido y publica cuando esté lista. Encuentra respuestas a las dudas habituales y ayuda para los ajustes más avanzados.

¿Por dónde empiezo?

01 / Guía práctica

Qué tipo elegir

¿Quieres crear una web desde cero o publicar una aplicación que ya tienes? Elige el punto de partida que encaje contigo.

Catálogo de aplicaciones

Desde Añadir servicio puedes buscar PostgreSQL, MySQL, MariaDB, MongoDB, Redis, Valkey, n8n y otras aplicaciones. Elige versión y rellena sus datos específicos. Seleccionar prepara un borrador con imagen, puertos, volumen y recursos: revisa, guarda, completa los secretos y despliega. Las bases de datos quedan privadas; añade dominio a las aplicaciones web cuando lo necesites. Supabase crea 11 borradores privados y abre el primero, con avisos de configuración en cada servicio. Prepara sus archivos, arranque y claves antes de desplegar; no es una instalación automática. WordPress y Nextcloud preparan además un MySQL privado con volumen propio. Configura los secretos indicados antes de desplegar; las dos contraseñas de base de datos de WordPress deben coincidir. También están disponibles pgAdmin y Vaultwarden.

Crear una web sin programar

Empieza con Kubo Web para diseñar tus páginas, añadir un blog y preparar contenido en varios idiomas. Puedes trabajar con el editor visual y publicar cuando estés listo. Encontrarás la guía de Kubo Web justo debajo.

Web estática

Para una landing, documentación o una app que funciona en el navegador. Publica HTML, CSS y JavaScript ya generados; no ejecuta un servidor. Una app React con Vite suele encajar aquí si su API vive aparte.

Web híbrida

Para páginas que necesitan un servidor: contenido por petición, sesiones o renderizado dinámico. El selector admite Astro, Next.js, Nuxt, SvelteKit, React Router y Angular. Necesitas preparar la imagen del servidor, los archivos estáticos y el manifiesto del build compatible con Kubo; elegir el framework no los genera.

Servicio

Para una API completa, una base de datos o un proceso en segundo plano. Tú defines la imagen que se ejecuta y cuántas copias mantener. Elige este tipo si necesitas un proceso continuo o un runtime distinto de Python.

Función

Para una tarea Python que se ejecuta al recibir una petición HTTP, como un webhook. Puede arrancar desde cero y escalar con las peticiones; el primer arranque puede tardar más. No es la opción para una base de datos ni para un proceso continuo.

02 / Guía práctica

Kubo Web

Crea una web a tu medida, añade un blog y publica tus cambios sin necesidad de programar. Aquí tienes ayuda para cada paso.

Crear tu primera web

Pulsa Nueva web, ponle un nombre y empieza a añadir páginas. Puedes cambiar el diseño y el contenido cuando quieras. Si ya tienes un proyecto compatible, usa la opción de importar.

Cambiar el diseño

Añade textos, imágenes y secciones desde Añadir elementos. Selecciona lo que quieras cambiar y ajusta sus colores, tamaño o separación en el panel lateral. Arrastra los elementos para ordenarlos; la marca que aparece indica dónde quedarán.

Revisar la versión móvil

Comprueba el diseño para ordenador, tableta y móvil. Puedes cambiar la distribución y el tamaño de los elementos en cada vista. Al editar desde un teléfono, la vista se adapta a la pantalla disponible.

Usar una sección en varias páginas

Guarda una sección en la biblioteca de reutilizables e insértala donde la necesites. Al editarla se actualizan sus copias. Si quieres que una de ellas sea diferente, desvincúlala antes de cambiarla.

Añadir fotos y vídeos

En Archivos puedes ver, sustituir y borrar las imágenes y vídeos que has subido. Ajusta cómo encajan en el diseño para evitar recortes no deseados. Para añadir YouTube, pega el enlace en un elemento Vídeo; el reproductor se carga cuando el visitante lo abre.

Crear y organizar páginas

Añade páginas desde Páginas y elige una dirección corta y descriptiva para cada una. Puedes eliminar una página con la papelera y recuperarla con Deshacer. La portada se conserva. También puedes personalizar el mensaje que verá alguien al abrir una dirección que no existe.

Escribir en el blog

Activa Blog y pulsa Nuevo artículo. Escribe y da formato al contenido, añade título, portada y etiquetas, y guarda un borrador si aún no está listo. También puedes importar artículos en Markdown, un formato de texto que conserva títulos, enlaces y otros datos.

Personalizar el listado de artículos

Abre Listado y plantilla del blog. Cambia el aspecto de las tarjetas y añade búsqueda o filtros por etiquetas. Puedes mostrar los artículos por páginas, con un botón para cargar más o a medida que el lector baja. Edita también la sección Sin artículos: se muestra cuando no hay resultados. El listado se puede personalizar y mover, pero no eliminar.

Preparar tu web para buscadores

Escribe un título y una descripción que expliquen cada página y usa direcciones fáciles de reconocer. Configura el dominio público en Idiomas/SEO para que el mapa del sitio y las referencias de las páginas apunten a tu web. Estas herramientas ayudan a los buscadores a entenderla; no garantizan una posición en sus resultados.

Ofrecer varios idiomas

Añade los idiomas que necesites y crea versiones vinculadas de tus páginas. Comparten el diseño, pero cada una tiene sus textos y dirección. Escribe las traducciones desde la página de ese idioma o desde el panel del elemento. Si falta un texto, se usa el idioma principal. Puedes colocar un selector de idioma donde quieras. No se traduce automáticamente.

Recibir mensajes con un formulario

Añade un formulario, elige sus campos y marca cuáles son obligatorios. Para recibir las respuestas por correo, conecta un proveedor como Resend o SMTP siguiendo las indicaciones de configuración. Puedes añadir protección contra spam con reCAPTCHA o Turnstile. Comprueba el envío después de publicar: la vista previa no ejecuta el servicio de correo.

Probar antes de publicar

Abre Vista previa para probar enlaces, menús y otros elementos. Pantalla completa permite ver la web sin los paneles del editor. Guardar conserva tu trabajo, pero no publica los cambios para tus visitantes.

Publicar y actualizar la web

Pulsa Publicar, elige un proyecto nuevo o existente de KuboRun y configura el dominio. Puedes seguir el progreso en KuboRun. Cuando quieras publicar cambios, usa Redesplegar: mantiene el mismo destino y prepara la nueva versión. Si hay un error, revisa el mensaje y vuelve a intentarlo; guardar una web no significa que ya esté publicada.

Volver a una versión anterior

En Versiones puedes consultar guardados anteriores y recuperar uno en el editor. Revísalo antes de guardarlo o publicarlo: restaurar no cambia por sí solo la web que ven tus visitantes. Se conservan hasta 20 versiones recientes, dentro del límite de almacenamiento del historial.

Traer una web existente

Puedes importar una carpeta o ZIP de Astro, o conectar un proyecto compatible de KuboRun. Se conservan sus páginas originales, pero no se convierten automáticamente en elementos editables. Puedes añadir páginas nuevas con el editor visual. Algunas páginas importadas no tienen vista previa; el editor indica el motivo. Los proyectos gestionados desde un repositorio pueden necesitar cambios desde ese repositorio.

Qué hacer si aparece un aviso de tamaño

No hay un número fijo de páginas. En Páginas puedes ver cuánto ocupa el proyecto y cuántos elementos contiene. Los avisos ayudan a detectar archivos pesados o diseños complejos. Cada proyecto admite 25 MB, 5.000 componentes y 8 niveles de secciones anidadas. Si te acercas al límite, reduce el peso de imágenes y vídeos o simplifica las páginas más grandes.

Opciones avanzadas y exportación

Si necesitas más personalización, puedes añadir CSS, JavaScript o un elemento HTML. Las variables privadas permiten configurar integraciones sin incluir sus valores en la descarga. La exportación externa está desactivada por defecto; Administración puede habilitarla para tu cuenta. Cuando está habilitada, Exportar Astro descarga el proyecto para publicarlo en otro alojamiento compatible; si usa formularios con acciones de servidor, necesitará un servidor y las credenciales correspondientes. Estas opciones pueden requerir ayuda técnica.

Guardar con tranquilidad

Usa Guardar o Ctrl/Cmd+S para conservar tu trabajo. Deshacer recupera cambios recientes y las tarjetas de Mis webs muestran la última edición guardada. Si otra versión se ha guardado mientras trabajabas, el editor te avisa para evitar sobrescribirla. La edición simultánea entre varias personas todavía no está disponible.

Revisión por artículo

En Revisión puedes elegir una entrada, enviarla a revisar, aprobarla y programarla. Publica primero el diseño completo desde ese panel: las publicaciones de artículos usarán esa versión y no arrastrarán cambios pendientes de otras entradas o del diseño.

03 / Guía práctica

Crear tu proyecto

Un proyecto reúne las piezas de una aplicación: por ejemplo, web, API y base de datos.

Nombre y origen

Pon un nombre reconocible (hasta 80 caracteres). Puedes indicar una URL pública HTTPS de GitHub, GitLab o Bitbucket, elegir un ZIP o empezar sin repositorio. Usa la URL del repositorio, no la de un archivo, y no incluyas credenciales.

Guardar y publicar son pasos distintos

Guarda el proyecto para continuar después, incluso si aún está incompleto. Cuando esté listo, pulsa Desplegar. Si ya está publicado, el mismo botón aplica los cambios sin que tengas que apagarlo antes. En el proyecto puedes consultar su estado, las versiones y los registros de actividad para comprobar el resultado.

04 / Guía práctica

Nombre, imagen y réplicas

Rellena estos datos para cada recurso que añadas.

Nombre del recurso

Usa un nombre único dentro del proyecto, como web, api o database. Empieza con una letra minúscula; admite letras minúsculas, números y guiones, hasta 40 caracteres.

Imagen de contenedor

Es el paquete ejecutable de tu aplicación, no la URL del repositorio. Ejemplo de formato: ghcr.io/tu-equipo/app:1.0.0. Sustitúyelo por una imagen real que hayas preparado. Una versión fija permite saber qué publicas. Se pide en servicios, webs híbridas y funciones.

Réplicas

Son copias de un servicio o web híbrida. Empieza con 1 si solo necesitas una copia; 0 lo deja pausado. El editor admite hasta 5. Cada copia necesita sus propios recursos. No aumentes las réplicas de una base de datos sin preparar su replicación.

05 / Guía práctica

Configurar una web

La carpeta depende del resultado de tu build, no solo del nombre del framework.

Carpeta de archivos estáticos

Indica una ruta relativa a la raíz del repositorio, como ./dist si ahí se genera tu web. Debe contener el resultado compilado que quieres servir, no los componentes fuente. No uses una ruta absoluta ni ../. Las webs estáticas no admiten variables de ejecución ni volúmenes.

Framework y manifiesto del build

En una web híbrida selecciona el framework real y la ruta del manifiesto compatible con Kubo, por ejemplo ./kubo-build.json. Este archivo describe cómo se sirven los archivos y las rutas dinámicas. No es package.json. Comprueba que tu proceso de build lo produce junto a la imagen y los archivos.

06 / Guía práctica

Configurar una función

Una función también necesita una imagen preparada para su runtime.

Python y directorio

Selecciona Python 3.12, 3.13 o 3.14, según tu imagen. El directorio es una ruta absoluta dentro de esa imagen, como /app/api, no una carpeta de tu ordenador.

Máximo de instancias

Es el límite de copias que pueden atender peticiones a la vez, entre 1 y 5. Más instancias permiten más trabajo simultáneo y pueden aumentar el consumo. No es un número de copias que permanezcan siempre encendidas.

07 / Guía práctica

Puerto y dominio

Expón solo los recursos que deban recibir visitas o peticiones externas.

Puerto interno

Es el puerto en el que escucha tu aplicación dentro de la imagen, por ejemplo 3000 u 8080. Debe coincidir con su configuración. Un servicio con puerto 0 no expone un puerto. Una función necesita un puerto válido.

Dominio

Escribe app.example.com, sin https:// ni rutas. Las webs estáticas e híbridas necesitan uno; un servicio interno puede dejarlo vacío. Para publicar debes verificar su propiedad y configurar el DNS según las indicaciones de la plataforma. localhost sirve para pruebas locales, no como dominio público.

Dominio gratuito de KuboRun

Si no tienes dominio propio, pulsa «Generar dominio gratis». Recibirás un nombre como ….apps.kuborun.com y se rellenará el campo de dominio. Está disponible para webs y APIs HTTP cuando la plataforma lo tenga habilitado. El nombre es gratuito; los recursos de tu aplicación mantienen su coste habitual. Volver a pulsar recupera el mismo nombre. También puedes elegir uno de «Tus dominios generados». Se conserva en tu cuenta aunque cierres el borrador (máximo 20). Solo tu cuenta puede configurarlo. Al eliminar el último servicio que lo usa, se retira definitivamente y se borra su registro DNS; el nombre antiguo nunca se reasigna. Si la reserva se está reponiendo, vuelve a probar en unos momentos. Asignar el nombre no publica la aplicación: también necesita despliegue y HTTPS.

08 / Guía práctica

CPU, memoria y archivos

Elige recursos por copia de tu aplicación. Ajusta según su consumo real.

CPU y memoria

1000 mCPU equivalen a 1 CPU; 1024 MiB, a 1 GiB de memoria. El editor admite 100–4000 mCPU y 128–8192 MiB por réplica o instancia. Los valores iniciales no garantizan que cualquier aplicación funcione: revisa lo que necesita tu runtime.

Volúmenes

Añade uno si necesitas conservar datos entre versiones, por ejemplo archivos de una base de datos. Indica un nombre, la ruta absoluta donde la aplicación escribe y la capacidad en GiB. La ruta debe corresponder a tu imagen; /data es solo un ejemplo. Un volumen no sustituye a una copia de seguridad.

Capacidad de disco

El máximo es 900 GiB por volumen. 0 significa sin reserva de capacidad. Si reservas espacio, la plataforma debe asignar el almacenamiento gestionado antes del despliegue. Quitar un volumen del borrador solo cambia la configuración; no elimina datos desplegados.

09 / Guía práctica

Variables y secretos

Separa la configuración pública de las credenciales.

Variables de entorno

Para valores no sensibles, como NODE_ENV=production. Los nombres usan mayúsculas, números y guiones bajos, sin empezar por un número. Se guardan en la configuración exportada; no pongas contraseñas ni tokens aquí.

Secretos

Añade la clave, por ejemplo DATABASE_URL o API_KEY, y guarda la configuración del proyecto. En Secretos, pulsa Cambiar valor para guardarlo cifrado. El valor no vuelve a mostrarse ni se incluye en el YAML. Redepliega los servicios afectados tras actualizarlo. Borrar un valor no lo elimina de un servicio que ya está en marcha; necesitará redeplegarse. No repitas un nombre como variable y secreto.

10 / Guía práctica

Revisar y publicar

Una configuración válida es el primer paso; una versión desplegada debe confirmarse por su estado.

Antes de continuar

Revisa los errores del editor, la imagen, las rutas, el puerto, los dominios y los secretos pendientes. Crea y edita cada recurso desde Servicios. Las variables, los secretos y el almacenamiento están en secciones desplegables. Usa «Ver YAML» para consultar el archivo y pulsa Guardar para conservar el borrador en KuboRun. También puedes descargar kubo.yaml. No necesitas escribir YAML para rellenar los campos.

Comprobar que se ha publicado

Sigue el progreso del despliegue y espera a que termine. Después comprueba el estado del servicio y abre su dirección pública. Si falla, revisa el mensaje de error y los registros antes de volver a intentarlo. Guardar la configuración no publica los cambios.

Si algo falla

Si el editor rechaza una ruta, comprueba si pide una ruta relativa al repositorio o absoluta dentro de la imagen. Si una aplicación desplegada no responde, revisa su puerto, dominio y estado; los logs, cuando estén disponibles, ayudan a localizar el fallo. Nunca compartas credenciales al pedir ayuda.

11 / Guía práctica

Protección de réplicas

Permite que un servicio termine un trabajo antes de que un cambio de versión o una reducción de réplicas retire su instancia. Tu aplicación solicita protección, consulta si hay una retirada pendiente y libera la protección al terminar.

¿Qué se protege?

Solo la réplica del servicio que hace la llamada. Kubo la identifica mediante su credencial privada; la petición no permite elegir otra réplica ni otro servicio. Los trabajos simultáneos pueden tener protecciones independientes. Liberar una no libera las demás. Esta API corresponde a réplicas de servicios, no a funciones.

¿Cuánto dura la protección?

Durante el funcionamiento normal, elige un TTL de entre 1 y 1.800 segundos y renuévalo antes de que venza si lo necesitas. Cuando Kubo solicita la retirada por primera vez, las protecciones que siguen activas reciben un plazo común de exactamente 30 minutos desde esa solicitud, que sustituye a su vencimiento anterior. Por ejemplo, una retirada solicitada a las 14:00 permite esperar hasta las 14:30, aunque el TTL original estuviera a punto de vencer. Sin una protección activa no hay periodo de gracia.

¿Qué ocurre cuando hay una retirada pendiente?

No se admiten nuevas protecciones ni renovaciones: esas llamadas devuelven HTTP 409 con retirement_pending. Consulta GET /lifecycle periódicamente. Indica retirement_pending, el motivo, requestedAt, deadline y acceptingProtections. Deja de aceptar trabajos nuevos y termina los que ya están en curso. Liberar todas las protecciones permite retirar antes la réplica; de lo contrario, Kubo puede retirarla al vencer el plazo fijo. Las consultas, otros despliegues, los reinicios y la reutilización del nodo no reinician la cuenta atrás.

¿Cómo se conecta mi aplicación?

Las réplicas de servicios nuevas reciben KUBO_LIFECYCLE_URL y KUBO_REPLICA_TOKEN como variables de entorno. Usa la URL inyectada y envía Authorization: Bearer seguido del token en cada petición. No publiques este endpoint ni registres el token en los logs. Las réplicas creadas antes de esta funcionalidad deben recrearse para recibir estas variables. No necesitas credenciales de administrador.

Solicitar y renovar protección

Envía POST /protect relativo a KUBO_LIFECYCLE_URL con Content-Type: application/json, un Idempotency-Key único por trabajo y un cuerpo como {"ttl":120}. Guarda el protectionId recibido y empieza el trabajo crítico solo después de obtener una respuesta correcta. Si se pierde la respuesta, reintenta con la misma clave y TTL; nunca reutilices la clave para otro trabajo. PATCH /protect/{protectionId} con el mismo formato de cuerpo renueva la protección solo antes de la retirada. Una API no disponible no confirma la protección.

Liberar la protección

Envía DELETE /protect/{protectionId} en cuanto termine el trabajo, también si falla. La liberación es idempotente y puede reintentarse. Usa un protectionId distinto por cada trabajo simultáneo y sigue consultando GET /lifecycle durante su ejecución. Una réplica de reemplazo tiene su propia identidad y no puede heredar la credencial de la anterior.

¿Qué puedo elegir en Run?

Al actualizar o parar explícitamente una réplica protegida, elige Esperar para respetar la protección o Continuar inmediatamente para interrumpirla. Borrar un servicio o proyecto, o apagar el proyecto completo, avisa de las protecciones pero continúa igualmente. La protección no evita una caída del proceso, una terminación por falta de memoria, un fallo del nodo ni una parada forzada externa; los trabajos siguen necesitando mecanismos de recuperación.

¿Cuándo tiene un coste adicional?

Solicitar protección supone aceptar este precio: solo se aplica un recargo mientras la protección sea el único motivo que mantiene encendido un nodo que ya podría retirarse. Cada réplica que lo bloquea cuesta entonces el doble de su tarifa normal de CPU y memoria reservadas: cómputo habitual más un recargo del 100%. Tener protección en un nodo que sigue siendo necesario normalmente no añade recargo. Almacenamiento, red y mínimos de la cuenta no cambian.

¿Cómo se calcula el recargo?

El precio depende de la CPU y memoria reservadas de esa réplica, no del tamaño ni del precio del nodo físico. No se reparte entre clientes ni aumenta porque otro cliente proteja una réplica. Por ejemplo, si tu cómputo reservado cuesta normalmente 0,10 € por hora, diez minutos de bloqueo añaden unos 0,0167 € al cómputo habitual. El desglose de consumo identifica este importe adicional como Protección de réplicas.

¿Cuándo termina el recargo?

Termina al liberar la protección que bloquea la retirada, vencer su plazo fijo o confirmar Kubo la reutilización del nodo para capacidad necesaria. No pagas el retraso posterior del proveedor al apagarlo. Reutilizar un nodo termina el recargo sin reiniciar el plazo de retirada de la réplica original. Se facturan segundos completos transcurridos, sin un periodo mínimo de cobro adicional.

12 / Guía práctica

Saldo y avisos

Puedes preparar tu configuración antes de añadir saldo.

Saldo y mínimo

Facturación muestra el saldo disponible, la reserva y el consumo del periodo. El mínimo depende de tu cuenta: si es 5 € por 30 días y consumes 3 €, solo faltan 2 € para cubrirlo; no son 5 € adicionales. Si tu mínimo es 0 €, no se aplica. Consulta las fechas junto al consumo del periodo.

Recargas, avisos e impuestos

Añade saldo manualmente o configura la recarga automática cuando los pagos estén habilitados. El aviso de saldo bajo es independiente: viene apagado y puedes elegir su umbral; no añade dinero. El envío requiere que las notificaciones estén disponibles. Revisa impuestos y total antes del pago, y gestiona datos fiscales y facturas desde el portal de facturación.

Recargo por protección de réplicas

Si la protección mantiene encendido un nodo que ya podría retirarse, la réplica que lo bloquea cuesta el doble de su tarifa habitual de CPU y memoria reservadas durante ese intervalo. Consulta Protección de réplicas en esta guía para conocer el plazo, la API de liberación y un ejemplo de precio.

13 / Para profundizar

Un poco más por dentro

Opcional: lo necesario para entender qué expresa tu configuración.

Configuración y ejecución

El formulario genera una descripción de tu proyecto para Kubo Core. La plataforma debe validar esa descripción y preparar los recursos antes de ejecutar una versión. Por eso cambiar un borrador no modifica por sí solo una aplicación en marcha.

Archivos y procesos

Una web estática sirve archivos. Una híbrida combina archivos con un servidor para las rutas dinámicas. Los servicios ejecutan imágenes; las funciones añaden activación HTTP y límites de escalado. Red, secretos y volúmenes se configuran por separado del código.

Versiones y datos

Una nueva imagen cambia el programa, pero los datos persistentes pertenecen a sus volúmenes. Volver a una versión anterior del programa no revierte automáticamente una base de datos. Prepara copias de seguridad y migraciones compatibles antes de cambiar su estructura.

Configuración segura

La configuración indica qué necesita tu aplicación. KuboRun comprueba los recursos y dominios antes de publicarla. Si un ajuste no está permitido, verás un error para corregirlo antes de continuar.

14 / Guía práctica

Builds al desplegar

Guardar conserva tu trabajo; Desplegar prepara una nueva versión y la publica. Puedes seguir el progreso y revisar los errores desde el proyecto.

ZIP y versiones

Un nuevo ZIP cambia la huella de los servicios modificados. Un tag existente no evita reconstruir código nuevo. Guardar no despliega. Un fallo de build no aplica la nueva versión.

Logs del despliegue

Logs muestra preparación, builds y problemas antes de que arranque el contenedor. El historial sobrevive al refrescar y los diagnósticos indican cómo corregir imágenes, acceso al registro, capacidad o disponibilidad. Los logs de ejecución se consultan debajo.

15 / Guía práctica

Cuentas compartidas en Kubo Run

Elige la cuenta propietaria y da acceso a proyectos concretos.

Comparte un proyecto

En Configuración puedes crear una cuenta de equipo e invitar por email. La persona invitada verifica ese correo y acepta en su Configuración; tiene siete días para hacerlo. Cambia de cuenta en el sidebar: los recursos se cobran a la cuenta seleccionada. La propiedad de un equipo puede transferirse a un miembro que la acepte, conservando sus proyectos, saldo y facturas.

Elige los permisos

Separa lectura, edición, despliegue, secretos, facturación, miembros, dominios, paquetes y conexiones Git. Kubo Web permite dar acceso solo al blog o al diseño. Para publicar una versión aprobada necesitas permiso de publicación Web y despliegue en el proyecto Run conectado. Editar código es un permiso distinto y permite usar los secretos de esa aplicación.

Borradores y publicación

Kubo Web guarda automáticamente y ofrece recuperar cambios conservados en el navegador. En Revisión puedes enviar una versión, aprobarla y elegir cuándo publicarla. Cambiarla después exige otra revisión. Las entradas marcadas como borrador quedan fuera de la publicación.