Instalación y operaciones de Coblyn

●  Instalacionv1.17.0 Release GateNivel · AdministradorÚltima rev · 27 jun 2026

Coblyn se instala como un appliance Docker on-premise. Desde v1.17.0 "Release Gate", arranca sólo con configuración segura, imágenes versionadas y un camino operativo para diagnóstico, backup y upgrade.

Sin credenciales por defecto

El modo production falla al arrancar si detecta secretos vacios, placeholders o CORS_ORIGINS=*. Si vienes de una guia antigua que usaba admin/admin o admin/coblyn, descartala.

Alcance soportado

Area	Estado actual
Host recomendado	Ubuntu Server 24.04 LTS amd64 o Debian 12 amd64
Runtime	Docker 24+ con Docker Compose V2
Red PXE	Interfaz fisica o bridged con conectividad L2 a la VLAN de despliegue
Almacenamiento	Storage Hub con pools NFS o SMB/CIFS desde la UI
Windows Server como host	No es objetivo de produccion todavia
Version documentada	v1.17.0 "Release Gate"

Para una PoC sin DHCP/PXE real, usa --testing --wizard; el instalador evita activar el plano PXE y expone la UI en un puerto de pruebas.

Puertos

Servicio	Puerto	Protocolo	Exposicion
Web UI / API via nginx	${WEB_PORT:-80}	TCP	Usuarios y agentes
TFTP	69	UDP	Clientes PXE
DHCP / Kea	67/68	UDP	Red host, interfaz PXE
RustDesk hbbs	21115, 21116, 21118	TCP	Soporte remoto
RustDesk hbbs heartbeat	21116	UDP	Soporte remoto
RustDesk hbbr	21117, 21119	TCP	Relay remoto

PostgreSQL, Redis y backend viven en la red Docker interna 10.150.0.0/24; no abras esos puertos al exterior. El backend controla Kea mediante el socket Unix compartido /run/kea/kea-dhcp4-ctrl.sock, sin Control Agent ni API HTTP publicada.

Instalacion limpia

1. Preparar el servidor

Usa una maquina limpia con una NIC dedicada o bridged para la VLAN de despliegue. Evita NAT si necesitas DHCP/PXE.

ip -brief addr
ip route

Anota:

• Interfaz PXE, por ejemplo eth0 o ens192.
• IP fija del servidor en esa VLAN.
• Gateway, DNS y rango DHCP autorizado.
• Rango de cuarentena para equipos desconocidos.

2. Descargar y verificar el bootstrapper

Descarga una versión explícita en un directorio privado, valida el checksum e inspecciona el script antes de elevar privilegios:

install -d -m 0700 "$HOME/coblyn-bootstrap"
cd "$HOME/coblyn-bootstrap"
curl --proto '=https' --tlsv1.2 -fSLO \
  https://get.coblyn.gksistemas.es/releases/download/v1.17.0-rc.5/setup.sh
curl --proto '=https' --tlsv1.2 -fSLO \
  https://get.coblyn.gksistemas.es/releases/download/v1.17.0-rc.5/setup.sh.sha256
sha256sum --check setup.sh.sha256
less setup.sh

Para la primera instalación, usa el asistente y el perfil Web/API:

sudo bash ./setup.sh --release 1.17.0-rc.5 --testing --wizard

El bootstrapper descarga el tarball inmutable y su checksum, rechaza rutas o tipos de fichero inseguros, instala en /opt/coblyn y delega en coblyn/setup.sh. No uses modo desatendido hasta haber definido cómo custodiar los secretos y crear el primer administrador sin incluir contraseñas en CLI, cloud-init o logs.

Canal piloto

El canal get del VPS permite la validación desde hosts limpios y cada release publica un manifiesto Sigstore firmado por la identidad OIDC del workflow. El bootstrap inicial todavía sólo exige el checksum y falta mantener un mirror recuperable fuera del VPS; hasta automatizar esa verificación no se considera el origen de producción. Un checksum servido por el mismo origen no protege frente al compromiso completo de ese origen.

3. Revisar .env

El archivo operativo queda en:

cd /opt/coblyn/coblyn
sudo nano .env

Valores que debes revisar antes de produccion:

Variable	Uso
PXE_INTERFACE	Interfaz fisica o bridged por la que escucha Kea
PXE_SERVER_IP	IP del servidor en la red PXE
DHCP_MODE	dhcp para servidor autoritativo, proxy si ya existe DHCP
DHCP_RANGE_START / DHCP_RANGE_END	Rango para equipos autorizados
DHCP_QUARANTINE_START / DHCP_QUARANTINE_END	Rango aislado para equipos desconocidos
WEB_PORT	Puerto publicado por nginx
COBLYN_IMAGE_TAG	Debe ser versionado, por ejemplo v1.17.0; no uses latest
RUSTDESK_IMAGE	Imagen fija, por ejemplo rustdesk/rustdesk-server:1.1.14
CORS_ORIGINS	Origenes permitidos; no uses * en produccion

