Guía de instalación de STSDATA NexaOrch

El paquete stsagent-bundle-<versión>.tar.gz contiene la aplicación ya compilada, en imágenes de contenedor listas, más el script manage.sh, que cubre tanto una instalación nueva como la actualización de una existente. No hay código fuente aquí dentro y nada se compila en el servidor.

Qué trae el paquete

Requisitos previos

• Un servidor Linux de 64 bits con bash, curl, rsync y Podman (podman + podman compose). El comando de instalación cambia según la distribución — vea la sección siguiente.
• Distribuciones cubiertas por esta guía: Debian y Ubuntu; RHEL, Fedora, Rocky Linux y AlmaLinux; SUSE Linux Enterprise y openSUSE.
• No necesita .NET en el servidor — ni SDK, ni runtime. La aplicación corre dentro de las imágenes, y las herramientas de operación son autocontenidas.
• Espacio en disco: el paquete pesa cerca de 1,2 GB y extraerlo ocupa otro tanto. Deje ~3 GB libres en la carpeta donde lo extraiga.
• manage.sh necesita root: ejecútelo siempre con sudo.
• 🛑 Una base de datos ya creada, con usuario y contraseña propios — el instalador no crea base ni usuario, y leer y grabar no alcanza: NexaOrch aplica las migraciones por su cuenta en el primer arranque. Vea La base de datos: qué preparar antes.

La base de datos: qué preparar antes

🛑 El instalador no crea la base ni el usuario. Pide los datos de conexión de una base que ya existe. Si la base también va a correr en contenedor, levántela aparte antes (por ejemplo con Podman) y apunte el instalador hacia ella.

Antes de ejecutar manage.sh install, prepare tres cosas:

1. la base — en Oracle, el usuario/esquema; en Firebird, el archivo .fdb;
2. un usuario dedicado a NexaOrch, con contraseña;
3. los privilegios de ese usuario sobre esa base.

Por qué leer y grabar no alcanza

En el primer arranque, y en cada actualización, NexaOrch aplica las migraciones por su cuenta. No es opcional y no tiene botón: es el paso que crea y hace evolucionar el esquema. Estas son las operaciones que ejecuta, relevadas de las migraciones del propio producto:

⚠️ Un usuario solo con SELECT/INSERT/UPDATE/DELETE instala y se rompe en el primer arranque. El error viene de dentro de la migración y nombra el objeto que intentó crear — no el privilegio que faltó.

El privilegio, por proveedor

Reemplace nexaorchdb y nexaorchusr por los nombres que vaya a usar. Ejecute como administrador de la base, antes de instalar.

• PostgreSQL — el camino más simple es que el usuario sea dueño de la base: CREATE DATABASE nexaorchdb OWNER nexaorchusr; (o, si la base ya existe, ALTER DATABASE nexaorchdb OWNER TO nexaorchusr;). ⚠️ En PostgreSQL 15 o más nuevo esto dejó de ser un detalle: el esquema public ya no otorga CREATE a todo usuario. Sin ser dueño, el usuario conecta, lee — y falla al crear la primera tabla.
• MySQL / MariaDB — GRANT ALL PRIVILEGES ON nexaorchdb.* TO 'nexaorchusr'@'%'; seguido de FLUSH PRIVILEGES;. ⚠️ La primera migración ejecuta ALTER DATABASE … CHARACTER SET utf8mb4, que es privilegio sobre la base, no sobre una tabla. Un grant armado solo con verbos de tabla pasa la prueba de conexión y falla en la primera migración.
• SQL Server — cree el login y el usuario en la base y otorgue db_owner; si prefiere separarlo, db_ddladmin + db_datareader + db_datawriter cubren las operaciones de la tabla de arriba.
• Oracle — no hay “base” que crear: se crea el usuario/esquema. Necesita CREATE SESSION, CREATE TABLE y CREATE SEQUENCE (las claves primarias son columnas de identidad, y en Oracle se apoyan en una secuencia interna) — y cuota en el tablespace: ALTER USER nexaorchusr QUOTA UNLIMITED ON users;. 🛑 Sin la cuota, crear la primera tabla falla con ORA-01950 aun con todos los privilegios anteriores otorgados. Es el tropiezo más común aquí.
• Firebird — la base es un archivo. Cree el .fdb conectado como el usuario de NexaOrch, para que quede dueño de la base: quien no es dueño ni SYSDBA conecta y lee, pero no altera metadatos — y una migración es un cambio de metadatos.

Verifique antes de instalar, no durante

Pruebe la conexión desde el propio servidor donde va a correr NexaOrch, con el cliente nativo de la base y con el mismo usuario y contraseña que le dará al instalador:

