Tutorial de implementación autohospedada de OpenShip: creación de una plataforma CI/CD con CLI y Docker

OpenShip es una plataforma de implementación de aplicaciones autohospedada y de código abierto con CI/CD integrado y ofrece una aplicación de escritorio, una consola web y CLI. Su objetivo es permitir a los desarrolladores identificar automáticamente la pila de tecnología, crear contenedores, configurar servicios y completar lanzamientos después de conectar el almacén de código al servidor, reduciendo el trabajo de escritura a mano y la implementación de YAML.

El proyecto cubre Node.js, Python, Go, Rust, PHP, Ruby, Java, .NET, Docker y monorepo, y también incluye bases de datos, nombres de dominio, certificados TLS, CDN, correo electrónico, copias de seguridad y monitoreo en la misma interfaz. Puede conectarse a OpenShip Cloud o implementarse en su propio VPS Linux o servidor dedicado.

Respuesta rápida

Instale la CLI usando npm:

1

npm i -g openship

Inicie el servicio en segundo plano de OpenShip:

1

openship up

Abra la interfaz de administración:

1

openship open

Ingrese el directorio del proyecto que se implementará, inicializará y publicará:

1
2
3

cd your-project
openship init
openship deploy

openship init se utiliza para conectar el directorio actual al proyecto OpenShip y openship deploy desencadena la compilación y la implementación. Antes de usarlo por primera vez en un servidor de producción, se recomienda utilizar un elemento no crítico para verificar el directorio persistente, la resolución del nombre de dominio, el certificado, la copia de seguridad y el proceso de reversión.

¿Qué problema resuelve OpenShip?

La implementación manual de un proyecto web generalmente requiere manejar Git pull, creación de imágenes, proxy inverso, TLS, variables de entorno, bases de datos, registros, copias de seguridad y reversión de versiones por separado. OpenShip centraliza estas tareas en una única plataforma de implementación.

Está más cerca de un PaaS liviano o de un panel de control de implementación autohospedado que de un CI Runner independiente. Los resultados de la implementación utilizan contenedores Docker estándar para facilitar la migración entre diferentes servidores y proveedores.

Preparación antes de la instalación

Si solo tiene experiencia local, puede instalar la CLI en la máquina de desarrollo. Al prepararse para el autohospedaje a largo plazo, se recomienda utilizar un servidor Linux independiente y confirmar con anticipación:

1. El servidor puede acceder al almacén de códigos y a la fuente espejo;
2. Los registros DNS pueden apuntar a la dirección de red pública del servidor;
3. Se han permitido en el firewall HTTP, HTTPS y los puertos realmente requeridos por la plataforma;
4. El espacio en disco puede acomodar espejos, bases de datos, volúmenes persistentes y copias de seguridad;
5. Se han planificado la autenticación del administrador, el almacenamiento de claves y la copia de seguridad externa.

OpenShip tiene acceso al código fuente, credenciales de implementación, variables de entorno y bases de datos, por lo que las consolas desprotegidas no deben exponerse directamente a la red pública. Antes de conectarse oficialmente, debe leer la documentación de la versión actual y las instrucciones de seguridad, y primero verificar la actualización y recuperación en un entorno aislado.

Método 1: instalar mediante CLI

Inicio rápido oficial con la instalación global de npm:

1

npm i -g openship

El funcionario también proporciona la entrada para la instalación de Shell:

1

curl -fsSL https://get.openship.io | sh

Antes de ejecutar un script remoto en el servidor, se recomienda descargar y revisar el contenido del script. Una vez completada la instalación, inicie el servicio en segundo plano:

1

openship up

Este comando instalará OpenShip como un servicio en segundo plano y configurará el inicio y el reinicio automático en caso de excepciones. Debe ejecutarse al observar el registro de inicio en primer plano:

1

openship up --foreground

Abra la consola:

1

openship open

Detenga el servicio en segundo plano:

1

openship stop

La ejecución en primer plano es más adecuada para la resolución de problemas por primera vez; después de confirmar que la configuración y el directorio de datos son correctos, cambie al modo de servicio en segundo plano.

Método 2: usar Docker Compose

Cuando desee un control explícito sobre contenedores, redes y volúmenes, puede iniciar la pila Compose desde el repositorio oficial:

1
2
3
4

git clone https://github.com/oblien/openship.git
cd openship
cp .env.example .env
docker compose up -d

No inicie en la red pública inmediatamente después de copiar .env.example. Primero abra .env, verifique todas las contraseñas, claves, direcciones externas, puertos y configuraciones de persistencia, reemplace los valores de ejemplo y luego ejecute Compose.

Ver el estado y los registros del servicio:

1
2

docker compose ps
docker compose logs -f

