On-Premise And Cloud Deployments

Enterprise software procurement often involves a difficult choice: accept a vendor’s SaaS offering and lose control over where your data lives, or build everything yourself and lose years to infrastructure work. Form.io eliminates this tradeoff. The entire platform deploys into environments you control, whether that means AWS, Azure, Google Cloud, your private data center, or a laptop running Docker Desktop. You get the same drag-and-drop form builder, the same REST API generation, the same submission handling, and the same renderer libraries that the hosted service provides, but running on infrastructure where you set the rules.

This is not a “private cloud” option bolted onto a SaaS product. Form.io was architected from the beginning as deployable infrastructure. The Docker containers, the MongoDB requirement, the stateless API servers, the environment variable configuration system: every architectural decision supports self-hosted deployment as a first-class scenario. When compliance requirements, data sovereignty laws, or security policies prohibit sending form data to third-party servers, Form.io runs entirely within your boundary.

What Self-Hosted Deployment Includes

A complete Form.io deployment consists of several components that work together as a microservice architecture. You can run all of them on a single server or distribute them across multiple instances behind load balancers.

The Enterprise Server is the primary API server. It handles form definitions, submission storage, user authentication, project management, and all the business logic that makes forms work. This is the component that receives API calls from your applications and processes form submissions. It connects to MongoDB for persistence and communicates with other services for specialized functions.

The PDF Server converts form submissions into PDF documents and handles the rendering of PDF-based forms. If your workflows require generating PDFs from submissions or embedding fillable PDF forms within your applications, this server handles that processing. It runs as a separate container, allowing you to scale PDF generation independently from API traffic.

The Developer Portal provides the browser-based interface where users build forms, manage projects, configure permissions, and view submissions. This is the same portal available at portal.form.io, but running within your environment. You can enable or disable the portal on any deployment by setting the PORTAL_ENABLED environment variable.

The Renderer Libraries are the open-source JavaScript libraries (github.com/formio/formio.js) that render forms in browsers. These run client-side in your applications and communicate with your self-hosted API server. The renderers do not require separate deployment; they load from CDN or bundle into your application code.

Deployment Patterns and Topologies

Form.io supports multiple deployment topologies depending on your organization’s needs. The deployment documentation covers each pattern in detail.

Single Environment is the simplest configuration. One server runs the Enterprise Server with the Developer Portal enabled. This works for development, testing, or small-scale production deployments. All form building, API serving, and submission storage happen on a single instance.

Multi-Environment with Stages is the common enterprise pattern. You deploy three separate environments: Development, Test/Authoring, and Production. The Test environment runs the Developer Portal where form builders create and modify forms. Forms promote through Stages to reach Production, where the portal is disabled and only the API serves requests. This separation prevents accidental changes to production forms while maintaining a clear deployment pipeline.

High-Availability Production scales the architecture horizontally. Multiple API server instances run behind a load balancer, all connecting to the same MongoDB cluster. Because the servers are stateless, you can spin up additional instances during peak load and scale down when traffic subsides. The deployment configurations documentation provides sizing recommendations based on concurrent user counts.

Docker Container Deployment

Form.io distributes all server components as Docker images through Docker Hub. The Enterprise Server lives at formio/formio-enterprise, and the PDF Server has its own image. This container-based approach means deployment works anywhere Docker runs.

A minimal deployment using Docker Compose looks like this:

version: '3'
services:
  mongo:
    image: mongo
    volumes:
      - ./data/db:/data/db
  formio:
    image: formio/formio-enterprise
    environment:
      - LICENSE_KEY=your-license-key
      - MONGO=mongodb://mongo:27017/formio
      - PORTAL_ENABLED=true
      - ADMIN_EMAIL=admin@example.com
      - ADMIN_PASS=changeme
    ports:
      - "3000:3000"
    depends_on:
      - mongo

Kubernetes and Orchestration

For organizations running Kubernetes clusters, Form.io deploys as standard Kubernetes resources. The Kubernetes deployment guide walks through creating Deployments, Services, and Ingress resources for both the API and PDF servers.

A typical Kubernetes deployment creates separate Deployment resources for the API and PDF servers, each managed by corresponding Services. An Ingress Controller routes external traffic to the appropriate service based on hostname or path. Environment variables pass through ConfigMaps or Secrets, with sensitive values like database credentials and license keys stored securely.

Helm chart support enables templated deployments that adapt to different environments. While Form.io does not publish an official Helm chart, the deployment patterns follow Kubernetes conventions that integrate with existing chart structures. Organizations with established Helm workflows can create charts using the documented container images and environment variables.

Environment Variable Configuration

All Form.io server configuration happens through environment variables. This design supports twelve-factor app principles and integrates naturally with container orchestration, secrets management systems, and CI/CD pipelines.

Required variables for any deployment include LICENSE_KEY (obtained from Form.io), MONGO (the MongoDB connection string), and authentication secrets like JWT_SECRET and DB_SECRET. Optional variables control features like portal enablement, PDF server connectivity, file storage configuration, and SSL/TLS settings.

The complete variable reference lives in the Enterprise Server documentation. Key configuration categories include database connection settings, authentication provider integration, file storage backends (S3, Azure Blob, local filesystem), email transport configuration, and performance tuning options.

For sensitive values, Form.io supports Docker Secrets. Set DOCKER_SECRETS=1 in your environment, and the server reads configuration from files in /run/secrets/ rather than environment variables. This pattern keeps credentials out of container inspection commands and integrates with orchestration platforms that provide secrets injection.