• PostgreSQL — psql -h <host> -p 5432 -U nexaorchusr -d nexaorchdb -c "select 1"
• MySQL / MariaDB — mysql -h <host> -P 3306 -u nexaorchusr -p nexaorchdb -e "select 1"
• SQL Server — sqlcmd -S <host>,1433 -U nexaorchusr -P <contraseña> -d nexaorchdb -Q "select 1"
• Oracle — sqlplus nexaorchusr/<contraseña>@<host>:1521/<service-name>
• Firebird — isql-fb -u nexaorchusr -p <contraseña> <host>/3050:/ruta/nexaorchdb.fdb

⚠️ En Oracle, el campo “Base de datos” del instalador es el service name, no un nombre de catálogo como en los otros proveedores. Es el mismo valor que va después de la barra en el comando de arriba.

💡 La prueba de arriba demuestra credencial y alcance. No demuestra privilegio de DDL — para eso, CREATE TABLE prueba_nexaorch (id INT); DROP TABLE prueba_nexaorch; con el mismo usuario responde en dos comandos lo que la migración solo respondería en el primer arranque.

💡 El instalador rehace esa prueba de DDL por su cuenta, como sexta etapa de su verificación de base, y borra la tabla enseguida. Hacerla aquí sirve para descubrirlo antes, sin depender de llegar hasta allá con el asistente entero ya respondido.

Requisitos previos por distribución

Vaya directo al bloque de la familia de su distribución; no hace falta leer los demás. Cada bloque trae el comando de instalación, la verificación de que quedó listo y qué confirmar antes de seguir.

⚠️ Haga la verificación antes de continuar. Un requisito que falta en silencio reaparece tres pasos más adelante, con un error que no menciona el paso que faltó.

Debian, Ubuntu y derivados

sudo apt update
sudo apt install podman podman-compose uidmap

Confirme que quedó listo:

podman --version
podman compose version
command -v newuidmap newgidmap

• SELinux: no aplica — esta familia usa AppArmor.
• Rootless: el paquete uidmap trae newuidmap/newgidmap, que el Worker necesita para arrancar sin privilegios. Si el command -v de arriba no responde ambas rutas, el contenedor no arranca.
• Firewall (ufw): libere el puerto por el que se accederá a la pantalla. Los valores por defecto son 8081 (HTTPS) y 8080 (HTTP); si elige otros en la instalación, libere esos — son puertos del host, y se pueden cambiar.

RHEL, Fedora, Rocky Linux y AlmaLinux

Este bloque vale para toda la familia: si usted está en Rocky Linux o en AlmaLinux, es aquí.

sudo dnf install podman podman-compose shadow-utils

⚠️ En RHEL, Rocky y Alma, podman-compose suele no estar en el repositorio base. Si el comando anterior no lo encuentra, habilite EPEL y repita:

sudo dnf install epel-release

Confirme que quedó listo:

podman --version
podman compose version
command -v newuidmap newgidmap

🛑 SELinux — verifique antes de seguir. Solo esta familia viene con SELinux activo por defecto:

getenforce

• Enforcing es lo esperado, y es el modo para el que el producto está preparado: los volúmenes de los contenedores se montan con reetiquetado automático.

• Permissive o Disabled significa que SELinux no está bloqueando nada. La instalación funciona — pero, si usted está probando el producto, un resultado así invalida la verificación del reetiquetado: la prueba pasaría aunque hubiera un defecto ahí.

• Rootless: shadow-utils trae newuidmap/newgidmap.

• Firewall (firewalld): libere el puerto por el que se accederá a la pantalla. Los valores por defecto son 8081 (HTTPS) y 8080 (HTTP); si elige otros en la instalación, libere esos — son puertos del host, y se pueden cambiar.

SUSE Linux Enterprise y openSUSE

sudo zypper install podman podman-compose shadow

Confirme que quedó listo:

podman --version
podman compose version
command -v newuidmap newgidmap

• SELinux: no aplica en la configuración por defecto — esta familia usa AppArmor.
• Rootless: el paquete shadow trae newuidmap/newgidmap.
• Firewall (firewalld): libere el puerto por el que se accederá a la pantalla. Los valores por defecto son 8081 (HTTPS) y 8080 (HTTP); si elige otros en la instalación, libere esos — son puertos del host, y se pueden cambiar.

Lo que esta guía no hace. Dice qué necesita NexaOrch que exista en la máquina y cómo comprobar que existe. Configurar el firewall, crear cuentas o ajustar rangos de subuid/subgid a fondo es administración del servidor, y sigue siendo de quien lo administra.

Instalación nueva

Use este camino si el servidor aún no tiene una instalación de NexaOrch.

Extraiga el paquete en cualquier carpeta — no tiene que ser el destino final, porque la instalación va a /opt/nexaorch:

⚠️ Un servidor que ya tiene una instalación anterior a esta versión conserva el nombre antiguo. Hasta esta versión, la cuenta de servicio, la carpeta y los contenedores se llamaban stsagent, /opt/stsagent y stsagent_ui_1 / stsagent_worker_1. Nada de eso se renombra: un update mantiene los nombres que la instalación ya tiene, a propósito. Esta guía usa los nombres NUEVOS; si su instalación es anterior, lea stsagent donde diga nexaorch. Para comprobarlo sin adivinar: sudo ./manage.sh runtime-names.

