Des del codi font

Compila AnsibleForms des del codi font i executa’l amb Node.js

Com està organitzat el codi
Requisits previs
Obtenir el codi
Compilar
Configurar
Executar
Primera execució

Com està organitzat el codi

El repositori conté dues aplicacions Node.js, i una compilació les combina en una de sola:

client : la interfície web, escrita en Vue 3 i compilada en fitxers estàtics amb Vite
server : l’API, escrita amb Express. Lliura les tasques als runners, es connecta a la base de dades i serveix el client compilat. Iniciat amb AF_ROLE=rte, el mateix servidor és l’RTE (runtime environment, entorn d’execució) que executa els playbooks

Només es compila el client; el resultat va a la carpeta views del servidor, com a la imatge de Docker.

Requisits previs

Compilar i executar des del codi font requereix bons coneixements de Linux i una mica de Node.js. Instal·les tu mateix cada component. Per executar AnsibleForms sense contenidors i sense compilar-lo, la instal·lació nativa de l’instal·lador ho fa tot per tu:

Node.js 26 (la versió de .nvmrc; com a mínim 24), amb npm
Git, per obtenir el codi i sincronitzar repositoris
Client OpenSSH, per a git per SSH, i sshpass, per als playbooks que es connecten amb una contrasenya SSH
Client de MariaDB (mariadb, mariadb-dump), per a les còpies de seguretat i les restauracions, també amb un servidor MySQL
MySQL 8+ o MariaDB, accessible des del servidor
Ansible, per al procés RTE que executa els playbooks (ansible-playbook al seu path). El procés de l’aplicació en si no necessita ni Ansible ni Python, i amb només formularis de plantilles (AWX, AAP, Ascender i els altres runners) no necessites cap RTE

Instal·la’ls per a la teva distribució:

Node.js 26 ve del repositori de NodeSource, i les altres eines del mateix Ubuntu:

curl -fsSL https://deb.nodesource.com/setup_26.x | sudo -E bash -
sudo apt-get install -y nodejs git openssh-client sshpass mariadb-client python3 python3-pip ansible

Node.js 26 ve del repositori de NodeSource, i les altres eines del mateix Debian:

curl -fsSL https://deb.nodesource.com/setup_26.x | sudo -E bash -
sudo apt-get install -y nodejs git openssh-client sshpass mariadb-client python3 python3-pip ansible

Node.js ve de NodeSource i sshpass d’EPEL (al mateix RHEL, activa EPEL tal com ho documenta Red Hat):

curl -fsSL https://rpm.nodesource.com/setup_26.x | sudo bash -
sudo dnf install -y epel-release
sudo dnf install -y nodejs git openssh-clients sshpass mariadb python3 python3-pip ansible-core

Comprova node --version (26) i ansible-playbook --version; per a la base de dades i el seu usuari, consulta Instal·lar MySQL.

Obtenir el codi

Clona el repositori en una carpeta que triïs, propietat de l’usuari que executarà l’aplicació. Els exemples fan servir /srv/apps/ansibleforms:

sudo mkdir -p /srv/apps
sudo chown $USER /srv/apps
cd /srv/apps
git clone https://github.com/ansibleforms/ansibleforms.git
cd ansibleforms

Compilar

Compila en tres passos, des de la carpeta del repositori. Primer compila el client:

cd client
npm ci
npm run build

Després instal·la les dependències del servidor:

cd ../server
npm ci --omit=dev

Finalment copia el client compilat a la carpeta views del servidor:

rm -rf views
mkdir views
cp -r ../client/dist/. views/

Configurar

El servidor llegeix la seva configuració de variables d’entorn i, en producció, també de server/persistent/.env, el fitxer on escriuen les pàgines de configuració.

Parteix del fitxer d’exemple de l’arrel del repositori i defineix com a mínim la connexió a MySQL (DB_HOST, DB_PORT, DB_USER, DB_PASSWORD):

cd /srv/apps/ansibleforms/server
mkdir -p persistent
cp ../.env.example persistent/.env

Totes les variables es descriuen a Variables d’entorn. Tota la resta es desa a server/persistent per defecte: config.yaml, la carpeta forms i els certificats autosignats s’hi creen en el primer inici, al costat dels registres. Posa els teus playbooks a server/persistent/playbooks, o fes que ANSIBLE_PATH apunti a un altre lloc a l’entorn de l’RTE, que és qui el llegeix.

