Skip to content
Klutch.sh Docs

Deploying FlowFuse

Introduction

FlowFuse is an enterprise-grade platform built on Node-RED that transforms how industrial teams develop, deploy, and manage automation applications at scale. As the industrial application platform for the modern era, FlowFuse extends Node-RED’s intuitive flow-based programming with AI-assisted development, collaborative team features, remote device management, and enterprise security—making it the go-to solution for bridging IT and OT systems in manufacturing, energy, logistics, and industrial operations.

With FlowFuse, you can connect any machine using any industrial protocol (Modbus, OPC-UA, MQTT, and hundreds more), transform raw data into structured information models, build interactive dashboards, and deploy applications to edge devices—all while maintaining governance, version control, and centralized management. The platform’s AI-powered FlowFuse Expert copilot accelerates development by generating Node-RED flows, data transformations, and dashboard components from natural language descriptions, turning weeks of development time into hours.

Deploying FlowFuse on Klutch.sh provides infrastructure-as-code simplicity with production-ready features: automated SSL/TLS termination, persistent storage for application data, environment-based configuration management, and seamless integration with PostgreSQL databases. This guide walks you through containerizing FlowFuse with Docker, configuring database backends, setting up email notifications, deploying to Klutch.sh, and implementing production best practices for industrial-scale Node-RED deployments.

Why Deploy FlowFuse on Klutch.sh

Running FlowFuse on Klutch.sh delivers several advantages for industrial teams:

  • Simplified Infrastructure: No Kubernetes complexity—deploy containerized FlowFuse with automatic service discovery and load balancing
  • Managed Database Integration: Connect to PostgreSQL databases with built-in connection pooling and backup strategies
  • Persistent Storage: Attach volumes for Node-RED flows, credentials, project data, and file storage with configurable sizing
  • Zero-Trust Security: Environment-based secrets management keeps credentials, API keys, and database passwords out of code
  • Custom Domain Support: Map your industrial domains (flows.yourcompany.com) with automatic SSL certificate provisioning
  • Cost-Effective Scaling: Pay for compute and storage you use without per-seat licensing from SaaS alternatives
  • GitOps Compatibility: Deploy from GitHub with automatic rebuilds on push for true infrastructure-as-code workflows
  • Production Monitoring: Built-in health checks, logging, and metrics collection for operational visibility

Prerequisites

Before deploying FlowFuse on Klutch.sh, ensure you have:

  • A Klutch.sh account (sign up here)
  • A GitHub repository for your FlowFuse deployment configuration
  • Access to the Klutch.sh dashboard
  • Basic understanding of Docker, Node-RED, and database concepts
  • A PostgreSQL database instance (see PostgreSQL deployment guide)
  • (Optional) SMTP server credentials for email notifications and team invitations
  • (Optional) Domain name for custom branding and access

Understanding FlowFuse Architecture

FlowFuse consists of several interconnected components that work together to provide comprehensive Node-RED management:

Core Components

  • FlowFuse Application: Main web application serving the management UI, API endpoints, and orchestration logic
  • PostgreSQL Database: Stores user accounts, teams, projects, instance configurations, audit logs, and metadata
  • Node-RED Instances: Isolated Node-RED containers managed by FlowFuse, one per project/application
  • File Storage Service: Provides persistent file system access for Node-RED instances to store data files
  • MQTT Broker (optional): Team-level message broker for inter-instance communication
  • Device Agent (optional): Remote agent software for managing Node-RED on edge devices

Architecture Flow

  1. Users access FlowFuse web UI to create teams and projects
  2. FlowFuse provisions isolated Node-RED instances in containers
  3. Each instance connects to shared PostgreSQL for context storage
  4. File Storage Service provides /data directory access to instances
  5. Instances communicate via Team Broker (MQTT) when configured
  6. Device Agents connect remote installations to central management
  7. All configuration, snapshots, and audit trails stored in PostgreSQL

When deployed on Klutch.sh, FlowFuse automatically detects your Dockerfile and builds a container image. The platform manages HTTP traffic routing to port 3000 (FlowFuse’s default port), provides SSL termination, and offers persistent volume options for file storage data.

Project Structure