tar -xzf stsagent-bundle-<versión>.tar.gz
cd stsagent-bundle-<versión>

Ejecute el instalador:

sudo ./manage.sh install

El asistente pregunta todo lo que falta para poner el sistema en marcha:

• Base de datos — los datos de conexión de una base ya existente (host, puerto, nombre, usuario, contraseña). El asistente no levanta una base nueva por usted: si también quiere que la base corra en contenedor, levántela usted mismo (por ejemplo mediante Podman) antes de ejecutar el instalador, y apunte hacia ella aquí.
• Cuenta de administrador — contraseña generada automáticamente o escrita. No existe contraseña predeterminada: o usted la define aquí, o el sistema la solicita en el primer acceso a la pantalla (vea Primer acceso).
• Empresa, notificación por correo (SMTP), ejecución e integración con IA (Ollama) — las mismas secciones de la pantalla Configuración, grabadas en la base antes del primer inicio de sesión.
• Carpetas del host — datos del Worker, descargas públicas, claves SSH, transferencia de archivos y copias de seguridad.
• Arrancar tras un reinicio — opcionalmente, una unidad systemd. Vea Arrancar solo después de un reinicio.

Al final, dos contenedores (ui y worker) se levantan con podman compose, todos aislados bajo una cuenta de servicio dedicada — nexaorch por defecto, y no el usuario que ejecutó el comando.

Cuando la instalación termina, no queda nada por ejecutar: los contenedores ya están funcionando y la última línea de la pantalla trae la dirección de acceso. En particular, no llame a podman compose a mano — en el servidor no funciona con el entorno de su usuario, por el motivo que explica la sección Hablar con compose sin el manage.sh, al final de esta guía.

Certificado HTTPS

Este paquete no trae certificado. En una instalación nueva, manage.sh genera uno autofirmado en el propio servidor, con contraseña aleatoria: cada instalación se queda con su clave, y nada secreto viaja por la página de descargas, que es pública.

Sirve para levantar el sistema y comprobar que todo responde. No sirve como certificado de producción, y el navegador avisará. Para cambiarlo por uno propio, sin reinstalar:

sudo ./manage.sh set-certificate --pfx mi-certificado.pfx --password CONTRASEÑA
sudo ./manage.sh set-certificate --crt mio.crt --key mia.key
sudo ./manage.sh set-certificate --self-signed --hosts 10.0.0.180,nexaorch.local

Reinstalando encima: la contraseña del certificado que ya existe

En una reinstalación, el certificado que ya está en el servidor no se sustituye: la instalación reutiliza el archivo y la contraseña que están allí, sin preguntar nada.

Solo pregunta “Password for the existing certificate” cuando la contraseña guardada en el .env no abre el archivo — el caso de quien cambió el .pfx a mano sin actualizar el .env. Esa contraseña no la eligió usted: es aleatoria, generada por la instalación anterior, y está en el .env de la instalación.

sudo grep HTTPS_CERT_PASSWORD /opt/nexaorch/.env

Si nadie tiene esa contraseña, pida cambiar el certificado: la instalación genera uno autofirmado nuevo allí mismo, en el servidor, con la IP y el nombre de esta máquina en el campo SAN — archivo y contraseña guardados juntos — y llega hasta el final.

Si la instalación ya está en marcha, lo mismo se resuelve sin reinstalar nada:

sudo /opt/nexaorch/manage.sh set-certificate --self-signed --hosts 10.0.0.180,nexaorch.local

Actualización

Use este camino si el servidor ya tiene una instalación funcionando y quiere llevarla a esta versión.

Copie el paquete al servidor y extráigalo:

tar -xzf stsagent-bundle-<versión>.tar.gz
cd stsagent-bundle-<versión>

Ejecute la actualización desde dentro de la carpeta extraída — es de ahí de donde salen las imágenes de esta versión:

sudo ./manage.sh update

La actualización no repite las preguntas de base, SMTP, empresa, ejecución y Ollama, no toca las bases ya aprovisionadas y preserva .env, el certificado y las carpetas de datos del Worker. Solo carga las imágenes nuevas y recrea los contenedores. Las migraciones de base pendientes corren solas al arrancar la UI.

Volver a la versión anterior

Antes de recrear los contenedores, el script etiqueta las imágenes en uso como :previous. Si la versión nueva no arranca correctamente:

sudo /opt/nexaorch/manage.sh rollback

Vuelve a las imágenes anteriores, sin necesitar el paquete antiguo.

Arrancar solo después de un reinicio

La instalación ofrece grabar una unidad systemd que levanta los contenedores en el arranque. Si lo rechazó en su momento y cambió de idea, o quiere desactivarlo después, no hace falta editar /etc/systemd/system a mano:

sudo /opt/nexaorch/manage.sh enable-boot
sudo /opt/nexaorch/manage.sh disable-boot

Por qué esto importa más de lo que parece. La unidad graba qué servicios levanta este host. Sin ese dato haría un compose up -d a secas y levantaría todos los servicios del archivo — incluida la UI en un host que solo debería ejecutar el Worker, ocupando puertos que allí pertenecen a otra cosa. El despliegue siempre respetó el recorte de servicios; era el arranque el que no lo hacía, y el problema solo aparecía tras un reinicio, lejos del cambio que lo causó.

Host solo de Worker

Un servidor puede ejecutar solo el Automation Agent, sin el Portal — es el arreglo habitual cuando la ejecución tiene que ocurrir cerca de una base de datos o de un recurso compartido, y el Portal vive en otro sitio.

Ese recorte queda grabado en el propio host, en STS_SERVICES dentro del .env de la instalación. Es lo que hace que una llamada manual (up, rollback, switch-connection) siga sabiendo que ese host no tiene UI — antes, cada invocación manual volvía al valor por defecto “ui worker” e iba a buscar una imagen que nunca se envió allí.

Licencia de la instalación

NexaOrch se licencia por instalación. No existe un código por Automation Agent: el paquete los licencia a todos.

Cómo se obtiene el archivo .lic

El código de esta instalación no lo aporta usted: NexaOrch lo genera la primera vez que arranca y lo muestra en Configuración → Licencia, con un formato como LIC-FQCH-EGS0-J2GC-GSHQ.

Las instalaciones creadas antes de agosto de 2026 muestran el mismo código con el prefijo NEXA-, y lo conservan para siempre: no hay nada que actualizar. El prefijo forma parte del código: copie siempre lo que muestra la pantalla, entero. LIC-ABCD-… y NEXA-ABCD-… son instalaciones distintas.

1. Instale — nada se bloquea sin licencia.
2. Abra Configuración → Licencia y copie el código de la instalación, con el prefijo.
3. Facilite ese código al comprar o renovar.
4. Recibirá un archivo .lic ligado a él: válido en esta instalación y en ninguna otra.
5. Impórtelo en la misma pantalla. Sin reinstalar y sin detener nada.

manage.sh install no pregunta nada sobre licencias. Instalar sin licencia es el camino normal — así funcionan las evaluaciones, las pruebas de concepto y los laboratorios.

Los Agents se licencian solos

El .lic dice cuántos Agents compró, y ellos ocupan las plazas por orden de llegada, sin ninguna configuración en cada servidor. Importada la licencia, los Agents que ya existen quedan conformes al instante. Un Agent instalado después toma una plaza libre solo, en el primer minuto en que arranque.

Necesita un Agent más: no existe licencia suelta de Agent. Compra la ampliación y recibe un .lic nuevo de esta misma instalación, ahora con más Agents incluidos. Impórtelo en la misma pantalla — comprar, renovar y ampliar son el mismo gesto.

Cuando no queda plaza: mientras no se haya importado ninguna licencia, no ocurre nada. Con una licencia en vigor, un Agent por encima del número incluido no toma trabajo nuevo; las ejecuciones en curso terminan con normalidad y los demás Agents no se ven afectados. La validación se hace en su propio servidor — NexaOrch nunca necesita internet para comprobar una licencia.

Evaluación y modo restringido

Una instalación nueva nace con 15 días de evaluación, con el producto completo: nada se recorta durante la prueba, porque un producto recortado no permite evaluar. El aviso en pantalla empieza a partir del día 10.

La tolerancia de 7 días existe por un motivo operativo: NexaOrch ejecuta cargas nocturnas. Una licencia que expira a medianoche con corte inmediato significa una carga que no corre, sin nadie despierto para importar un archivo — y el cliente se entera a las 8 con el BI vacío, justo el día en que estaba renovando.

En modo restringido se deniega la escritura y la interfaz queda en solo lectura. Los procesos, el historial y las conexiones siguen donde están; importar la licencia lo desbloquea al instante.

Las instalaciones que ya existían antes del régimen de prueba no entran en evaluación: su fecha de creación nace vacía, y vacío significa “sin prueba”, no “prueba empezando ahora”. El régimen vale para quien nace en él.

Publicación: directa o detrás de un proxy inverso

NexaOrch funciona de las dos formas, elegida por configuración y cambiable después, sin reinstalar.

Modo directo (por defecto)

El propio sistema sirve HTTPS, con el certificado en /opt/nexaorch/https/aspnetapp.pfx. El acceso es por IP.

La instalación genera ese certificado ya con la IP y el nombre de esta máquina en el campo SAN — es decir, la dirección coincide. Aun así el navegador avisa, porque es autofirmado: nadie salvo el propio servidor reconoce al emisor. Son cosas distintas, y solo queda la segunda:

• Dirección equivocada → resuelto por la instalación, o reemita con --hosts
• Emisor desconocido → resuelto importando el certificado