Executar

Executa AnsibleForms en producció, o en mode de desenvolupament per treballar en el codi mateix:

Inicia el servidor en mode de producció des de la carpeta server:

cd /srv/apps/ansibleforms/server
npm run start

Una aplicació iniciada des de la línia d’ordres s’atura quan tanques la sessió. PM2 la manté en marxa en segon pla, la reinicia després d’una fallada i la torna a iniciar en arrencar:

sudo npm install -g pm2

cd /srv/apps/ansibleforms/server
NODE_ENV=production pm2 start index.js --name ansibleforms
pm2 save
pm2 startup   # prints the command that starts PM2 at boot

Els playbooks s’executen en un RTE: inicia el mateix servidor una segona vegada amb AF_ROLE=rte, en un port propi. L’aplicació el truca i hi manté un WebSocket obert (RTE_MODE=inbound, consulta Modes), i executa els playbooks des de les mateixes carpetes (RTE_FILES=local). També llegeix persistent/.env, però no en fa servir cap paràmetre de la base de dades. Afegeix a persistent/.env el token que comparteixen l’aplicació i l’RTE, de com a mínim 16 caràcters, i el config seed que declara l’RTE:

RTE_TOKEN=<at least 16 characters>
CONFIG_SEED_PATH=/srv/apps/ansibleforms/server/persistent/seed.yaml

El config seed declara una credencial d’RTE amb l’adreça de l’RTE i el seu token, i el runner predeterminat rte que s’hi autentica:

version: 1
credentials:
  items:
    - name: rte
      credential_type: rte
      url: http://127.0.0.1:8010
      password: ${RTE_TOKEN}
runners:
  items:
    - name: rte
      type: rte
      rte_mode: inbound
      credential: rte
      is_default: true

Sense seed, afegeix-los a Connexions > Credencials (una credencial d’RTE amb aquesta adreça i el token) i a Connexions > Runners (tipus RTE, Mode Entrant). Després inicia l’RTE, només a 127.0.0.1:

cd /srv/apps/ansibleforms/server
AF_ROLE=rte RTE_MODE=inbound RTE_FILES=local PORT=8010 HTTPS=0 LISTEN_HOST=127.0.0.1 \
  NODE_ENV=production pm2 start index.js --name ansibleforms-rte
pm2 save

La configuració de l’RTE es descriu a la pàgina Executar un RTE. Comprova que PM2 llista tots dos processos:

pm2 status

Tots dos són online:

+----+------------------+------+---------+------+--------+----------+--------+-----+---------+------+----------+
| id | name             | mode | version | pid  | uptime | restarts | status | cpu | mem     | user | watching |
+----+------------------+------+---------+------+--------+----------+--------+-----+---------+------+----------+
| 0  | ansibleforms     | fork | 7.0.0   | 3104 | 8s     | 0        | online | 0%  | 120.1mb | root | disabled |
| 1  | ansibleforms-rte | fork | 7.0.0   | 3187 | 5s     | 0        | online | 0%  | 80.4mb  | root | disabled |
+----+------------------+------+---------+------+--------+----------+--------+-----+---------+------+----------+

Per treballar en el codi mateix, inicia-ho tot des de l’arrel del repositori amb recàrrega en directe: el servidor al port 3001, un RTE al port 8010 i el client a https://localhost:8443. En aquest mode, el servidor i l’RTE llegeixen server/.env.development:

cd /srv/apps/ansibleforms
npm install
(cd server && npm install && cp ../.env.example .env.development)
(cd client && npm install)
npm run dev

L’RTE (npm run dev:rte) necessita ansible-playbook al path, i s’afegeix ell mateix com a runner en mode database, obsolet, només per al desenvolupament; npm run dev:local inicia el client i el servidor sense ell. La guia de contribució descriu les proves i les comprovacions que cal executar.

Primera execució

Obre el servidor en un navegador (amb el .env d’exemple, https://your_ip:8443). Amb una base de dades buida, l’esquema es crea en el primer inici.

Les credencials d’administrador predeterminades són:

nom d’usuari : admin
contrasenya : AnsibleForms!123