Installation on Ubuntu

01 Overview

The Flomation platform consists of six components.

Architecture

Each backend service (Sentinel, API, Launch) requires its own PostgreSQL database. These can run on the same PostgreSQL server for cost savings. The Runner polls the API for pending executions and invokes the Executor to run workflows.

02 Prerequisites

• Ubuntu 22.04 LTS or 24.04 LTS
• Root or sudo access
• A PostgreSQL server (see Section 4)
• Network connectivity between all component hosts
• SMTP server (required for user registration email verification)

Recommended Install Order

Components should be installed and configured in this order, as later services depend on earlier ones:

1. PostgreSQL database
2. Sentinel (identity — no dependencies on other Flomation services)
3. API (depends on Sentinel)
4. Launch (depends on API)
5. Editor (depends on API, Launch, and Sentinel)
6. Executor and Runner (depend on API)

03 Install the Flomation Repository

Install the Flomation apt repository configuration package on each host that will run a Flomation component.

wget https://flomation-packages-live.s3.eu-west-2.amazonaws.com/apt/flomation-repo_1.0.1-1_all.deb
sudo dpkg -i flomation-repo_1.0.1-1_all.deb
sudo apt update

Verify the repository is available:

apt policy flomation-sentinel

flomation-sentinel:
  Installed: (none)
  Candidate: 1.0.1-1
  Version table:
     1.0.1-1 500
        500 https://flomation-packages-live.s3.eu-west-2.amazonaws.com/apt stable/main amd64 Packages

04 PostgreSQL Database

The Flomation platform requires a PostgreSQL database with the uuid-ossp and pgcrypto extensions.

Setting up and administering PostgreSQL is outside the scope of this guide. Ensure you have a running PostgreSQL instance accessible from the hosts running Sentinel, API, and Launch.

Create the Database

Connect to your PostgreSQL server and create a database and user for Flomation:

CREATE USER flomation WITH PASSWORD 'your-secure-password';

-- Create a database for each service
CREATE DATABASE flomation_sentinel OWNER flomation;
CREATE DATABASE flomation_api OWNER flomation;
CREATE DATABASE flomation_launch OWNER flomation;

-- Enable required extensions on each database
\c flomation_sentinel
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
CREATE EXTENSION IF NOT EXISTS "pgcrypto";

\c flomation_api
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
CREATE EXTENSION IF NOT EXISTS "pgcrypto";

\c flomation_launch
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
CREATE EXTENSION IF NOT EXISTS "pgcrypto";

05 Install Flomation Sentinel

Sentinel provides identity and access management — authentication, user accounts, sessions, and MFA.

Install

sudo apt install -y flomation-sentinel

Configure

Create the configuration file:

sudo vi /opt/flomation/sentinel/config.json

{
  "listener": {
    "address": "0.0.0.0",
    "port": 8999,
    "url": "https://sentinel.example.com"
  },
  "database": {
    "hostname": "db.example.com",
    "port": 5432,
    "username": "flomation",
    "password": "your-secure-password",
    "database": "flomation_sentinel",
    "encryption_key": "PLACEHOLDER-GENERATE-A-SECURE-KEY",
    "ssl_mode": "require"
  },
  "security": {
    "cookie": {
      "domain": "example.com",
      "secure": true,
      "http_only": true,
      "expiration": 86400
    },
    "realm": "example.com",
    "secret": "PLACEHOLDER-GENERATE-A-SECURE-SECRET",
    "login_redirect": "https://editor.example.com/",
    "logout_redirect": "https://editor.example.com/logout"
  },
  "notification": {
    "enabled": true,
    "send_from": "noreply@example.com",
    "smtp": {
      "host": "smtp.example.com",
      "port": 587,
      "username": "smtp-user",
      "password": "smtp-password"
    }
  }
}

Set appropriate permissions on the configuration file:

sudo chown flomation:flomation /opt/flomation/sentinel/config.json
sudo chmod 640 /opt/flomation/sentinel/config.json

Configuration Reference

Start

sudo systemctl enable --now flomation-sentinel

Verify the service is running:

sudo systemctl status flomation-sentinel

06 Install Flomation API

The API server is the core of the platform — it manages organisations, workflows, executions, runners, and environments.

Install

sudo apt install -y flomation-api

Configure

Create the configuration file:

sudo vi /opt/flomation/api/config.json

{
  "http": {
    "address": "0.0.0.0",
    "port": 8888
  },
  "database": {
    "hostname": "db.example.com",
    "port": 5432,
    "username": "flomation",
    "password": "your-secure-password",
    "database": "flomation_api",
    "encryption_key": "PLACEHOLDER-GENERATE-A-SECURE-KEY",
    "ssl_mode": "require"
  },
  "security": {
    "identity_service": "https://sentinel.example.com"
  },
  "launch": {
    "url": "https://launch.example.com"
  }
}