Si el servidor cambia de IP o de nombre, reemita:

sudo /opt/nexaorch/manage.sh set-certificate --self-signed
sudo /opt/nexaorch/manage.sh set-certificate --self-signed --hosts 10.0.0.180,nexaorch.local

Cómo quitar el aviso del navegador

La instalación deja el certificado público en /opt/nexaorch/https/aspnetapp.crt. Distribuya ese archivo — no contiene clave privada; no envíe el .pfx — e impórtelo como autoridad de confianza en las máquinas que usan el sistema.

• Windows, máquina a máquina: certlm.msc → Entidades de certificación raíz de confianza → Certificados → importar el aspnetapp.crt.
• Windows, todo el dominio de una vez (recomendado cuando hay AD): Directiva de grupo → Configuración del equipo → Directivas → Configuración de Windows → Configuración de seguridad → Directivas de clave pública → Entidades de certificación raíz de confianza → Importar.
• Firefox usa su propio almacén: Configuración → Privacidad y seguridad → Certificados → Ver certificados → Autoridades → Importar.

Si tiene una CA corporativa, emitir por ella es el mejor camino — las máquinas del dominio ya confían en esa CA, y no hay nada que distribuir:

sudo /opt/nexaorch/manage.sh set-certificate --pfx /ruta/cert.pfx --password '<contraseña>'
sudo /opt/nexaorch/manage.sh set-certificate --crt /ruta/cert.crt --key /ruta/cert.key

Detrás de un proxy inverso (recomendado cuando hay nombre DNS)

Un nginx termina el TLS con un certificado emitido para el nombre y reenvía HTTP a NexaOrch. Es el arreglo que elimina el aviso del navegador sin instalar nada en las máquinas de los usuarios — un certificado de CA pública solo existe para un nombre, nunca para una IP privada.

sudo /opt/nexaorch/manage.sh set-proxy-mode --proxy 10.0.0.5
sudo /opt/nexaorch/manage.sh set-proxy-mode --proxy 10.0.1.0/24
sudo /opt/nexaorch/manage.sh set-proxy-mode --proxy off

La IP indicada es la del proxy. Sin ella el sistema ignora las cabeceras X-Forwarded-*, y el resultado es un bucle de redirección y un inicio de sesión que nunca completa. En ese modo el sistema pasa a escuchar solo HTTP en el 8080.

El tramo entre el proxy y el sistema va en texto claro. Cuando nginx está en otro servidor, ese tramo atraviesa la red — y la cookie de autenticación viaja en él. Es el mismo arreglo que usan Gitea, pgAdmin y la mayoría de aplicaciones tras un proxy, y es aceptable cuando ambos están en la misma red de confianza. Dos medidas no son opcionales: abra el puerto 8080 en el firewall solo para la IP del proxy, y mantenga proxy y sistema en la misma VLAN, nunca con internet o una red de invitados de por medio.

Ejemplo de configuración — los tres ajustes marcados son exigencia de este sistema, no formalidad:

server {
    listen 443 ssl;
    server_name nexaorch.cliente.com;

    ssl_certificate     /etc/letsencrypt/live/nexaorch.cliente.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/nexaorch.cliente.com/privkey.pem;

    # la importación de paquetes acepta 11 MB; el valor por defecto de nginx es 1 MB
    client_max_body_size 12m;

    location / {
        proxy_pass http://10.0.0.180:8080;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        # sin esta línea: bucle de redirección
        proxy_set_header X-Forwarded-Proto $scheme;
        # sin esta línea (o con un valor corto): "la pantalla se colgó" en las pantallas de vista previa — vea abajo
        proxy_read_timeout 300s;
    }

    location /downloads/ {
        proxy_pass http://10.0.0.180:8080;
        # la página pública sirve el paquete de ~1,2 GB
        proxy_buffering off;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

🛑 El timeout del proxy y las pantallas de vista previa (la pantalla que se “cuelga”)

El proxy_read_timeout del ejemplo anterior no es una formalidad: cuatro pantallas piden al servidor abrir una conexión con una base de datos de terceros y leer de ella antes de responder. En una tabla grande — muchas filas y, sobre todo, muchas columnas — eso supera fácilmente los 60 segundos que nginx espera por defecto.

Las rutas, por su nombre:

⚠️ No sirve crear un location para esas rutas. El ?handler= es query string, y el location de nginx compara solo la ruta — por eso el ajuste va en el location /, como en el ejemplo, y vale para todo el sistema. Si prefiere separarlo, el recorte posible es por página (/SharedCommands/Edit y /Jobs/Step), nunca por handler.

Qué pasa sin el ajuste — y esto es lo que usted necesita reconocer después. Nginx se rinde antes de que el sistema responda y devuelve su propia página de error 504. La pantalla esperaba JSON, recibe HTML, y lo que ve el operador es algo como:

SyntaxError: Unexpected token '<', "<html> <h"... is not valid JSON

🛑 Nada en ese mensaje apunta al proxy. Quien opera reporta “la pantalla se colgó” o “dio error de JavaScript”, y el problema se busca en el sistema, en la base, en el navegador — nunca en nginx. Si usted ve ese error solo en las pantallas de vista previa y solo con tablas grandes, el sospechoso es este parámetro, y la confirmación está en el error.log de nginx (upstream timed out).

300s es un punto de partida, no una medición. Si la lectura del origen legítimamente demora más, el número sube; si prefiere que el operador reciba el error rápido, baja — pero entonces la vista previa de tabla grande deja de funcionar, y esa es la elección que se está haciendo.

⚠️ Instalación que ya está en producción. La línea entró en esta guía después de que la mayoría de las instalaciones existentes fueran configuradas — el archivo que corre hoy puede no tenerla. Revise el location / de su server, agregue la línea si falta, y recargue con nginx -t && systemctl reload nginx. Nada en el sistema necesita reiniciarse.

Primer acceso

Cuando la instalación se hace por el asistente (manage.sh install), la cuenta de administrador y los datos de la empresa ya se graban allí, y usted entra directamente en la pantalla de inicio de sesión.

Una base que no pasó por el asistente — por ejemplo, al apuntar la aplicación a una base nueva con switch-connection, o al restaurar una copia en una base limpia — abre en el primer acceso: la propia pantalla solicita la contraseña del administrador (si aún no hay ninguno) y, a continuación, los datos de la empresa. Al final muestra el código de esta instalación, que es el que usted informa a STSDATA para licenciarla. El mismo código está siempre disponible en Configuración › Licencia.

Rellenar los datos de la empresa es obligatorio: ese paso es el que da identidad a la instalación.

Cuando la conexión con la base falla

Vale para todas las distribuciones. Los bloques por familia, más abajo, traen solo lo que cambia: firewall, SELinux y nombre del servicio.

💡 Empiece por lo que el instalador ya respondió

Si la falla ocurrió durante la instalación, no empiece probando a mano: el instalador ya hizo el diagnóstico y ya lo escribió todo. Verifica la base en seis etapas — el nombre resuelve, el puerto acepta TCP, el servidor completa el protocolo, la credencial es aceptada, la base es alcanzable, y el usuario crea y borra una tabla:

  [OK]      host 'db.ejemplo.local' resolves (10.0.0.7)
  [OK]      port 5432 accepts TCP
  [FAILED]  credentials accepted for user 'nexaorchusr'
            no pg_hba.conf entry for host "10.0.0.7", user "nexaorchusr"
            -> PostgreSQL refused this origin (pg_hba.conf), not the password. ...
  [SKIPPED] database 'nexaorchdb' is reachable

• la etapa que falla dice la causa y qué verificar; las siguientes salen como [SKIPPED], y nunca en blanco;
• escribe un archivo de registro e imprime la ruta en pantalla, incluso cuando todo pasa. ⚠️ Ese registro nunca contiene la contraseña, ni su longitud;
• 🛑 imprime con qué usuario del sistema operativo se está conectando. El instalador corre como la cuenta de servicio, no como quien escribió el comando — y con peer o ident en el pg_hba.conf ese es el nombre que la base ve. Por eso «lo probé en DBeaver y funciona» puede ser verdad mientras el instalador falla.

Dos acciones responden sin cambiar nada, y son el comienzo de cualquier verificación:

sudo ./manage.sh runtime-names   # cuenta de servicio, carpeta y prefijo de contenedores de esta máquina
sudo ./manage.sh pg-hba-path     # dónde está el pg_hba.conf (le pregunta primero al servidor)

El resto de esta sección vale para lo que el instalador no alcanza: lo que ocurre después de que termina, y la prueba manual, cuando quiere separar «la base rechaza» de «NexaOrch rechaza».

🛑 ¿La base está “en el mismo servidor”? Entonces localhost no sirve

NexaOrch corre dentro de un contenedor. Ahí adentro, localhost es el propio contenedor — no el servidor. Apuntar la cadena de conexión a localhost con la base instalada en el host da “conexión rechazada” aun con la base arriba y la credencial correcta, y es el error más común de esta instalación.

Use, en lugar de localhost:

• host.containers.internal, en las versiones de Podman que lo publican; o
• la IP del servidor en la red (la misma que usaría desde otra máquina).

💡 Confírmelo con sudo ./manage.sh logs ui --lines 50 apenas levante: el error de conexión aparece ahí, con el host que realmente intentó.

Los cuatro desenlaces, y qué quiere decir cada uno

Pruebe desde el servidor, con el cliente nativo (comandos en La base de datos: qué preparar antes). Lo que vuelva dice dónde está el problema:

⚠️ El cuarto es el que no parece problema de conexión. La conexión funcionó; lo que faltó fue CREATE TABLE. Si la prueba de conexión pasa y la instalación se rompe enseguida, empiece por ahí.

💡 Dónde está el pg_hba.conf — pregúntele al servidor, no a la distribución

La ruta cambia según la familia, y cualquier lista envejece. El propio PostgreSQL responde:

sudo -u postgres psql -tAc 'SHOW hba_file'

Las rutas por familia, para cuando el servidor no esté levantado:

💡 El instalador intenta abrir ese archivo para la red de Podman por su cuenta, y dice en pantalla qué hizo. Si no encuentra el archivo, lo avisa en vez de quedarse callado — y sudo ./manage.sh pg-hba-path muestra dónde buscó.

Debian, Ubuntu y derivados

• Firewall: sudo ufw status. Si está activo, abra el puerto de la base hacia el servidor — por ejemplo sudo ufw allow from <ip-del-servidor> to any port 5432 proto tcp.
• Servicio de la base, cuando es local: systemctl status postgresql (o mysql, mariadb, firebird).
• PostgreSQL local: por defecto escucha solo en localhost. Para aceptar al contenedor, ajuste listen_addresses en postgresql.conf y agregue la línea correspondiente en pg_hba.conf.

RHEL, Fedora, Rocky Linux y AlmaLinux

• Firewall: sudo firewall-cmd --list-all. Para abrir: sudo firewall-cmd --add-port=5432/tcp --permanent && sudo firewall-cmd --reload.
• SELinux: con SELinux en enforcing, la salida de un contenedor hacia un servicio del host puede ser denegada. Verifique con getsebool -a | grep container_connect y mire sudo ausearch -m avc -ts recent después de un intento — un denied ahí marca el camino.
• Servicio de la base, cuando es local: systemctl status postgresql (o mariadb).

SUSE Linux Enterprise y openSUSE

• Firewall: sudo firewall-cmd --list-all — las versiones actuales de SUSE usan firewalld. Los mismos comandos del bloque anterior.
• SELinux/AppArmor: SUSE usa AppArmor por defecto; si está activo para Podman, sudo aa-status muestra los perfiles en modo enforce.
• Servicio de la base, cuando es local: systemctl status postgresql (o mariadb).

Si nada de lo anterior lo explica

Junte estas salidas antes de abrir un ticket — juntas responden casi toda pregunta que haría el soporte:

sudo ./manage.sh version
sudo ./manage.sh logs ui --lines 200

⚠️ No pegue la salida de comandos podman ejecutados a mano: compose imprime la línea entera del podman run, con la contraseña de la base y la del certificado en texto claro. manage.sh la filtra; un comando suelto, no.

Ha perdido la contraseña de administrador

El sistema no tiene “he olvidado mi contraseña”, y no hay forma de crear un administrador nuevo en una base que ya tiene usuarios. Si el único administrador pierde la contraseña — o queda bloqueado por intentos fallidos — el camino de vuelta es este comando, en el propio servidor:

sudo /opt/nexaorch/manage.sh reset-password --list
sudo /opt/nexaorch/manage.sh reset-password --user admin
sudo /opt/nexaorch/manage.sh reset-password --user admin --password 'NuevaClave@2026'

La contraseña nueva necesita al menos 10 caracteres y al menos uno que no sea letra ni dígito — la misma regla de la pantalla de usuarios. Si no pasa, el comando rechaza y no altera nada.

Omitiendo --password el comando pregunta en el terminal, sin mostrar lo que escribe. Prefiera esa forma: lo que va en la línea de comandos queda visible para los demás usuarios de la máquina, con ps.

Al restablecer, las sesiones abiertas de ese usuario caen. Un usuario inactivo sigue sin poder entrar aunque tenga la contraseña nueva — reactívelo en la pantalla de usuarios. Un usuario en la Papelera hay que restaurarlo primero; el comando avisa cuando es el caso.

Otros comandos

sudo /opt/nexaorch/manage.sh version     # versión instalada y estado de los contenedores
sudo /opt/nexaorch/manage.sh logs ui     # registro del contenedor de la UI
sudo /opt/nexaorch/manage.sh logs worker # registro del contenedor del Worker
sudo /opt/nexaorch/manage.sh up          # (re)levanta los contenedores ya cargados
sudo /opt/nexaorch/manage.sh down        # DETIENE la instalación (no desinstala)
sudo /opt/nexaorch/manage.sh down worker # detiene solo el Worker (la UI sigue arriba)

Detener la instalación

sudo /opt/nexaorch/manage.sh down          # detiene todo
sudo /opt/nexaorch/manage.sh down worker   # detiene solo el Worker
sudo /opt/nexaorch/manage.sh down ui       # detiene solo la UI

down detiene; no desinstala. Ningún volumen ni dato se eliminan — para quitar la instalación existe uninstall. Al final, el comando lista lo que quedó arriba.

Cuando el arranque automático está activado, un down sin argumento detiene por la unidad de systemd, y no por fuera de ella: así systemd no queda creyendo que la aplicación sigue arriba. Detener un solo servicio no toca la unidad — tras un reinicio vuelve a levantarse (use disable-boot si no es eso lo que quiere).

Hablar con compose sin el manage.sh

Si necesita llamar a podman compose directamente, no funciona con el entorno de su usuario: este servidor tiene el complemento compose de Docker instalado, y el comando intenta un socket que la cuenta de servicio no expone, fallando con failed to connect to the docker API at unix:///run/user/<uid>/podman/podman.sock. La invocación correcta es:

sudo -u nexaorch env \
  XDG_RUNTIME_DIR=/run/user/$(id -u nexaorch) \
  HOME=/opt/nexaorch \
  PODMAN_COMPOSE_PROVIDER=podman-compose \
  podman compose -p nexaorch -f /opt/nexaorch/docker-compose.prod.yml ps

El manage.sh ya hace exactamente esto internamente — prefiéralo siempre que haya un comando listo.

Mover la base de datos

sudo /opt/nexaorch/manage.sh switch-connection --provider <P> --connection '<cadena>'

Apunta la instalación a otra base. No migra ningún dato — úselo cuando la base sigue siendo la misma, pero cambió de IP, puerto o contraseña.

Migrar a otro proveedor de base de datos

sudo /opt/nexaorch/manage.sh migrate-provider

Copia los datos de esta instalación a otra base (por ejemplo, Firebird → PostgreSQL). Interactivo: pregunta origen y destino, y el origen solo se lee, nunca se altera.

Detiene los contenedores antes de copiar y los deja parados al final — con el Automation Agent en marcha el origen sería un blanco móvil, y una ejecución que empiece después de copiarse su tabla no llegaría al destino.

No reapunta la instalación. Al terminar, ejecute switch-connection para pasar a usar la base nueva, o up para volver a la de hoy.

Eliminar la instalación

sudo /opt/nexaorch/manage.sh uninstall

Elimina esta instalación: contenedores, imágenes, la red y la cuenta de servicio, en ese orden — invertirlo bloquea la máquina. Y pregunta antes de eliminar una carpeta de datos que esté fuera del directorio de instalación.

🛑 La base de datos NO se toca. Nada en uninstall borra datos: las definiciones de Job, el historial de ejecuciones, las conexiones, las credenciales cifradas y los usuarios siguen donde están. El propio comando lo avisa en pantalla, antes de pedir confirmación.

Es lo deseable en la mayoría de los casos — reinstalar encima reencuentra todo. Si usted realmente quiere descartar los datos, eso es un paso aparte, al final de esta guía: Eliminar también la base de datos.

Ajuste las rutas si STS_INSTALL_DIR se personalizó en la instalación original.

Eliminar también la base de datos

Esta sección está fuera de la secuencia de instalación a propósito, y nada de lo que hay aquí es necesario para eliminar el producto: uninstall ya lo resolvió y no tocó la base de datos. Lea esta parte solo si la decisión es descartar los datos.

🛑 No hay vuelta atrás

Borrar la base de datos es la acción más destructiva ligada a este producto. No existe deshacer, ni papelera. Lo que se pierde:

• las definiciones de Job y sus etapas — todo el trabajo de quien montó las automatizaciones;
• el historial de ejecuciones, con registros y estadísticas;
• las conexiones y las credenciales cifradas;
• los usuarios, roles y permisos;
• la licencia importada y la identidad de esta instalación.

⚠️ Un detalle que suele sorprender: el usuario con el que la aplicación se conecta normalmente no tiene permiso para crear bases de datos. Quien la borra en general no puede recrearla solo — necesitará a alguien con privilegios de administración en el servidor de base de datos. Confírmelo antes, no después.

El comando, por proveedor

Los comandos de abajo están en texto y no en bloque de código, a propósito: no deben copiarse de corrido junto con los comandos de instalación. Escriba el suyo, sustituyendo <nombre-de-la-base> por el nombre real — que está en DEFAULT_CONNECTION_STRING, en el archivo .env de la instalación, antes de que usted elimine la instalación.

• MySQL / MariaDB — conéctese con mysql -u <admin> -p y ejecute: DROP DATABASE <nombre-de-la-base>;
• PostgreSQL — conéctese con psql -U <admin> y ejecute: DROP DATABASE <nombre-de-la-base>;
• SQL Server — conéctese con sqlcmd -S <host> -U <admin> y ejecute: DROP DATABASE <nombre-de-la-base>;
• Oracle — no se borra una “base”: se elimina el usuario/esquema, con DROP USER <usuario> CASCADE; ejecutado por alguien con privilegios de DBA.
• Firebird — no hay DROP DATABASE remoto: la base es un archivo. Detenga el servicio y borre el .fdb indicado en la cadena de conexión (por defecto /opt/firebird/data/nexaorchdb.fdb).

⚠️ Antes de cualquiera de ellos, una copia de seguridad resuelve el arrepentimiento que el DROP no resuelve.