Platform Architecture
A simple overview of the Form.io Platform architecture
Form.io is a fully containerized platform. Everything runs as Docker containers that can be deployed on-premise, in the cloud, or even locally to a single machine. At the core, an environment is a handful of services connected over a Docker network, each handling a distinct responsibility.
The Enterprise Container
The Enterprise API server (formio/formio-enterprise, port 3000) is the heart of the platform. It serves the REST APIs for creating and managing forms, manages the storage and retrieval of submissions, and handles user authentication.
When enabled, it hosts the Developer Portal, a web-based UI where form builders visually design forms, manage projects, configure roles, and promote forms across stages. Whether the portal is enabled or not is controlled by an environment variable configured at deployment. Production instances often run without the portal, keeping it as a pure API endpoint for applications.
The PDF Container
The PDF server (formio/pdf-server, port 4005) is a separate container dedicated to rendering PDFs. It handles uploading existing PDF documents and overlaying Form.io web forms on top of them, as well as generating PDF exports of form submissions. It uses a headless browser (Puppeteer) internally to render forms into PDF format. Both the API server and the PDF server connect to the same database where data is ultimately stored.
DB Layer
MongoDB is the database layer. All form definitions (stored as JSON), submissions, user accounts, project configurations, and the Portal Base project data live here.
In production deployments, this is typically a managed MongoDB service (MongoDB Atlas, Azure Cosmos DB, AWS DocumentDB), but for local development it can run as a simple Docker container with a mounted volume.
Additional External Services
Storage
S3-compatible file storage handles binary files, like file uploads from form users, or stored PDF documents. Form.io supports a variety of storage options:
AWS S3, directly
Azure Blob Storage
Self-hosted S3-compatible servers, like SeaweedFS or MinIO.
The PDF server in particular relies on this for storing generated PDF files.
NGINX
NGINX (or another reverse proxy) sits in front of the API and PDF containers, routing all incoming HTTP/HTTPS traffic to the correct service. Requests to the root path go to the API server, requests to /pdf/ are rewritten and forwarded to the PDF server, and file storage traffic can be routed to the desired storage service or domain. This lets the entire environment sit behind a single URL.
What lives on the client side
The Form Renderer is a JavaScript SDK (available for vanilla JS, Angular, and React) that is embedded directly into an application. It takes the JSON form definition from the API and transforms it into a fully interactive, validated form in the browser.
All rendering, validation logic, and conditional behavior run client-side. The renderer talks back to the API server only to fetch form definitions and submit completed data.
Multi-environment deployments
A typical enterprise setup uses a 3-environment license: Development, Test/Authoring, and Production. The Test environment is where the Developer Portal lives, providing a stable place for form builders to work.
Stages within a project let teams promote forms from one environment to the next. Each environment has an independent API server, PDF server, and database, all connected through the portal UI using remote connections secured by a shared portal secret.
This architecture means form builders work in the portal, developers embed the renderer in their apps, and the Enterprise and PDF servers handle everything in between. This effectively separates Form.io platform development, form building, and application development, preventing issues in one from bottlenecking another.
Last updated
Was this helpful?