How it works

The parts of an installation, what happens at a launch, and where data is kept

  1. Architecture
    1. Built with
  2. What happens when you launch a form
  3. Where things are stored

Architecture

AnsibleForms is one Node.js server that serves the web application and a REST API, backed by a MySQL database. It reads forms from YAML files, and runs each job either as a local ansible-playbook process or as a template on AWX, AAP or Ascender:

AnsibleForms architecture The browser and an optional MCP client talk to the AnsibleForms server. The server stores its data in MySQL and in the persistent folder, runs ansible-playbook locally, and connects to AWX, AAP or Ascender, data sources, secret stores, git repositories, login providers, a mail server and an optional model provider. Browser forms, designer, jobs, chat MCP client optional AnsibleForms server Node.js / Express, one instance Web app and REST API Form engine, expressions Job runner, scheduler ansible-playbook runs locally, in the container MCP server (optional) Persistent folder config.yaml, forms, playbooks MySQL / MariaDB jobs, users, credentials AWX / AAP / Ascender templates, over their API Data sources databases, REST APIs, files Secret stores HashiCorp Vault, CyberArk Git repositories forms, playbooks, config Login providers LDAP, Entra ID, OIDC Mail server notifications, approvals Model provider optional, chat assistant

The components in the diagram each have a role of their own:

Component Role
Browser The Vue web application: the forms, the Designer, the job history and the settings
AnsibleForms server Evaluates the forms, launches and tracks the jobs, runs the schedules and serves the REST API
ansible-playbook Runs playbooks from the playbooks folder; the container image includes Ansible
MySQL / MariaDB Holds the jobs and their output, the users, the credentials and the connections
Persistent folder Holds config.yaml, the form files, the playbooks, the logs and the backups
AWX / AAP / Ascender Runs the job templates and workflow templates of AWX forms
Data sources Fill the fields: database queries, REST APIs, files and other functions
Secret stores Supply the user and password of a credential at use time, see Secret stores
Git repositories Keep the forms, the playbooks and config.yaml under version control
MCP client, chat Optional, both off by default: the MCP server and the chat assistant

AnsibleForms runs as a single instance: see the FAQ for the reasons.

Built with

The server and the web interface are built on these components:

Part Technology
Server Node.js and Express
Database MySQL or MariaDB
Web interface Vue 3, with Bootstrap 5 and Font Awesome

What happens when you launch a form

A launch goes through the same steps whether it comes from the browser or from the REST API:

  1. Load : the server sends only the forms the user’s roles allow, and evaluates server expressions
  2. Submit : the browser turns the field values into extravars and posts them to POST /api/v2/job
  3. Check : the server reloads the form for the user’s roles and, with launch validation on, checks the values
  4. Record : the job is stored with status running, and its id is added to the extravars as __jobid__
  5. Credentials : the form’s credentials are read from the database or a secret store
  6. Approve : a form with an approval point waits until an approver accepts the job
  7. Run : ansible-playbook runs locally, or the AWX/AAP/Ascender template is launched; multistep forms run each step
  8. Follow : the output is saved as it arrives, and the browser polls the job every two seconds to show it live
  9. End : the job gets its final status, and a mail goes out when the form’s notifications ask for it

Where things are stored

AnsibleForms keeps its state in two places: the MySQL database and the persistent folder. Back up both.

In the database

The database, AnsibleForms, is created at the first start (unless ALLOW_SCHEMA_CREATION is 0) and holds:

  • the jobs, their extravars and their output, the schedules and the stored jobs
  • the local users, the groups and the API tokens
  • the credentials, encrypted with ENCRYPTION_SECRET, and the secret store connections
  • the AWX, LDAP, OAuth2, repository, mail and chat assistant settings
  • the audit log

In the persistent folder

It is /app/dist/persistent in the image and server/persistent from source; each path has its own variable:

Default path Variable Contents
config.yaml CONFIG_PATH The categories, the roles and the constants
forms/ FORMS_FOLDER_PATH The form files, .yaml or .yml, in subfolders if you like
playbooks/ ANSIBLE_PATH The playbooks of ansible forms, and their working directory
repositories/ REPO_PATH The clones of the git repositories
forms_backups/ FORMS_BACKUP_PATH The copies the Designer makes before it saves
backups/ BACKUP_PATH The database backups
uploads/ UPLOAD_PATH The files uploaded through file fields
logs/ LOG_PATH ansibleforms.log and ansibleforms.errors.log
certificates/ HTTPS_CERT, HTTPS_KEY The certificate and key, when HTTPS is 1
.env   The environment variables saved from the settings pages (unless ALLOW_ENV_EDIT is 0)

The generated SSH key lives in HOME_PATH, outside the persistent folder by default.