Deploying Form.io

Introduction

Form.io is a powerful, open-source form builder and data management platform that enables developers and organizations to create sophisticated web forms without writing extensive code. Built on a modern JavaScript stack, Form.io provides a drag-and-drop form builder, form rendering engine, and a complete API for form submissions and data management.

The platform separates form creation from form rendering, allowing you to build forms once and embed them anywhere. Form.io is particularly popular for enterprise applications, government forms, healthcare intake systems, and any scenario requiring complex, dynamic forms with conditional logic, validation, and workflow automation.

Key highlights of Form.io:

• Drag-and-Drop Form Builder: Create complex forms visually without coding
• Dynamic Forms: Build forms with conditional fields, calculated values, and real-time validation
• JSON-Powered: Forms are stored as JSON, making them versionable and portable
• Embeddable Renderer: Embed forms in any web application with the JavaScript renderer
• Submission Management: Store, query, and export form submissions
• Role-Based Access Control: Fine-grained permissions for forms and submissions
• Webhooks and Actions: Trigger external systems when forms are submitted
• PDF Generation: Generate PDF documents from form submissions
• File Uploads: Handle file attachments with configurable storage backends
• API-First Design: Full REST API for all operations
• 100% Open Source: Community edition available under OSL-3.0

This guide walks through deploying Form.io on Klutch.sh using Docker, configuring the form builder and API server, and integrating forms into your applications.

Why Deploy Form.io on Klutch.sh

Deploying Form.io on Klutch.sh provides several advantages for your form management needs:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Form.io without complex orchestration. Push to GitHub, and your form platform deploys automatically.

Persistent Storage: Attach persistent volumes for your form definitions and submission data. Your forms and data survive container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure form submissions from anywhere.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates to your Dockerfile trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on your form traffic and submission volume. Scale up for high-traffic applications.

Environment Variable Management: Securely store sensitive configuration like database credentials and API keys through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain to your Form.io instance for branded form URLs.

Always-On Availability: Your form platform remains accessible 24/7 for users to submit forms at any time.

Prerequisites

Before deploying Form.io on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your Form.io configuration
• Basic familiarity with Docker and containerization concepts
• Understanding of MongoDB (Form.io’s database backend)
• (Optional) A custom domain for your Form.io instance

Understanding Form.io Architecture

Form.io consists of several components working together:

API Server: The Node.js backend that handles form definitions, submissions, authentication, and all REST API operations. This is the core of Form.io.

Form Builder: A React-based drag-and-drop interface for creating and editing forms. The builder generates JSON form definitions.

Form Renderer: A JavaScript library (formio.js) that renders forms in web applications based on JSON definitions. Can be embedded in any web application.

MongoDB Database: Stores form definitions, submissions, users, roles, and all platform data. Form.io requires MongoDB for persistence.

File Storage: Handles file uploads from forms. Supports local filesystem, S3, Azure Blob Storage, and other backends.

Preparing Your Repository

To deploy Form.io on Klutch.sh, create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

formio-deploy/
├── Dockerfile
├── config/
│   └── default.json
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM formio/formio:latest

# Set environment variables
ENV NODE_ENV=production
ENV PORT=3001
ENV MONGO=${MONGO_URI}
ENV JWT_SECRET=${JWT_SECRET}

# Expose the API port
EXPOSE 3001

# The base image includes the default entrypoint

Advanced Dockerfile with Custom Configuration

For more control over your deployment:

FROM formio/formio:latest

# Set production environment
ENV NODE_ENV=production
ENV PORT=3001

# MongoDB connection
ENV MONGO=${MONGO_URI}

# Security settings
ENV JWT_SECRET=${JWT_SECRET}
ENV JWT_EXPIRE_TIME=${JWT_EXPIRE_TIME:-240}

# Admin credentials
ENV ADMIN_EMAIL=${ADMIN_EMAIL}
ENV ADMIN_PASS=${ADMIN_PASS}