Secretos obligatorios en produccion:

• POSTGRES_PASSWORD
• REDIS_PASSWORD
• JWT_SECRET
• STORAGE_ENCRYPTION_KEY
• DHCP_WEBHOOK_SECRET
• BOOT_PROGRESS_SECRET
• MDM_ENROLLMENT_TOKEN

Normalmente el instalador los genera. Si vienes de un .env antiguo, ejecuta:

sudo ./setup.sh doctor --fix

4. Validar antes de arrancar

sudo ./setup.sh doctor

El doctor comprueba distribucion, Docker, Compose V2, .env, secretos, propagacion de variables a Compose, puertos, RAM y disco.

Si quieres ver el plan sin tocar el sistema:

sudo ./setup.sh install --dry-run

5. Arrancar el stack

En modo interactivo el instalador puede arrancar el stack al final. Si necesitas hacerlo manualmente:

docker compose up -d
docker compose ps
sudo ./setup.sh admin-bootstrap

Accede a:

http://<PXE_SERVER_IP>:<WEB_PORT>

El bootstrap solicita usuario y contraseña, sólo funciona mientras la base de datos no contenga usuarios y no persiste la credencial en .env. Acepta entre 15 y 128 caracteres, espacios y Unicode, sin reglas artificiales de composición; rechaza valores comunes o previsibles y repite el prompt si no coinciden las entradas o no se cumple la política.

Configuracion inicial despues del login

1. Entra en la UI con el administrador persistente que acabas de crear.
2. Abre Storage y crea un pool NFS o SMB/CIFS desde Storage Hub. No dependas del antiguo modelo de configuracion NFS plana.
3. Carga o descarga los activos de arranque necesarios en tftpboot/.
4. Verifica que docker compose ps no muestra servicios reiniciando.
5. Prueba un cliente PXE en la VLAN correcta y confirma que aparece en inventario o cuarentena.

Upgrade desde v1.x

Desde /opt/coblyn/coblyn:

sudo ./setup.sh backup
sudo ./setup.sh upgrade --auto
sudo ./setup.sh doctor

v1.17.0 introduce Alembic como autoridad de migraciones. En una instalación existente, primero verifica que el esquema heredado coincide exactamente con el modelo y solo entonces adopta el baseline:

docker compose exec backend python -m utils.migrations adopt-legacy
docker compose exec backend python -m utils.migrations verify

No ejecutes alembic stamp directamente: omite la comprobación de drift que protege datos heredados. En instalaciones nuevas o tras desplegar una revisión, aplica las migraciones como paso de despliegue y valida con python -m utils.migrations verify.

Backup y restore minimo

Backup operativo:

sudo ./setup.sh backup

El backup incluye .env, licencia, claves, Compose y datos persistentes relevantes en backups/.

Antes de cualquier upgrade:

sudo ./setup.sh backup
docker compose ps

Para un restore completo en otro host, conserva como minimo:

• Backup generado por setup.sh.
• Volumen PostgreSQL o dump de base de datos.
• license.key, keys/ y secretos del .env.
• Datos de RustDesk si quieres conservar claves de soporte remoto.
• Repositorios de imagenes gestionados por Storage Hub.

Release local

Para validar una release en un entorno Linux con Bash:

bash scripts/release-check.sh
bash scripts/package-release.sh

release-check.sh ejecuta checks de sintaxis, tests backend, heads de Alembic, lint/test/build de frontend, validacion de Compose y empaquetado. package-release.sh genera dist/coblyn-v<version>.tar.gz y su checksum.

Troubleshooting

El backend se reinicia con "Unsafe production configuration"

Hay secretos vacios, placeholders o CORS inseguro. Ejecuta:

sudo ./setup.sh doctor --fix
sudo ./setup.sh doctor
docker compose up -d

DHCP no responde

• Comprueba PXE_INTERFACE.
• Usa DHCP_MODE=proxy si existe un DHCP corporativo autoritativo.
• Revisa logs:

docker logs coblyn-dhcp-kea

El menu PXE no carga

curl http://<PXE_SERVER_IP>/tftpboot/menus/boot.ipxe
docker logs coblyn-tftp
docker logs coblyn-nginx

Storage Hub no monta un pool

• Comprueba conectividad NFS/SMB desde el host.
• Verifica credenciales en la UI de Storage.
• Ejecuta sudo ./setup.sh doctor para confirmar nfs-common y cifs-utils.

Docker no descarga imagenes

Verifica conectividad al registry configurado en COBLYN_REGISTRY. Si tu distribucion usa imagenes privadas, autentica antes:

docker login registry.gitlab.com
docker compose pull