Detenga el servicio pero conserve los datos del volumen:

1

docker compose down

No agregue simplemente -v sin una copia de seguridad, ya que eliminará el volumen administrado por Compose. Antes de actualizar, debe registrar la imagen o versión actual, exportar la base de datos y hacer una copia de seguridad del volumen persistente para asegurarse de poder regresar a la versión verificada.

Implementar el primer proyecto

Ingrese al directorio del proyecto local:

1
2

cd your-project
openship init

El proceso de inicialización se utiliza para crear o seleccionar un proyecto OpenShip y asociar el directorio actual con el proyecto. Activar la implementación después de la finalización:

1

openship deploy

La plataforma intentará identificar la pila de tecnología, crear la aplicación y configurar el entorno de ejecución. Aunque el énfasis oficial está en reducir los archivos de configuración, aún se debe aclarar la siguiente información antes de la implementación:

• Puerto de escucha de aplicaciones y ruta de verificación de estado;
• Comandos de compilación, comandos de inicio y versiones de tiempo de ejecución;
• Secretos y variables de entorno requeridas;
• Directorio que debe guardarse de forma persistente;
• Cuándo se debe realizar la migración de la base de datos.

La detección automática es adecuada para proyectos habituales, pero no debe sustituir la comprensión del proceso de inicio de la aplicación. Cuando encuentre un error de compilación, primero confirme en el registro de compilación en tiempo real si el idioma, la versión y el comando detectados son correctos.

Implementar el proyecto Docker Compose

Las instrucciones oficiales de OpenShip pueden implementar archivos Compose existentes tal como están. Para proyectos que incluyen servicios web, trabajadores, bases de datos y Redis, esto suele ser más sencillo que reconfigurar todos los servicios.

Verifique el archivo Redactar antes de comprometerse con la implementación:

1

docker compose config

Verificación de inicio local:

1
2

docker compose up -d
docker compose ps

Se requiere una inspección especial:

1. No lleve el montaje vinculado del entorno de desarrollo directamente al entorno de producción;
2. Las bases de datos y los cachés no deben exponer los puertos del host sin autenticación;
3. El secreto no debe estar codificado en compose.yaml;
4. Los servicios deben tener controles de salud razonables y estrategias de reinicio;
5. Los volúmenes persistentes deben incluirse en las pruebas de respaldo y recuperación.

Se puede iniciar Local Compose, lo que solo prueba que la configuración básica del contenedor está disponible. Los nombres de dominio, TLS, redes externas, límites de recursos y migración de datos de producción aún deben verificarse de forma independiente en el entorno de destino de OpenShip.

Configurar nombre de dominio y TLS

OpenShip admite la gestión de nombres de dominio, Let’s Encrypt, certificados comodín y renovación automática. El proceso general es:

1. Resuelva el nombre de dominio en el servidor de implementación en el proveedor de servicios DNS;
2. Vincular el nombre de dominio en el proyecto OpenShip;
3. Espere a que la plataforma solicite y configure el certificado;
4. Verifique el salto de HTTP a HTTPS;
5. Verifique la cadena de certificados y el estado de renovación de la red externa.

Cuando falla la solicitud del certificado, primero verifique si el DNS ha entrado en vigencia, si los puertos 80 y 443 están ocupados por otros servidores proxy inversos y si el modo de proxy CDN afecta la verificación ACME. Los certificados comodín generalmente también implican validación de DNS y los permisos requeridos deben limitarse a los nombres de dominio necesarios.

Base de datos, almacenamiento y respaldo

Las capacidades de backend enumeradas por la plataforma incluyen Postgres, MySQL, MongoDB, Redis, Workers, WebSocket y Storage. Después de crear la base de datos, la información de conexión debe inyectarse en la aplicación a través del secreto de la plataforma o las variables de entorno para evitar enviarla a Git.

La función de copia de seguridad cubre bases de datos y volúmenes, pero “se han configurado tareas programadas” no es igual a “se pueden restaurar”. Complete al menos un simulacro de recuperación antes de conectarse:

1. Cree datos de prueba;
2. Generar copias de seguridad de forma manual o periódica;
3. Exportar la copia de seguridad fuera del servidor;
4. Restaurar en un proyecto aislado o en una base de datos de prueba;
5. Verifique que los datos, permisos y versión de la aplicación sean consistentes.

Si la copia de seguridad solo se guarda en el mismo disco en el mismo servidor, es posible que aún se pierda si el disco duro falla o el host es invadido. Los entornos de producción deben mantener copias externas y configurar controles de acceso y cifrado para los archivos de respaldo.

Pulsar para implementar y revertir