# Optional: Configure file storage
ENV FORMIO_S3_BUCKET=${FORMIO_S3_BUCKET}
ENV FORMIO_S3_REGION=${FORMIO_S3_REGION}
ENV FORMIO_S3_KEY=${FORMIO_S3_KEY}
ENV FORMIO_S3_SECRET=${FORMIO_S3_SECRET}

# Optional: Email configuration
ENV FORMIO_EMAIL_TYPE=${FORMIO_EMAIL_TYPE}
ENV FORMIO_EMAIL_USER=${FORMIO_EMAIL_USER}
ENV FORMIO_EMAIL_PASS=${FORMIO_EMAIL_PASS}

# Create directories for uploads
RUN mkdir -p /app/uploads

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3001/health || exit 1

EXPOSE 3001

# The base image includes the default entrypoint

Creating the Configuration File

Create a config/default.json file for additional settings:

{
  "port": 3001,
  "mongo": "${MONGO_URI}",
  "jwt": {
    "secret": "${JWT_SECRET}",
    "expireTime": 240
  },
  "admin": {
    "email": "${ADMIN_EMAIL}",
    "password": "${ADMIN_PASS}"
  },
  "cors": {
    "origin": "*",
    "methods": ["GET", "PUT", "POST", "DELETE", "OPTIONS"],
    "allowedHeaders": ["Content-Type", "x-jwt-token", "x-token"]
  }
}

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
README.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local
node_modules/
.npm

Environment Variables Reference

Variable	Required	Default	Description
MONGO or MONGO_URI	Yes	-	MongoDB connection string
JWT_SECRET	Yes	-	Secret key for JWT token signing
JWT_EXPIRE_TIME	No	240	JWT token expiration in minutes
ADMIN_EMAIL	Yes	-	Initial admin account email
ADMIN_PASS	Yes	-	Initial admin account password
PORT	No	3001	Server port
FORMIO_S3_BUCKET	No	-	S3 bucket for file uploads
FORMIO_S3_REGION	No	-	S3 region
FORMIO_S3_KEY	No	-	S3 access key
FORMIO_S3_SECRET	No	-	S3 secret key

Deploying Form.io on Klutch.sh

Once your repository is prepared, follow these steps to deploy Form.io:

Generate Your JWT Secret

Before deployment, generate a secure JWT secret:

openssl rand -base64 32

Save this secret securely for the environment variables configuration.

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile config/ .dockerignore README.md
git commit -m "Initial Form.io deployment configuration"
git remote add origin https://github.com/yourusername/formio-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “formio” or “forms”.

Create a MongoDB Database

Before creating the Form.io app, set up a MongoDB database:

1. Within your project, create a new MongoDB database service
2. Note the connection string provided by Klutch.sh
3. This will be used for the MONGO environment variable

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Form.io Dockerfile.

Configure HTTP Traffic

Form.io serves its API and UI over HTTP. In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 3001 (Form.io’s default port)

Set Environment Variables

In the environment variables section, add the following:

Variable	Value
MONGO	MongoDB connection string from step 4
JWT_SECRET	Your generated secret from step 1
ADMIN_EMAIL	admin@yourdomain.com
ADMIN_PASS	A strong admin password
JWT_EXPIRE_TIME	240 (or your preferred duration)

Attach Persistent Volumes

For file upload support, add the following volumes:

Mount Path	Recommended Size	Purpose
/app/uploads	10 GB	Uploaded files from forms

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the Form.io container
• Provision an HTTPS certificate

Access Form.io

Once deployment completes, access your Form.io instance at https://your-app-name.klutch.sh. Log in with your admin credentials to begin creating forms.

Initial Setup and Configuration

First-Time Login

When you first access your Form.io instance:

1. Navigate to https://your-app-name.klutch.sh
2. Log in with the admin email and password you configured
3. You’ll see the Form.io dashboard with options to create projects

Creating Your First Project

Form.io organizes forms into projects:

1. Click “Create Project” in the dashboard
2. Enter a project name and title
3. Select a project template or start from scratch
4. Configure project settings

Understanding the Dashboard

The Form.io dashboard includes:

Section	Description
Forms	View and manage form definitions
Data	Browse and export form submissions
Access	Configure roles and permissions
Actions	Set up webhooks and integrations
Settings	Project configuration

Building Forms

Using the Form Builder

Create forms with the drag-and-drop builder:

1. Navigate to Forms > Create Form
2. Drag components from the left panel onto the form canvas
3. Click components to configure their properties
4. Use the Preview tab to test your form
5. Save the form when complete

Available Components

Form.io provides a rich set of form components:

Category	Components
Basic	Text Field, Text Area, Number, Password, Checkbox, Select, Radio
Advanced	Email, URL, Phone, Date/Time, Currency, Signature, File Upload
Layout	Columns, Panel, Table, Tabs, Fieldset, Well
Data	Hidden, Container, Data Map, Data Grid, Edit Grid
Premium	Nested Form, Resource, Custom Component

Conditional Logic

Make forms dynamic with conditional fields:

1. Select a component and click the gear icon
2. Go to the Conditional tab
3. Set conditions based on other field values
4. The component will show/hide based on conditions

Example condition: Show “Spouse Name” field only when “Marital Status” equals “Married”.

Validation Rules

Configure field validation:

Validation	Description
Required	Field must have a value
Minimum/Maximum Length	Text length constraints
Minimum/Maximum Value	Numeric range constraints
Pattern	Regular expression validation
Custom	JavaScript validation logic

Form Rendering

Embedding Forms in Web Applications

Embed Form.io forms in your application using the JavaScript renderer:

<link rel="stylesheet" href="https://cdn.form.io/formiojs/formio.full.min.css">
<script src="https://cdn.form.io/formiojs/formio.full.min.js"></script>

<div id="formio"></div>

<script>
  Formio.createForm(document.getElementById('formio'),
    'https://your-formio-instance.klutch.sh/project/form'
  ).then(function(form) {
    form.on('submit', function(submission) {
      console.log('Submission:', submission);
    });
  });
</script>

React Integration

Use Form.io with React applications:

import { Form } from '@formio/react';

function MyFormComponent() {
  return (
    <Form
      src="https://your-formio-instance.klutch.sh/project/form"
      onSubmit={(submission) => console.log(submission)}
    />
  );
}

Angular Integration

Use Form.io with Angular applications:

import { FormioModule } from '@formio/angular';

@NgModule({
  imports: [FormioModule]
})
export class AppModule { }

Submission Management

Viewing Submissions

Access form submissions through the dashboard:

1. Navigate to your form
2. Click the Data tab
3. Browse submissions in table view
4. Click individual submissions for details

Exporting Data

Export submissions in multiple formats:

Format	Use Case
JSON	API integration, backups
CSV	Spreadsheet analysis
PDF	Document generation

Querying Submissions

Use the API to query submissions:

GET /project/form/submission?data.status=pending&limit=50

Supported query operators:

Operator	Example	Description
equals	data.status=active	Exact match
regex	data.name__regex=/john/i	Pattern match
exists	data.email__exists=true	Field exists
gt, lt	data.age__gt=18	Comparison

Access Control

Roles and Permissions

Configure role-based access:

Role	Default Permissions
Administrator	Full access to all resources
Authenticated	Create and read own submissions
Anonymous	Submit forms only

Creating Custom Roles

Define roles for your use case:

1. Go to Access > Roles
2. Create a new role
3. Assign permissions to forms and resources
4. Assign users to roles

Field-Level Permissions

Control access to individual form fields:

1. Edit a form component
2. Go to the API tab
3. Configure view and edit permissions
4. Restrict sensitive fields to specific roles

Actions and Webhooks

Built-in Actions

Form.io supports various submission actions:

Action	Description
Email	Send email notifications
Webhook	Call external API endpoints
SQL	Insert data into SQL databases
OAuth	Authenticate with OAuth providers
Role Assignment	Assign roles based on submission

Configuring Webhooks

Set up webhooks for form submissions:

1. Navigate to your form’s Actions tab
2. Add a Webhook action
3. Enter the target URL
4. Configure request method and headers
5. Map submission data to the request body

Email Notifications

Configure email actions:

1. Add an Email action to your form
2. Set up SMTP or email service credentials
3. Configure recipients (static or from form fields)
4. Design the email template

PDF Generation

Enabling PDF Support

Generate PDFs from form submissions:

1. Enable PDF generation in your form settings
2. Design the PDF template
3. Configure page layout and styles
4. Access PDF downloads from submission data

Custom PDF Templates

Create branded PDF output:

1. Upload custom fonts and logos
2. Design template with placeholders for form data
3. Configure headers, footers, and page breaks

Production Best Practices

Security Recommendations

• Strong JWT Secret: Use a cryptographically secure random string
• HTTPS Only: All form traffic should use HTTPS (automatic with Klutch.sh)
• Admin Credentials: Use strong, unique admin passwords
• API Security: Implement proper authentication for API access
• CORS Configuration: Restrict origins in production

Performance Optimization

• MongoDB Indexes: Create indexes for frequently queried fields
• Caching: Implement caching for frequently accessed forms
• Resource Sizing: Allocate sufficient memory for complex forms
• Connection Pooling: Configure MongoDB connection pools

Backup Strategy

Protect your form data:

1. MongoDB Backups: Regular database backups
2. Form Export: Export form definitions as JSON
3. Submission Export: Periodic exports of submission data
4. File Backups: Back up uploaded files

Monitoring and Logging

Accessing Logs

View application logs through:

1. Klutch.sh Dashboard: View runtime logs
2. API Logs: Monitor API request logs
3. Submission Logs: Track form submission activity

Health Monitoring

Monitor your Form.io instance:

1. Check the /health endpoint for API status
2. Monitor MongoDB connection status
3. Track submission success rates
4. Alert on error spikes

Troubleshooting Common Issues

Connection to MongoDB Failed

Symptoms: Application fails to start with database errors.

Solutions:

• Verify MONGO connection string is correct
• Ensure MongoDB service is running
• Check network connectivity between services
• Verify MongoDB user permissions

Form Builder Not Loading

Symptoms: Dashboard loads but form builder is blank.

Solutions:

• Clear browser cache
• Check browser console for JavaScript errors
• Verify all Form.io assets are loading
• Check CORS configuration

Submissions Not Saving

Symptoms: Forms submit but data doesn’t appear.

Solutions:

• Check MongoDB connection
• Verify form permissions
• Review submission validation errors
• Check API logs for errors

File Uploads Failing

Symptoms: File upload components don’t work.

Solutions:

• Verify upload directory exists and is writable
• Check file size limits
• Verify S3 credentials if using S3 storage
• Check available disk space

Updating Form.io

To update to a newer version:

1. Backup Data: Export forms and backup MongoDB
2. Update Dockerfile: Change the image tag
3. Push Changes: Commit and push to trigger redeployment
4. Run Migrations: Apply any database migrations
5. Verify: Test form creation and submission

Additional Resources

• Form.io Official Website
• Form.io Documentation
• Form.io Server GitHub
• Form.io Renderer GitHub
• Form.io Examples
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Form.io on Klutch.sh gives you a powerful, self-hosted form builder and data management platform with automatic builds, persistent storage, and secure HTTPS access. The combination of Form.io’s feature-rich form capabilities and Klutch.sh’s deployment simplicity means you can focus on creating forms rather than managing infrastructure.

With support for complex conditional logic, extensive validation, role-based access control, and seamless integration with web applications, Form.io on Klutch.sh provides an enterprise-grade form solution. Whether you’re building simple contact forms or complex multi-step workflows, Form.io delivers the tools you need with complete control over your data.