Set appropriate permissions:

sudo chown flomation:flomation /opt/flomation/api/config.json
sudo chmod 640 /opt/flomation/api/config.json

Configuration Reference

Start

sudo systemctl enable --now flomation-api

07 Install Flomation Launch

Launch is the trigger and webhook ingress service — it handles webhooks, QR codes, forms, tracking pixels, and scheduled triggers.

Install

sudo apt install -y flomation-launch

Configure

Create the configuration file:

sudo vi /opt/flomation/launch/config.json

{
  "http": {
    "address": "0.0.0.0",
    "port": 8081
  },
  "database": {
    "hostname": "db.example.com",
    "port": 5432,
    "username": "flomation",
    "password": "your-secure-password",
    "database": "flomation_launch",
    "encryption_key": "PLACEHOLDER-GENERATE-A-SECURE-KEY",
    "ssl_mode": "require"
  },
  "automate": {
    "url": "https://api.example.com"
  }
}

Set appropriate permissions:

sudo chown flomation:flomation /opt/flomation/launch/config.json
sudo chmod 640 /opt/flomation/launch/config.json

Configuration Reference

Start

sudo systemctl enable --now flomation-launch

08 Install Flomation Editor

The Editor is the web-based UI for designing and managing workflows. It is a Node.js application (React Router / SSR).

Install

sudo apt install -y flomation-editor

Configure

The Editor is configured via an environment file. Copy the sample and edit it:

sudo cp /opt/flomation/editor/etc/environment.sample /opt/flomation/editor/etc/environment
sudo vi /opt/flomation/editor/etc/environment

# Flomation Editor Configuration
AUTOMATE_API_URL=https://api.example.com
BILLING_API_URL=https://billing.example.com
TRIGGER_URL=https://launch.example.com
LOGIN_URL=https://sentinel.example.com
LAUNCH_URL=https://launch.example.com
PORT=8080
NODE_ENV=production

Set appropriate permissions:

sudo chown flomation:flomation /opt/flomation/editor/etc/environment
sudo chmod 640 /opt/flomation/editor/etc/environment

Configuration Reference

Start

sudo systemctl enable --now flomation-editor

09 Install Flomation Executor

The Executor is a command-line tool that runs workflow definitions. It is invoked by the Runner and does not run as a persistent service.

Install

sudo apt install -y flomation-executor

The Executor binary is installed to /opt/flomation/executor/ and added to the system PATH via /etc/profile.d/flomation-executor.sh.

No additional configuration is needed — the Runner passes all required parameters when invoking the Executor.

10 Install Flomation Runner

The Runner is a background agent that polls the Flomation API for pending workflow executions and invokes the Executor to run them.

Install

Install both the Runner and Executor on the same host:

sudo apt install -y flomation-runner flomation-executor

Obtain a Registration Code

Before configuring the Runner, you need a registration code from the API server. This is generated through the Flomation Editor UI after initial platform setup (see Section 11).

Configure

Create the configuration file:

sudo vi /opt/flomation/runner/config.json

{
  "runner": {
    "url": "https://api.example.com",
    "registration_code": "your-registration-code",
    "name": "runner-01",
    "checkin_timeout": 5,
    "certificate": "flomation-runner.pem"
  },
  "execution": {
    "max_concurrent_executors": 5,
    "execution_directory": "/opt/flomation/runner/workspace/",
    "executable_name": "flomation-executor"
  }
}

Create the workspace directory:

sudo mkdir -p /opt/flomation/runner/workspace
sudo chown flomation:flomation /opt/flomation/runner/workspace

Set appropriate permissions:

sudo chown flomation:flomation /opt/flomation/runner/config.json
sudo chmod 640 /opt/flomation/runner/config.json

Configuration Reference

Start

sudo systemctl enable --now flomation-runner

11 First-Time Setup

Once all services are running, follow these steps to bootstrap the platform.

1. Register the First User

Sentinel provides a self-registration flow:

1. Navigate to your Sentinel instance's /authenticate endpoint in a browser (e.g. https://sentinel.example.com/authenticate).
2. Enter your email address. Since no accounts exist yet, Sentinel will present a registration prompt.
3. Click Create account.
4. Check your email for a verification message containing a link to set your password.
5. Click the verification link and set your password.

2. Log In to the Editor

