From source

Build AnsibleForms from source and run it with Node.js

1. How the code is organized
2. Prerequisites
3. Get the code
4. Build
5. Configure
6. Run
7. First time run

---

How the code is organized

The repository holds two Node.js applications, and a build combines them into one:

• client : the web interface, written in Vue 3 and built into static files with Vite
• server : the API, written in Express. It runs the playbooks and AWX templates, connects to the database and serves the built client

Only the client is built; its output goes into the server’s views folder, as in the Docker image.

---

Prerequisites

Building and running from source requires solid Linux skills and some knowledge of Node.js. You install every component yourself:

• Node.js 24 or newer, with npm
• Git, to get the code
• MySQL 8+ or MariaDB, reachable from the server
• Ansible, if you run playbooks locally (ansible-playbook on the path); not required if you only launch AWX/AAP/Ascender templates

---

Get the code

Clone the repository into a folder of your choice, owned by the user that will run the application. The examples use /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

---

Build

Build in three steps, from the repository folder. First build the client:

cd client
npm ci
npm run build

Then install the server’s dependencies:

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

Finally copy the built client into the server’s views folder:

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

---

Configure

The server reads its settings from environment variables and, in production, also from server/persistent/.env, the file that the settings pages write to.

Start from the example file and set at least the MySQL connection (DB_HOST, DB_PORT, DB_USER, DB_PASSWORD):

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

All variables are described under Environment Variables. Everything else is stored in server/persistent by default: config.yaml, the forms folder and self-signed certificates are created there at the first start, alongside the logs. Put your playbooks in server/persistent/playbooks, or point ANSIBLE_PATH elsewhere.

---

Run

Run AnsibleForms in production, or in development mode to work on the code itself:

Start the server in production mode from the server folder:

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

An application started from the command line stops when you log off. PM2 keeps it running in the background, restarts it after a crash and starts it again at 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

Check that PM2 lists the application:

pm2 status

The application is online:

+----+--------------+------+---------+------+--------+----------+--------+-----+---------+------+----------+
| id | name         | mode | version | pid  | uptime | restarts | status | cpu | mem     | user | watching |
+----+--------------+------+---------+------+--------+----------+--------+-----+---------+------+----------+
| 0  | ansibleforms | fork | 7.2.0   | 3104 | 8s     | 0        | online | 0%  | 120.1mb | root | disabled |
+----+--------------+------+---------+------+--------+----------+--------+-----+---------+------+----------+

---

First time run

Open the server in a browser (with the example .env, https://your_ip:8443). On an empty database, the schema is created at the first start.

The default admin credentials are:

• username : admin
• password : AnsibleForms!123