OpenShip proporciona entornos push-to-implement, vista previa, procesos de preparación/producción y reversión. Al acceder al repositorio de código, no le dé al token de implementación más permisos de organización o de repositorio de los necesarios.

Se recomienda configurar el proceso de lanzamiento de producción como:

1. Pull Request crea un entorno de vista previa;
2. Implementar la preparación después de la fusión;
3. Completar los exámenes de salud y pruebas necesarias;
4. Lanzamiento a producción después de la confirmación;
5. Supervisar las tasas de error, los recursos y las interfaces clave;
6. Retroceder al producto verificado anterior en caso de excepción.

Es posible que los cambios en el esquema de la base de datos no se deshagan automáticamente a medida que el contenedor se revierte. Al diseñar migraciones, se deben priorizar los pasos de compatibilidad con versiones anteriores y el proceso de recuperación de la base de datos debe verificarse por separado de la reversión de la aplicación.

¿Cómo elegir entre los tres métodos de gestión?

El proyecto también proporciona interfaces REST API y MCP para la integración con herramientas de automatización o agentes de IA. Al crear credenciales para clientes de automatización, utilice identidades independientes, privilegios mínimos y tokens revocables; conservar la confirmación o aprobación manual para operaciones de alto impacto, como implementación, eliminación y recuperación.

Debe distinguirse el estado actual y la hoja de ruta.

El archivo README oficial describe la funcionalidad principal como lista para producción y en desarrollo continuo, al tiempo que deja claro que la documentación aún se está perfeccionando. Los clústeres de múltiples nodos, las interfaces de equilibrio de carga, las redes privadas, el monitoreo avanzado y las canalizaciones de CI/CD visuales se enumeran como planes de seguimiento.

Por lo tanto, la evaluación debe basarse en las funciones realmente disponibles en la versión actual y no tratar la hoja de ruta tal como se entregó. Para la migración de producción, primero verifique las capacidades que realmente necesita, como recuperación de fallas de un solo nodo, compatibilidad de actualización, exportación de respaldo, aislamiento de permisos y registros de auditoría.

Preguntas frecuentes

openship up La consola no se puede abrir después del inicio.

Primero use el modo de primer plano para observar errores:

1

openship up --foreground

Luego verifique la ocupación del puerto, el firewall, el estado del servicio y los registros. Si se ejecuta en un servidor remoto, la dirección abierta por openship open también debe ser accesible desde la red del lado de administración.

El reconocimiento automático está construido incorrectamente

Verifique el directorio raíz del proyecto, el archivo de bloqueo, el Dockerfile, el archivo Compose y la declaración de la versión en tiempo de ejecución. El monorepo también necesita confirmar el subdirectorio de la aplicación real y crear contexto para evitar que la plataforma seleccione la entrada incorrecta en el directorio raíz del almacén.

El nombre de dominio se resolvió pero falló la emisión del certificado.

Verifique que DNS devuelva la dirección del servidor de destino, que otros servicios no utilicen los puertos 80/443, que el firewall de la nube permita el acceso externo y que la CDN o el proxy inverso bloqueen las solicitudes de verificación.

¿Se puede reemplazar inmediatamente la plataforma de producción existente?

No se recomienda la migración general directa. Primero seleccione un proyecto de bajo riesgo que pueda revertirse, verifique la implementación, los registros, el monitoreo, la copia de seguridad y la recuperación, las actualizaciones de versión y el manejo de fallas, y luego amplíe gradualmente el alcance de uso.

¿Para quién es adecuado OpenShip?

OpenShip es adecuado para desarrolladores individuales o equipos pequeños que desean una experiencia de implementación todo en uno en sus propios servidores Linux, pero no desean mantener CI, servidores proxy inversos, certificados y scripts de bases de datos por separado para cada proyecto. También es adecuado para entornos que desean conservar la portabilidad básica a través de Docker.

Si una organización ya cuenta con sistemas maduros de Kubernetes, GitOps, gobierno de identidad y observabilidad, la introducción de un nuevo plano de control de implementación puede agregar duplicación de la gestión. Aquí es donde comienza comparando modelos de permisos, auditorías, capacidades de clúster y costos de integración de canalizaciones existentes.

Resumen

OpenShip reúne la creación de código, la implementación de contenedores, los certificados de dominio, las bases de datos, las copias de seguridad y el monitoreo en la misma plataforma y permite la administración a través de escritorio, web, CLI, API y MCP. La forma más rápida de experimentarlo es instalar la CLI y ejecutar openship up. Para el autohospedaje de producción, es más adecuado comenzar con un proyecto de prueba aislado, centrándose en verificar secretos, persistencia, copia de seguridad y recuperación, actualizaciones y reversiones.

Dirección del proyecto: obblien/openship

Documentación oficial: openship.io/docs