Navigate to your Editor instance (e.g. https://editor.example.com). You will be redirected to Sentinel to authenticate. Log in with the credentials you just created.

3. Create an Organisation

After logging in, the API automatically creates your user record. You can then create your first organisation through the Editor UI.

4. Register a Runner

To execute workflows, you need at least one Runner registered:

1. In the Editor, navigate to the Runners section.
2. Generate a registration code.
3. Use this registration code in the Runner's config.json (see Section 10).
4. Start (or restart) the Runner service.

12 Service Management

All Flomation services are managed via systemd. The DEB packages install service unit files to /etc/systemd/system/.

Common operations:

# Start a service
sudo systemctl start flomation-api

# Stop a service
sudo systemctl stop flomation-api

# Restart a service
sudo systemctl restart flomation-api

# View service status
sudo systemctl status flomation-api

# View logs
sudo journalctl -u flomation-api -f

Log Files

Service logs are written to:

• stdout/stderr logs: /opt/flomation/<component>/logs/<component>.log and .err
• Symlink: /var/log/flomation/<component> points to the logs directory

File Locations

Upgrades

To upgrade a component:

sudo apt update
sudo apt upgrade flomation-api

The DEB upgrade process automatically:

1. Stops the running service.
2. Creates a snapshot of the current installation in /opt/flomation/snapshots/.
3. Installs the new version.
4. Restarts the service.

13 Firewall Configuration (UFW)

If ufw is enabled, you will need to open ports for each service running on the host. The specific ports depend on your configuration.

For example, to allow traffic to the API on port 8888:

sudo ufw allow 8888/tcp

Verify the firewall rules:

sudo ufw status

Repeat for each service port as needed. Only open ports that need to be accessible from other hosts — services communicating on localhost do not require firewall rules.

14 AppArmor

Ubuntu uses AppArmor as its mandatory access control framework. In most cases no configuration is required for Flomation services.

To verify that AppArmor is active:

sudo dmesg | grep -i apparmor

To view the status of all AppArmor profiles:

sudo aa-status

If a Flomation service is being blocked by AppArmor, the denial will appear in the system log. You can check for denials with:

sudo dmesg | grep "DENIED"

15 TLS Configuration

The Sentinel, API, and Launch services support TLS termination directly. This is the recommended way to serve Flomation over HTTPS — a separate reverse proxy is not required.

Direct TLS termination (recommended)

Place the certificate and private key in each service's installation root:

• /opt/flomation/sentinel/certificate.crt and /opt/flomation/sentinel/certificate.key
• /opt/flomation/api/certificate.crt and /opt/flomation/api/certificate.key
• /opt/flomation/launch/certificate.crt and /opt/flomation/launch/certificate.key

When these files are present, the service serves HTTPS automatically.

When serving over HTTPS, also ensure:

• Sentinel's security.cookie.secure is set to true.
• The listener.url (Sentinel), security.identity_service (API), and all URL references in the Editor environment file use https:// URLs.

Editor

The Editor service does not support TLS termination directly. To serve the Editor over HTTPS, place it behind a reverse proxy such as nginx, HAProxy, or Caddy that handles TLS termination.

Example: nginx

server {
    listen 80;
    server_name editor.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name editor.example.com;

    ssl_certificate     /etc/nginx/ssl/editor.crt;
    ssl_certificate_key /etc/nginx/ssl/editor.key;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;

        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Replace editor.example.com and the certificate paths with values appropriate for your environment.

Reverse proxy (optional for Sentinel, API, Launch)

A TLS-terminating reverse proxy such as HAProxy, nginx, or Caddy is also supported in front of Sentinel, API, and Launch. This can be useful for consolidating certificates, terminating TLS at the network edge, or fronting multiple services on a single hostname.

When using a reverse proxy, ensure the X-Forwarded-For and X-Forwarded-Proto headers are set correctly.

16 Troubleshooting

Service fails to start

Check the service logs:

sudo journalctl -u flomation-<component> -e --no-pager
sudo cat /opt/flomation/<component>/logs/<component>.err

Database connection errors

• Verify PostgreSQL is running and accessible from the service host.
• Check that the database credentials in config.json are correct.
• Ensure the uuid-ossp and pgcrypto extensions are installed on the database.
• If using SSL, verify the ssl_mode setting matches your PostgreSQL configuration.

Editor shows blank page or API errors

• Verify the URLs in /opt/flomation/editor/etc/environment are correct and reachable from the user's browser (these are client-side URLs).
• Delete /opt/flomation/editor/build/client/run-config.js and restart the Editor service to regenerate it from the environment file.

Runner cannot register

• Verify the runner.url in the Runner's config.json points to the API server.
• Ensure the registration code is valid and has not already been used.
• Check that the Runner can reach the API server over the network.

Verification email not received

• Check Sentinel logs for SMTP errors.
• Verify SMTP settings in Sentinel's config.json.
• Ensure notification.enabled is set to true.