Dai sorgenti

Compila AnsibleForms dai sorgenti ed eseguilo con Node.js

  1. Come è organizzato il codice
  2. Prerequisiti
  3. Ottieni il codice
  4. Compila
  5. Configura
  6. Esegui
  7. Primo avvio

Come è organizzato il codice

Il repository contiene due applicazioni Node.js, e una build le unisce in una sola:

  • client : l’interfaccia web, scritta in Vue 3 e compilata in file statici con Vite
  • server : l’API, scritta in Express. Passa i job ai runner, si connette al database e serve il client compilato. Avviato con AF_ROLE=rte, lo stesso server è l’RTE (ambiente di runtime) che esegue i playbook

Viene compilato solo il client; il suo output va nella cartella views del server, come nell’immagine Docker.

Prerequisiti

Compilare ed eseguire dai sorgenti richiede buone competenze Linux e qualche conoscenza di Node.js. Installi ogni componente tu stesso. Per eseguire AnsibleForms senza container e senza compilarlo, l’installazione nativa dell’installer fa tutto questo al posto tuo:

  • Node.js 26 (la versione in .nvmrc; almeno la 24), con npm
  • Git, per ottenere il codice e sincronizzare i repository
  • Client OpenSSH, per git via SSH, e sshpass, per i playbook che si connettono con una password SSH
  • Client MariaDB (mariadb, mariadb-dump), per backup e ripristini, anche con un server MySQL
  • MySQL 8+ o MariaDB, raggiungibile dal server
  • Ansible, per il processo RTE che esegue i playbook (ansible-playbook nel suo path). Il processo dell’app non ha bisogno né di Ansible né di Python, e con soli moduli template (AWX, AAP, Ascender e gli altri runner) non ti serve affatto un RTE

Installali per la tua distribuzione:

Node.js 26 arriva dal repository NodeSource, gli altri strumenti da Ubuntu stesso:

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

Controlla node --version (26) e ansible-playbook --version; per il database e il suo utente, vedi Installa MySQL.

Ottieni il codice

Clona il repository in una cartella a tua scelta, di proprietà dell’utente che eseguirà l’applicazione. Gli esempi usano /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

Compila

Compila in tre passi, dalla cartella del repository. Prima compila il client:

cd client
npm ci
npm run build

Poi installa le dipendenze del server:

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

Infine copia il client compilato nella cartella views del server:

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

Configura

Il server legge le sue impostazioni dalle variabili d’ambiente e, in produzione, anche da server/persistent/.env, il file in cui scrivono le pagine delle impostazioni.

Parti dal file di esempio nella radice del repository e imposta almeno la connessione MySQL (DB_HOST, DB_PORT, DB_USER, DB_PASSWORD):

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

Tutte le variabili sono descritte in Variabili d’ambiente. Tutto il resto viene salvato per impostazione predefinita in server/persistent: config.yaml, la cartella forms e i certificati autofirmati vengono creati lì al primo avvio, insieme ai log. Metti i tuoi playbook in server/persistent/playbooks, oppure fai puntare ANSIBLE_PATH altrove nell’ambiente dell’RTE, che la legge.

Esegui

Esegui AnsibleForms in produzione, o in modalità sviluppo per lavorare sul codice stesso:

Avvia il server in modalità produzione dalla cartella server:

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

Un’applicazione avviata dalla riga di comando si ferma quando ti disconnetti. PM2 la tiene in esecuzione in background, la riavvia dopo un crash e la avvia di nuovo al boot:

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

I playbook vengono eseguiti su un RTE: avvia lo stesso server una seconda volta con AF_ROLE=rte, su una porta tutta sua. L’app lo contatta e tiene aperto un WebSocket (RTE_MODE=inbound, vedi Modalità), ed esso esegue i playbook dalle stesse cartelle (RTE_FILES=local). Legge anche persistent/.env, ma non usa nessuna delle sue impostazioni del database. Aggiungi a persistent/.env il token che l’app e l’RTE condividono, di almeno 16 caratteri, e il config seed che dichiara l’RTE:

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

Il config seed dichiara una credenziale RTE con l’indirizzo dell’RTE e il suo token, e il runner predefinito rte che accede con essa:

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

Senza un seed, aggiungili in Connessioni > Credenziali (una credenziale RTE con quell’indirizzo e il token) e Connessioni > Runner (tipo RTE, Modalità In entrata). Poi avvia l’RTE, solo su 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

Le impostazioni dell’RTE sono descritte nella pagina Eseguire un RTE. Controlla che PM2 elenchi entrambi i processi:

pm2 status

Entrambi sono 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 |
+----+------------------+------+---------+------+--------+----------+--------+-----+---------+------+----------+

Primo avvio

Apri il server in un browser (con il .env di esempio, https://your_ip:8443). Su un database vuoto, lo schema viene creato al primo avvio.

Le credenziali di amministratore predefinite sono:

  • nome utente : admin
  • password : AnsibleForms!123