Database Requirements and Options

Form.io requires MongoDB or a MongoDB-compatible database. This is a hard requirement, not a preference. The platform stores form schemas, submissions, users, and all project data as JSON documents. The document model maps directly to how forms work: nested structures, arrays, dynamic fields, and schema-less flexibility.

For self-hosted deployments, you have several options. MongoDB Community Edition runs locally or in containers. The deployment scripts include configurations for running MongoDB alongside the Form.io servers. MongoDB Atlas provides a managed database service that works with self-hosted Form.io API servers. Your forms platform runs in your environment while the database runs as a managed service. Azure Cosmos DB with MongoDB API compatibility works for Azure deployments. Amazon DocumentDB provides similar MongoDB compatibility for AWS environments.

The database connection string goes in the MONGO environment variable. Include the database name explicitly (default is formio) because cloud providers often omit it from their generated connection strings. Omitting the database name causes the server to use MongoDB’s default test database, which creates confusion when data appears to vanish.

File Storage Configuration

Form submissions often include file uploads. Self-hosted deployments need a configured file storage backend to handle these uploads. Form.io supports Amazon S3, Azure Blob Storage, and local filesystem storage.

For cloud deployments, S3 or Azure Blob integrates through environment variables specifying the bucket/container name, region, and credentials. The file storage documentation covers the specific variables for each provider (read more about File Uploads).

For fully air-gapped or on-premise deployments where cloud storage is not available, SeaweedFS provides an open-source S3-compatible file storage system. The local deployment guide includes SeaweedFS configuration that runs alongside the Form.io containers. This gives you S3-compatible storage without any cloud dependencies.

Compliance and Data Sovereignty

Self-hosted deployment is often driven by compliance requirements. When regulations specify where data must reside, who can access it, and what controls must surround it, running the platform yourself provides the control necessary to meet those requirements.

HIPAA compliance for healthcare data requires knowing exactly where protected health information lives and controlling access to it. A self-hosted Form.io deployment stores all submission data in your MongoDB instance, within your security boundary, subject to your access controls. Form.io does not access your data because there is no connection back to Form.io servers (except for license validation, which transmits only the license key, not form data).

FedRAMP requirements for federal government systems demand specific security controls and often require deployment within government cloud regions like AWS GovCloud. Self-hosted Form.io deploys into any environment that runs Docker, including government-restricted cloud regions.

GDPR and data residency requirements specify that personal data must remain within certain geographic boundaries. Self-hosted deployment lets you choose exactly where your infrastructure runs. European data stays in European data centers. You control the geography.

Data sovereignty concerns extend beyond specific regulations. Some organizations simply cannot send customer data to third-party servers for business, contractual, or policy reasons. Self-hosted Form.io keeps all data within infrastructure you own or control.

The key point: Form.io provides the platform, but compliance responsibility remains with you. Self-hosted deployment enables compliance; it does not automatically provide it. You still need proper access controls, encryption, audit logging, network security, and all the other controls your compliance framework requires. Form.io gives you the platform that operates within your compliant infrastructure.

License Management

Self-hosted deployments require a valid license key. The license determines which features are available, how many environments you can run, how many projects you can create, and other utilization limits.

Licenses are managed through the Form.io portal at portal.form.io. License managers can view utilization, enable and disable environments, and monitor which servers are actively using the license. The server validates the license on startup by contacting the Form.io license server. If your network restricts outbound connections, ensure the license server is reachable or work with Form.io support on alternative validation methods.

A typical enterprise license allows multiple environments. The recommended pattern uses three environments (Development, Test, Production) mapped to separate license utilizations. You can reassign utilizations between servers as your infrastructure changes.

Upgrading and Maintenance

Self-hosted deployments require you to manage upgrades. Form.io releases new versions regularly, and applying those updates is your responsibility.

The upgrade process involves pulling new Docker images, stopping current containers, and starting new containers with the same environment variables. The maintenance and migration documentation provides step-by-step commands.

Before any upgrade, back up your MongoDB database. The platform stores all state in MongoDB, so a good backup lets you roll back if problems occur. Use mongodump for full backups that preserve indexes, or mongoexport for portable JSON exports.

Version pinning matters. Tag your deployments with specific version numbers rather than using latest. This ensures reproducible deployments and prevents unexpected changes when containers restart.

What Self-Hosted Deployment Cannot Do

Understanding the limitations helps set appropriate expectations.

No automatic updates. You apply updates when you choose to, which means you also bear responsibility for staying current with security patches and bug fixes. Form.io publishes release notes, but you manage the upgrade schedule.

No managed infrastructure. Server monitoring, database administration, backup verification, capacity planning, and incident response are your responsibility. Form.io provides the software; you provide the operations.

License validation requires network access. The server must reach the Form.io license server on startup. Fully air-gapped deployments need special arrangements with Form.io support.

Support scope differs. Self-hosted deployments receive support for the Form.io software itself, but infrastructure issues (network configuration, database performance, container orchestration problems) fall outside Form.io support scope.

When to Choose Self-Hosted Deployment

Self-hosted deployment makes sense when compliance requirements prohibit third-party data storage, when data sovereignty laws require geographic control, when security policies mandate infrastructure ownership, when air-gapped or disconnected environments need form capabilities, or when cost structures favor infrastructure investment over subscription fees.

If these constraints do not apply, the hosted service at portal.form.io provides the same capabilities without operational overhead.

Related Resources