Installation on Ubuntu

Deploy the Flomation platform on Ubuntu 22.04 LTS, 24.04 LTS.

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.

bashCopy
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:

bashCopy
apt policy flomation-sentinel

output
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:

sqlCopy
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

bashCopy
sudo apt install -y flomation-sentinel

Configure

Create the configuration file:

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

jsonCopy
{
  "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:

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

Configuration Reference

Start

bashCopy
sudo systemctl enable --now flomation-sentinel

Verify the service is running:

bashCopy
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

bashCopy
sudo apt install -y flomation-api

Configure

Create the configuration file:

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

jsonCopy
{
  "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:

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

Configuration Reference

Start

bashCopy
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

bashCopy
sudo apt install -y flomation-launch

Configure

Create the configuration file:

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

jsonCopy
{
  "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:

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

Configuration Reference

Start

bashCopy
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

bashCopy
sudo apt install -y flomation-editor

Configure

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

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

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

Set appropriate permissions:

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

Configuration Reference

Start

bashCopy
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

bashCopy
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:

bashCopy
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:

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

jsonCopy
{
  "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:

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

Set appropriate permissions:

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

Configuration Reference

Start

bashCopy
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:

bashCopy
# 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:

bashCopy
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:

bashCopy
sudo ufw allow 8888/tcp

Verify the firewall rules:

bashCopy
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:

bashCopy
sudo dmesg | grep -i apparmor

To view the status of all AppArmor profiles:

bashCopy
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:

bashCopy
sudo dmesg | grep "DENIED"

15 TLS & Reverse Proxy

It is strongly recommended to place a TLS-terminating reverse proxy in front of all Flomation services.

The services themselves listen on plain HTTP. Use a reverse proxy such as nginx, HAProxy, or Caddy to terminate TLS.

Configuring a reverse proxy is outside the scope of this guide. At a minimum, ensure:

• All external-facing endpoints (Sentinel, API, Launch, Editor) are served over HTTPS.
• The X-Forwarded-For and X-Forwarded-Proto headers are set correctly.
• Sentinel's security.cookie.secure is set to true when serving over HTTPS.
• The listener.url (Sentinel), security.identity_service (API), and all URL references in the Editor environment file use https:// URLs.

16 Troubleshooting

Service fails to start

Check the service logs:

bashCopy
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.