A minimal repository structure for deploying FlowFuse on Klutch.sh:

flowfuse-deployment/
├── Dockerfile
├── .dockerignore
├── .gitignore
├── README.md
└── config/
    └── flowfuse.yml.template

Important: Keep secrets and credentials out of Git. All sensitive configuration should be injected via environment variables in Klutch.sh.

Creating Your Dockerfile

Klutch.sh automatically detects a Dockerfile in the root directory of your repository. Create a Dockerfile that uses the official FlowFuse image:

Option 1: Simple Dockerfile (Quick Start)

FROM flowfuse/forge:latest


# Expose FlowFuse web application port
EXPOSE 3000


# FlowFuse runs as non-root user by default
CMD ["npm", "start"]

Option 2: Production Dockerfile with Custom Configuration

FROM flowfuse/forge:2.25


WORKDIR /usr/src/forge


# Copy custom configuration template (secrets via env vars)
COPY config/flowfuse.yml.template /usr/src/forge/etc/


# Install additional dependencies if needed
USER root
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
        postgresql-client \
        curl \
    && rm -rf /var/lib/apt/lists/*


# Switch back to forge user for security
USER forge


# Expose HTTP port
EXPOSE 3000


# Health check for monitoring
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl --fail http://localhost:3000/api/v1/ping || exit 1


# Start FlowFuse application
CMD ["npm", "start"]

Option 3: Advanced Dockerfile with File Storage

FROM flowfuse/forge:2.25


WORKDIR /usr/src/forge


# Create directories for persistent data
USER root
RUN mkdir -p /opt/flowfuse/var/files /opt/flowfuse/var/context && \
    chown -R forge:forge /opt/flowfuse


# Copy configuration templates
COPY --chown=forge:forge config/flowfuse.yml.template /usr/src/forge/etc/


# Install runtime dependencies
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
        postgresql-client \
        curl \
        ca-certificates \
    && rm -rf /var/lib/apt/lists/*


# Switch to forge user
USER forge


# Expose application port
EXPOSE 3000


# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl --fail http://localhost:3000/api/v1/ping || exit 1


# Start application
CMD ["npm", "start"]

Important Notes:

  • FlowFuse’s web application runs on port 3000 by default
  • The official image runs as a non-root user (forge) for security
  • Configuration can be provided via flowfuse.yml file or environment variables
  • PostgreSQL client is useful for database initialization and health checks

Configuration Template

Create a config/flowfuse.yml.template file for FlowFuse configuration. Sensitive values will be injected via environment variables:

# FlowFuse Configuration Template
# Sensitive values should be provided via environment variables


# Base URL for the platform (required)
base_url: ${FLOWFUSE_BASE_URL}


# Port to listen on
port: 3000


# Database configuration (PostgreSQL)
db:
  type: postgres
  host: ${DB_HOST}
  port: ${DB_PORT}
  database: ${DB_NAME}
  user: ${DB_USER}
  password: ${DB_PASSWORD}


# Logging configuration
logging:
  level: ${LOG_LEVEL:-info}
  pretty: false


# Email/SMTP configuration (optional)
email:
  enabled: ${EMAIL_ENABLED:-false}
  from: ${EMAIL_FROM}
  smtp:
    host: ${SMTP_HOST}
    port: ${SMTP_PORT}
    secure: ${SMTP_SECURE:-true}
    tls:
      rejectUnauthorized: ${SMTP_TLS_VERIFY:-true}
    auth:
      user: ${SMTP_USER}
      pass: ${SMTP_PASSWORD}


# File storage configuration
fileStore:
  type: 'localfs'
  options:
    root: '/opt/flowfuse/var/files'


# Driver configuration for Node-RED instances
driver:
  type: 'stub'


# Rate limiting
rate_limits:
  enabled: true
  timeWindow: 60000
  max: 1000


# Telemetry (optional - disable for privacy)
telemetry:
  enabled: ${TELEMETRY_ENABLED:-false}

Database Setup

FlowFuse requires PostgreSQL for storing platform data. You need to set up two databases:

Deploy PostgreSQL on Klutch.sh

  1. Follow the PostgreSQL deployment guide to create a database instance on Klutch.sh.

  2. Connect to your PostgreSQL instance and create the required databases:

-- Create FlowFuse main database
CREATE DATABASE flowfuse;


-- Create FlowFuse context database (for Node-RED context storage)
CREATE DATABASE flowfuse_context;


-- Create user with appropriate permissions
CREATE USER flowfuse_user WITH ENCRYPTED PASSWORD 'your-secure-password-here';


-- Grant privileges
GRANT ALL PRIVILEGES ON DATABASE flowfuse TO flowfuse_user;
GRANT ALL PRIVILEGES ON DATABASE flowfuse_context TO flowfuse_user;


-- Grant schema permissions
\c flowfuse
GRANT ALL ON SCHEMA public TO flowfuse_user;


\c flowfuse_context
GRANT ALL ON SCHEMA public TO flowfuse_user;
  1. Note your database connection details:
    • Host: Your PostgreSQL app URL (e.g., postgres-app.klutch.sh)
    • Port: 8000 (Klutch.sh TCP routing port)
    • Database names: flowfuse and flowfuse_context
    • Username: flowfuse_user
    • Password: Your secure password

Deploying to Klutch.sh

Follow these detailed steps to deploy FlowFuse on Klutch.sh with full configuration.

Deployment Steps

    1. Create Your Repository

      Create a new GitHub repository and add your Dockerfile:

      Terminal window
      mkdir flowfuse-deployment
      cd flowfuse-deployment
      

      # Create Dockerfile
      cat > Dockerfile << 'EOF'
      FROM flowfuse/forge:2.25
      

      WORKDIR /usr/src/forge
      

      USER root
      RUN mkdir -p /opt/flowfuse/var/files /opt/flowfuse/var/context && \
          chown -R forge:forge /opt/flowfuse && \
          apt-get update && \
          apt-get install -y --no-install-recommends postgresql-client curl && \
          rm -rf /var/lib/apt/lists/*
      

      USER forge
      

      EXPOSE 3000
      

      HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
        CMD curl --fail http://localhost:3000/api/v1/ping || exit 1
      

      CMD ["npm", "start"]
      EOF
      

      # Create .gitignore
      cat > .gitignore << 'EOF'
      node_modules/
      *.log
      .env
      .env.local
      *.key
      *.pem
      /var/
      /opt/
      .DS_Store
      EOF
      

      # Create .dockerignore
      cat > .dockerignore << 'EOF'
      node_modules
      npm-debug.log
      .git
      .gitignore
      README.md
      .env
      .env.local
      EOF
      

      # Initialize git and push
      git init
      git add .
      git commit -m "Initial FlowFuse deployment setup"
      git remote add origin https://github.com/YOUR_USERNAME/flowfuse-deployment.git
      git push -u origin main

    2. Access the Klutch.sh Dashboard

      Navigate to klutch.sh/app and log in to your account.

    3. Create a New Project

      • Click “New Project” in the dashboard
      • Enter a project name (e.g., “Industrial IoT Platform”)
      • Select your preferred region for deployment

    4. Create a New Application

      • Within your project, click “New App”
      • Name your application (e.g., “FlowFuse”)
      • Connect your GitHub repository containing the Dockerfile

    5. Configure Traffic Settings

      • In the app settings, select HTTP as the traffic type
      • FlowFuse serves web traffic on HTTP for both the UI and API
      • Set the internal port to 3000 (FlowFuse’s default HTTP port)

    6. Set Up Persistent Storage

      FlowFuse requires persistent storage for file operations and context data:

      • In the app settings, navigate to the “Volumes” section
      • Click “Add Volume” for file storage:
        • Mount path: /opt/flowfuse/var/files
        • Size: 10GB (adjust based on expected usage)
      • Click “Add Volume” for context storage:
        • Mount path: /opt/flowfuse/var/context
        • Size: 5GB (adjust based on number of instances)

      Important: These directories store:

      • /opt/flowfuse/var/files: File nodes data, uploaded files, persistent storage for Node-RED instances
      • /opt/flowfuse/var/context: Node-RED context data across instances

    7. Configure Environment Variables

      Add the following environment variables for FlowFuse configuration:

      Core Configuration:

      Terminal window
      # Base URL (use your Klutch.sh app URL or custom domain)
      FLOWFUSE_BASE_URL=https://flowfuse-app.klutch.sh
      

      # Logging
      LOG_LEVEL=info

      Database Configuration:

      Terminal window
      # PostgreSQL connection details
      DB_HOST=postgres-app.klutch.sh
      DB_PORT=8000
      DB_NAME=flowfuse
      DB_USER=flowfuse_user
      DB_PASSWORD=your-secure-database-password

      Email Configuration (Optional but Recommended):

      Terminal window
      # Enable email functionality
      EMAIL_ENABLED=true
      EMAIL_FROM=noreply@yourdomain.com
      

      # SMTP configuration (example using Gmail)
      SMTP_HOST=smtp.gmail.com
      SMTP_PORT=587
      SMTP_SECURE=false
      SMTP_USER=your-email@gmail.com
      SMTP_PASSWORD=your-app-specific-password
      SMTP_TLS_VERIFY=true

      Optional Configuration:

      Terminal window
      # Disable telemetry for privacy
      TELEMETRY_ENABLED=false
      

      # Session configuration
      SESSION_SECRET=generate-random-64-char-string-here

      Generate secure secrets:

      Terminal window
      # Generate SESSION_SECRET
      openssl rand -hex 32
      

      # Generate strong database password
      openssl rand -base64 32

    8. Deploy the Application

      • Review all configuration settings
      • Click “Deploy” to start the build process
      • Klutch.sh will automatically detect your Dockerfile, build the container, and deploy it
      • Monitor the build logs for any errors
      • Initial deployment takes 2-3 minutes for image download and startup

    9. Verify Deployment

      Once deployment completes:

      • Access FlowFuse at your Klutch.sh URL (e.g., https://flowfuse-app.klutch.sh)
      • You should see the FlowFuse setup wizard
      • Check the health endpoint: https://flowfuse-app.klutch.sh/api/v1/ping

    10. Complete Initial Setup

      On first access, FlowFuse will guide you through:

      • Creating the platform administrator account
      • Setting up your first team
      • Configuring default project settings
      • Creating your first Node-RED instance

First Run Configuration

After accessing FlowFuse for the first time, complete the setup wizard:

Administrator Account Setup

  1. Navigate to your FlowFuse URL
  2. Create the administrator account:
    • Username: Choose a memorable admin username
    • Email: Your administrative email
    • Password: Strong password (minimum 8 characters)
    • Full Name: Your name

Platform Configuration

Configure platform-wide settings:

// Example: Default stack configuration
{
  "name": "Node-RED 3.1",
  "properties": {
    "cpu": 100,      // 0.1 CPU cores
    "memory": 256    // 256MB RAM
  },
  "container": "flowfuse/node-red:3.1"
}

Create Your First Team

  1. Click “Create Team” in the dashboard
  2. Configure team settings:
    • Team name: Your organization or department name
    • Team type: Choose based on your subscription
    • Team slug: URL-friendly identifier

Create Your First Project

  1. Within your team, click “Create Project”
  2. Configure project settings:
    • Project name: Descriptive name for your application
    • Stack: Select Node-RED version and resources
    • Template: Choose starting template or blank

Creating Node-RED Instances

FlowFuse manages individual Node-RED instances for each project:

Via Web UI

  1. Navigate to your team dashboard
  2. Click “Create Instance”
  3. Configure instance:
    • Name: Descriptive name (e.g., “Production Gateway”)
    • Stack: Node-RED version and resource allocation
    • Template: Starting configuration template
    • Credentials: Auto-generated secure credentials

Instance Configuration Options

# Example instance configuration
instance:
  name: "Factory Floor Gateway"
  stack: "node-red-3.1"
  settings:
    httpAdminRoot: "/admin"
    httpNodeRoot: "/"
    credentialSecret: "auto-generated-by-flowfuse"
    flowFile: "flows.json"
    userDir: "/data"
  resources:
    cpu: "0.5"
    memory: "512Mi"
  environment:
    - name: "TZ"
      value: "America/New_York"
    - name: "NODE_OPTIONS"
      value: "--max-old-space-size=460"

Connecting to Your Instances

Access your deployed Node-RED instances:

Direct Access

Each instance gets a unique URL:

https://instance-name-team-slug.flowfuse-app.klutch.sh

API Access

Use FlowFuse API to manage instances programmatically:

Terminal window
# Get list of instances
curl -X GET https://flowfuse-app.klutch.sh/api/v1/teams/{teamId}/projects \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"


# Get instance details
curl -X GET https://flowfuse-app.klutch.sh/api/v1/projects/{projectId} \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"


# Start/stop instance
curl -X POST https://flowfuse-app.klutch.sh/api/v1/projects/{projectId}/actions/start \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Node.js Client Example

const FlowFuseClient = require('@flowfuse/flowfuse-client');


const client = new FlowFuseClient({
  baseURL: 'https://flowfuse-app.klutch.sh',
  accessToken: process.env.FLOWFUSE_TOKEN
});


async function listProjects(teamId) {
  try {
    const projects = await client.teams.getProjects(teamId);
    console.log('Projects:', projects);


    for (const project of projects) {
      console.log(`Project: ${project.name}`);
      console.log(`URL: ${project.url}`);
      console.log(`Status: ${project.state}`);
    }
  } catch (error) {
    console.error('Error fetching projects:', error);
  }
}


// List all projects for a team
listProjects('your-team-id');

Python Client Example

import requests
import os


FLOWFUSE_URL = "https://flowfuse-app.klutch.sh"
ACCESS_TOKEN = os.getenv("FLOWFUSE_TOKEN")


headers = {
    "Authorization": f"Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json"
}


def list_team_projects(team_id):
    """List all projects for a team"""
    response = requests.get(
        f"{FLOWFUSE_URL}/api/v1/teams/{team_id}/projects",
        headers=headers
    )


    if response.status_code == 200:
        projects = response.json()
        for project in projects['projects']:
            print(f"Project: {project['name']}")
            print(f"URL: {project['url']}")
            print(f"Status: {project['state']}")
    else:
        print(f"Error: {response.status_code}")
        print(response.text)


# Usage
list_team_projects("your-team-id")

Installing Custom Node Packages

Add custom Node-RED nodes to your instances:

Via FlowFuse UI

  1. Navigate to instance settings
  2. Go to “Palette Management”
  3. Search for nodes in the Node-RED catalog
  4. Click “Install” on desired packages

Programmatically via API

Terminal window
# Install a node package
curl -X POST https://flowfuse-app.klutch.sh/api/v1/projects/{projectId}/nodes \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "module": "node-red-contrib-modbus",
    "version": "5.x"
  }'

Common Industrial Nodes

// Popular packages for industrial IoT
const industrialNodes = [
  'node-red-contrib-modbus',      // Modbus TCP/RTU
  'node-red-contrib-opcua',       // OPC-UA client/server
  'node-red-contrib-s7',          // Siemens S7 PLCs
  'node-red-contrib-influxdb',    // InfluxDB time-series
  'node-red-dashboard',           // Dashboard UI
  'node-red-contrib-mqtt-broker', // MQTT broker
  '@flowfuse/node-red-dashboard'  // FlowFuse Dashboard 2.0
];

Snapshots and Version Control

FlowFuse provides built-in snapshot functionality for version control:

Create Snapshot

Terminal window
# Create snapshot of current flows
curl -X POST https://flowfuse-app.klutch.sh/api/v1/projects/{projectId}/snapshots \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Release v1.2.0",
    "description": "Added temperature monitoring flows"
  }'

Restore from Snapshot

Terminal window
# Restore project to a snapshot
curl -X POST https://flowfuse-app.klutch.sh/api/v1/projects/{projectId}/actions/rollback \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "snapshotId": "snapshot-id-here"
  }'

DevOps Pipelines

Set up development, staging, and production pipeline:

  1. Create three projects: dev, staging, production
  2. Develop flows in dev environment
  3. Create snapshot when ready
  4. Deploy snapshot to staging for testing
  5. After validation, deploy to production
// Example pipeline automation
async function promoteToProd(devProjectId, prodProjectId) {
  // Create snapshot of dev environment
  const snapshot = await client.projects.createSnapshot(devProjectId, {
    name: `Promotion-${Date.now()}`,
    description: 'Automated promotion to production'
  });


  // Deploy snapshot to production
  await client.projects.deploySnapshot(prodProjectId, snapshot.id);


  console.log('Successfully promoted to production');
}

Device Agent Configuration

FlowFuse Device Agent enables remote Node-RED management on edge devices:

Installing Device Agent

On your edge device (Raspberry Pi, industrial PC, etc.):

Terminal window
# Install Node.js (if not present)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs


# Install FlowFuse Device Agent
sudo npm install -g @flowfuse/device-agent


# Create device configuration
sudo mkdir -p /opt/flowfuse-device
cd /opt/flowfuse-device


# Initialize device configuration
flowfuse-device-agent --init

Register Device with FlowFuse

  1. In FlowFuse UI, navigate to your team
  2. Go to “Devices” section
  3. Click “Add Device”
  4. Copy the device registration token

On the device:

Terminal window
# Configure device
cat > device.yml << EOF
deviceId: your-device-id
token: your-device-token
forgeURL: https://flowfuse-app.klutch.sh
credentialSecret: generate-random-secret
EOF


# Start device agent
flowfuse-device-agent --config device.yml

Deploy Flows to Devices

Terminal window
# Create device snapshot
curl -X POST https://flowfuse-app.klutch.sh/api/v1/devices/{deviceId}/snapshots/deploy \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "snapshotId": "snapshot-id-to-deploy"
  }'

Team Broker (MQTT) Setup

Enable Team Broker for inter-instance communication:

Configuration

Add to your FlowFuse configuration:

# Team Broker configuration
broker:
  enabled: true
  port: 1883
  websocket:
    enabled: true
    port: 8083
  auth:
    type: 'flowfuse'

Using Team Broker in Node-RED

// MQTT configuration for Team Broker
const mqtt = {
  broker: 'mqtt://flowfuse-app.klutch.sh',
  port: 1883,
  clientId: 'instance-name',
  username: 'team:team-slug:instance-name',
  password: 'auto-generated-token'
};


// In Node-RED flow
[
  {
    "id": "mqtt-in",
    "type": "mqtt in",
    "broker": "team-broker",
    "topic": "sensors/temperature",
    "qos": "1"
  },
  {
    "id": "mqtt-out",
    "type": "mqtt out",
    "broker": "team-broker",
    "topic": "actuators/valve",
    "qos": "1"
  }
]

Email Configuration

Configure SMTP for team invitations and notifications:

Gmail Configuration

Terminal window
# Gmail SMTP settings
EMAIL_ENABLED=true
EMAIL_FROM=your-app@gmail.com
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-app@gmail.com
SMTP_PASSWORD=your-app-specific-password

SendGrid Configuration

Terminal window
# SendGrid SMTP settings
EMAIL_ENABLED=true
EMAIL_FROM=noreply@yourdomain.com
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASSWORD=your-sendgrid-api-key

Amazon SES Configuration

Terminal window
# Amazon SES SMTP settings
EMAIL_ENABLED=true
EMAIL_FROM=noreply@yourdomain.com
SMTP_HOST=email-smtp.us-east-1.amazonaws.com
SMTP_PORT=587
SMTP_USER=your-ses-smtp-username
SMTP_PASSWORD=your-ses-smtp-password

Custom Domain Configuration

Map your own domain to FlowFuse:

DNS Setup

  1. Add Custom Domain in Klutch.sh

    • Navigate to your FlowFuse app settings
    • Go to “Domains” section
    • Add your domain (e.g., flows.yourdomain.com)
    • Note the CNAME target provided

  2. Configure DNS Records

    Add CNAME record in your DNS provider:

    Type: CNAME
    Name: flows
    Value: your-app.klutch.sh
    TTL: 3600

  3. Update FlowFuse Configuration

    Update the FLOWFUSE_BASE_URL environment variable:

    Terminal window
    FLOWFUSE_BASE_URL=https://flows.yourdomain.com

  4. Wildcard Domain for Instances

    Add wildcard CNAME for instance subdomains:

    Type: CNAME
    Name: *.flows
    Value: your-app.klutch.sh
    TTL: 3600

    This enables URLs like: instance-name.flows.yourdomain.com

Monitoring and Logging

Health Checks

FlowFuse provides health endpoints:

Terminal window
# Check platform health
curl https://flowfuse-app.klutch.sh/api/v1/ping


# Expected response
{
  "status": "okay",
  "version": "2.25.0"
}

Application Logs

Monitor FlowFuse logs through Klutch.sh dashboard:

  • Platform startup and initialization
  • User authentication events
  • Instance creation and management
  • Database connection status
  • API request logs

Metrics Collection

Enable Prometheus metrics:

# Add to configuration
telemetry:
  enabled: true
  prometheus:
    enabled: true
    port: 9090

Access metrics at: https://flowfuse-app.klutch.sh/metrics

Key metrics to monitor:

  • flowfuse_instances_total: Total number of Node-RED instances
  • flowfuse_instances_active: Currently running instances
  • flowfuse_api_requests_total: API request count
  • flowfuse_api_request_duration_seconds: API response time
  • flowfuse_db_connections: Database connection pool status

Backup and Recovery

Database Backup

Regularly backup your PostgreSQL databases:

Terminal window
# Backup FlowFuse main database
pg_dump -h postgres-app.klutch.sh -p 8000 -U flowfuse_user flowfuse \
  > flowfuse-backup-$(date +%Y%m%d).sql


# Backup context database
pg_dump -h postgres-app.klutch.sh -p 8000 -U flowfuse_user flowfuse_context \
  > flowfuse-context-backup-$(date +%Y%m%d).sql

File Storage Backup

Backup persistent volumes containing file data:

Terminal window
# Create backup of file storage
tar -czf flowfuse-files-backup-$(date +%Y%m%d).tar.gz \
  /opt/flowfuse/var/files

Disaster Recovery

To restore FlowFuse after failure:

  1. Deploy new FlowFuse instance on Klutch.sh
  2. Restore PostgreSQL databases from backups
  3. Restore file storage volumes
  4. Update database connection strings
  5. Restart FlowFuse application
  6. Verify all instances are accessible

Troubleshooting

Common Issues

Issue: Cannot access FlowFuse UI

  • Verify the app is running in Klutch.sh dashboard
  • Check port 3000 is correctly configured as internal port
  • Review application logs for startup errors
  • Verify health endpoint: curl https://your-app.klutch.sh/api/v1/ping

Issue: Database connection errors

Error: Connection refused to PostgreSQL
  • Verify database credentials in environment variables
  • Check PostgreSQL is running and accessible
  • Ensure database host and port are correct (host:8000 for Klutch.sh)
  • Test connection: psql -h postgres-app.klutch.sh -p 8000 -U flowfuse_user -d flowfuse

Issue: Email notifications not sending

  • Verify EMAIL_ENABLED=true is set
  • Check SMTP credentials are correct
  • Test SMTP connection from container
  • Review email logs for delivery errors
  • Check spam folders for test emails

Issue: Node-RED instances fail to start

  • Check instance logs in FlowFuse UI
  • Verify sufficient resources (CPU/memory) allocated
  • Ensure file storage volume is attached and writable
  • Review stack configuration for errors

Issue: Unable to install custom nodes

  • Verify internet connectivity from container
  • Check npm registry accessibility
  • Review package compatibility with Node-RED version
  • Check for conflicting node dependencies

Issue: Device Agent not connecting

  • Verify device token is correct
  • Check forgeURL points to correct FlowFuse instance
  • Ensure firewall allows outbound HTTPS
  • Review device agent logs for connection errors

Debug Mode

Enable debug logging for troubleshooting:

Terminal window
# Set log level to debug
LOG_LEVEL=debug

Or for specific components:

Terminal window
# Debug database queries
DEBUG=flowfuse:db:*


# Debug authentication
DEBUG=flowfuse:auth:*


# Debug all components
DEBUG=flowfuse:*

Database Issues

Check database connectivity:

Terminal window
# Test PostgreSQL connection
docker exec -it flowfuse-container psql \
  -h postgres-app.klutch.sh \
  -p 8000 \
  -U flowfuse_user \
  -d flowfuse \
  -c "SELECT version();"

Performance Diagnostics

Monitor resource usage:

Terminal window
# Check container stats
docker stats flowfuse-container


# Review memory usage
docker exec -it flowfuse-container free -h


# Check disk space
docker exec -it flowfuse-container df -h

Production Best Practices

Security Hardening

  • Use strong passwords: Generate complex passwords for database and admin accounts
  • Enable HTTPS: Always use SSL/TLS in production (automatic with Klutch.sh)
  • Rotate secrets: Regularly update session secrets and database passwords
  • Implement RBAC: Use FlowFuse’s role-based access control for team members
  • Audit logging: Enable comprehensive audit trails for compliance
  • Network isolation: Restrict database access to FlowFuse container only

Performance Optimization

  • Database connection pooling: Configure appropriate connection limits
db:
  pool:
    min: 2
    max: 10
    acquire: 30000
    idle: 10000
  • Resource allocation: Size instances based on flow complexity
# Light flows: 0.1 CPU, 256MB RAM
# Medium flows: 0.5 CPU, 512MB RAM
# Heavy flows: 1 CPU, 1GB RAM
  • Caching: Enable Redis for session caching (optional)
  • File storage: Use external object storage (S3-compatible) for large deployments

High Availability

For mission-critical deployments:

  • Database replication: Set up PostgreSQL primary-replica configuration
  • Load balancing: Deploy multiple FlowFuse instances behind load balancer
  • Backup automation: Schedule regular automated backups
  • Monitoring alerts: Set up alerting for downtime and errors
  • Disaster recovery: Document and test recovery procedures

Scaling Strategy

As your deployment grows:

  • Vertical scaling: Increase CPU/memory for FlowFuse container
  • Horizontal scaling: Deploy multiple FlowFuse instances (requires shared database)
  • Database optimization: Add read replicas for reporting queries
  • File storage: Migrate to object storage for unlimited capacity
  • Instance distribution: Distribute Node-RED instances across multiple FlowFuse servers

Cost Optimization

Resource Sizing

FlowFuse resource requirements:

  • Small deployment (< 10 instances): 1 CPU, 2GB RAM, 10GB storage
  • Medium deployment (10-50 instances): 2 CPU, 4GB RAM, 50GB storage
  • Large deployment (50+ instances): 4+ CPU, 8GB+ RAM, 100GB+ storage

Storage Management

  • Regularly clean up old snapshots
  • Archive inactive projects
  • Compress log files
  • Monitor file storage usage

Database Optimization

  • Implement data retention policies
  • Archive historical audit logs
  • Optimize indexes for query performance
  • Regular VACUUM operations

Migration from FlowFuse Cloud

To migrate from FlowFuse Cloud to self-hosted on Klutch.sh:

  1. Export Projects: Download snapshots of all projects
  2. Export Teams: Document team structure and memberships
  3. Deploy FlowFuse: Follow this guide to deploy on Klutch.sh
  4. Import Snapshots: Upload snapshots to new FlowFuse instance
  5. Migrate Users: Invite team members to new platform
  6. Update DNS: Point custom domains to new deployment
  7. Verify: Test all flows and integrations
  8. Cutover: Shut down Cloud instances after verification

Getting Started Checklist

Before going to production with FlowFuse:

  • PostgreSQL database deployed and configured
  • Both flowfuse and flowfuse_context databases created
  • Persistent volumes attached for file and context storage
  • Environment variables configured with secure secrets
  • SMTP configured for email notifications
  • Custom domain configured (optional)
  • First administrator account created
  • Team structure planned and created
  • Project templates configured
  • Stack configurations defined
  • Backup strategy implemented
  • Monitoring and alerting configured
  • Documentation created for team
  • Test instance deployed and verified
  • Production rollout plan documented

Resources

Conclusion

Deploying FlowFuse on Klutch.sh provides enterprise-grade Node-RED management with simplified infrastructure, persistent storage, and database integration. By following this guide, you’ve set up a production-ready industrial application platform capable of managing hundreds of Node-RED instances, connecting thousands of industrial devices, and serving teams of developers building the next generation of industrial IoT applications. With AI-assisted development, collaborative workflows, and centralized management, FlowFuse on Klutch.sh empowers your team to bridge the IT/OT divide and accelerate digital transformation initiatives across your industrial operations.