Local Execution Setup Guide

This guide will help you set up Flowguard to execute flows on your own server instead of using the cloud-based execution service.

Why Use Local Execution?

Running Flowguard locally on your server provides several benefits:

Privacy: All test data stays on your server
Performance: Lower latency for flow executions
Control: Full control over the execution environment
Cost: No dependency on external services

Prerequisites

Before you begin, ensure your server meets these requirements:

Node.js version 18.0.0 or higher
npm version 8.0.0 or higher
Sufficient disk space for Playwright browsers (~500MB)
Server access to install packages and run Node.js processes

Step-by-Step Setup

1. Install Node.js

If Node.js is not already installed on your server:

Ubuntu/Debian

bash

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

CentOS/RHEL

bash

curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo yum install -y nodejs

macOS (using Homebrew)

bash

brew install node

Verify the installation:

bash

node --version
npm --version

2. Copy the API Directory

Copy the Flowguard API directory to a location on your server:

bash

# Example: Copy from plugin directory to a custom location
cp -r /path/to/wordpress/wp-content/plugins/flowguard/api /var/www/flowguard-api

Note: You can place the API directory anywhere on your server. Make sure the directory is readable and executable by your web server user.

3. Install Dependencies

Navigate to the API directory and install the required npm packages:

bash

cd /var/www/flowguard-api
npm install

This will install:

express - Web server framework
playwright - Browser automation library
axios - HTTP client
dotenv - Environment variable management

4. Install Playwright Browsers

Playwright requires browser binaries to be installed:

bash

npx playwright install

This downloads and installs Chromium, Firefox, and WebKit browsers.

For headless servers, you may need to install additional system dependencies:

bash

# Ubuntu/Debian
npx playwright install-deps

# Or manually
sudo apt-get install -y \
    libnss3 \
    libnspr4 \
    libatk1.0-0 \
    libatk-bridge2.0-0 \
    libcups2 \
    libdrm2 \
    libdbus-1-3 \
    libxkbcommon0 \
    libatspi2.0-0 \
    libxcomposite1 \
    libxdamage1 \
    libxfixes3 \
    libxrandr2 \
    libgbm1 \
    libpango-1.0-0 \
    libcairo2 \
    libasound2

5. Configure Environment (Optional)

Create a .env file in the API directory to customize settings:

bash

cd /var/www/flowguard-api
nano .env

Add the following configuration:

env

# Server Configuration
PORT=3000
HOST=localhost
NODE_ENV=production

# Flow Configuration
FLOW_TIMEOUT=300000

Configuration Options:

Variable	Description	Default
`PORT`	Port number for the API server	3000
`HOST`	Hostname to bind to	localhost
`NODE_ENV`	Environment mode	development
`FLOW_TIMEOUT`	Maximum time for flow execution (ms)	300000 (5 min)

6. Start the Server

You have several options for starting the server:

Local API vs Full API

The plugin bundles a minimal Local API that only includes flow execution capabilities. It uses server-local.js as the entry point with fewer dependencies. This is different from the full API which includes monitoring, database, and other features.

Option A: Manual Start (for testing)

bash

cd /var/www/flowguard-api
npm start

Press Ctrl+C to stop the server.

Option B: Background Process with PM2 (Recommended)

PM2 is a production process manager for Node.js applications.

Install PM2 globally:

bash

sudo npm install -g pm2

Start the server with PM2:

bash

cd /var/www/flowguard-api
pm2 start npm --name flowguard-api -- start

Useful PM2 commands:

bash

pm2 status              # Check server status
pm2 logs flowguard-api  # View logs
pm2 restart flowguard-api  # Restart server
pm2 stop flowguard-api  # Stop server
pm2 delete flowguard-api  # Remove from PM2

Make PM2 start on system boot:

bash

pm2 startup
pm2 save

Option C: systemd Service (Linux)

Create a systemd service file:

bash

sudo nano /etc/systemd/system/flowguard-api.service

Add the following configuration:

ini

[Unit]
Description=Flowguard API Server
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/flowguard-api
ExecStart=/usr/bin/npm start
Restart=on-failure
RestartSec=10
Environment=NODE_ENV=production
Environment=PORT=3000

[Install]
WantedBy=multi-user.target

Enable and start the service:

bash

sudo systemctl daemon-reload
sudo systemctl enable flowguard-api
sudo systemctl start flowguard-api

Check status:

bash

sudo systemctl status flowguard-api

View logs:

bash

sudo journalctl -u flowguard-api -f

7. Verify Server is Running

Test the health endpoint:

bash

curl http://localhost:3000/health

You should see a response like:

json

{"status":"ok","timestamp":"2024-12-09T10:30:45.123Z"}

8. Configure WordPress Plugin

Log in to your WordPress admin panel
Navigate to Flowguard > Settings
Click on the Execution tab
Select Local API as the execution mode
Enter the API directory path: /var/www/flowguard-api
Enter the port number: 3000 (or your custom port)
Enter the host: localhost
Click Check Requirements

The system will verify:

Node.js is installed
npm is installed
API directory exists
package.json is valid
All npm packages are installed
Playwright browsers are installed
Local server is running

If all requirements are met, you'll see a success message and can start running flows locally!

Troubleshooting

Server Won't Start

Error: Port 3000 is already in use

Solution: Either stop the other process using port 3000, or change the port in your .env file and WordPress settings.

bash

# Check what's using port 3000
sudo lsof -i :3000

# Use a different port
echo "PORT=3001" >> .env

Browser Launch Fails

Error: browserType.launch: Executable doesn't exist

Solution: Reinstall Playwright browsers:

bash

cd /var/www/flowguard-api
npx playwright install --force
npx playwright install-deps

Permission Errors

Error: EACCES: permission denied

Solution: Ensure the API directory has correct permissions:

bash

sudo chown -R www-data:www-data /var/www/flowguard-api
sudo chmod -R 755 /var/www/flowguard-api

WordPress Can't Connect to Server

Error: Failed to connect to local API server

Solutions:

Verify the server is running:
bash
```
curl http://localhost:3000/health
```
Check firewall settings (server should be accessible from localhost)

Review server logs:

bash

# If using PM2
pm2 logs flowguard-api

# If using systemd
sudo journalctl -u flowguard-api -n 50

Server Crashes During Flow Execution

Cause: Insufficient memory or resources

Solution: Increase memory limits and optimize:

bash

# Increase Node.js memory limit
node --max-old-space-size=4096 src/server.js

# Or in PM2
pm2 start src/server.js --name flowguard-api --max-memory-restart 1G

Security Considerations

Local Network Only

By default, the API server only binds to localhost, meaning it's only accessible from the same machine. This is the recommended configuration.

DANGER

Never expose the API server to the public internet without proper authentication!

Firewall Configuration

If you need to access the API from a different server, use SSH tunneling instead of opening ports:

bash

ssh -L 3000:localhost:3000 user@your-server.com

Process Isolation

Consider running the API server under a dedicated user account with limited permissions:

bash

sudo useradd -r -s /bin/false flowguard
sudo chown -R flowguard:flowguard /var/www/flowguard-api

Update your systemd service or PM2 configuration to use this user.

Performance Optimization

Browser Reuse

The API server reuses browser instances when possible to improve performance. Browser contexts are created fresh for each flow execution.

Concurrent Flows

The server can handle multiple flow executions concurrently. The default limit is based on available system resources.

Resource Cleanup

Failed or cancelled flows automatically clean up their browser resources. The server monitors resource usage and restarts browsers if needed.

Maintenance

Updating the API

When updating Flowguard, you may need to update the API dependencies:

bash

cd /var/www/flowguard-api
npm install
npx playwright install

Then restart the server:

bash

# If using PM2
pm2 restart flowguard-api

# If using systemd
sudo systemctl restart flowguard-api

Log Rotation

Configure log rotation to prevent logs from consuming too much disk space:

bash

# For PM2
pm2 install pm2-logrotate
pm2 set pm2-logrotate:max_size 10M
pm2 set pm2-logrotate:retain 7

Monitoring

Monitor server health and resource usage:

bash

# Check server status
curl http://localhost:3000/health

# Monitor with PM2
pm2 monit

# Check system resources
htop

Settings - Configure execution mode and other settings
Running Flows - Understanding flow execution
REST API - API reference for developers

Local Execution Setup Guide ​

Why Use Local Execution? ​

Prerequisites ​

Step-by-Step Setup ​

1. Install Node.js ​

Ubuntu/Debian ​

CentOS/RHEL ​

macOS (using Homebrew) ​

2. Copy the API Directory ​

3. Install Dependencies ​

4. Install Playwright Browsers ​

5. Configure Environment (Optional) ​

6. Start the Server ​

Option A: Manual Start (for testing) ​

Option B: Background Process with PM2 (Recommended) ​

Option C: systemd Service (Linux) ​

7. Verify Server is Running ​

8. Configure WordPress Plugin ​

Troubleshooting ​

Server Won't Start ​

Browser Launch Fails ​

Permission Errors ​

WordPress Can't Connect to Server ​

Server Crashes During Flow Execution ​

Security Considerations ​

Local Network Only ​

Firewall Configuration ​

Process Isolation ​

Performance Optimization ​

Browser Reuse ​

Concurrent Flows ​

Resource Cleanup ​

Maintenance ​

Updating the API ​

Log Rotation ​

Monitoring ​

Related Documentation ​

Local Execution Setup Guide

Why Use Local Execution?

Prerequisites

Step-by-Step Setup

1. Install Node.js

Ubuntu/Debian

CentOS/RHEL

macOS (using Homebrew)

2. Copy the API Directory

3. Install Dependencies

4. Install Playwright Browsers

5. Configure Environment (Optional)

6. Start the Server

Option A: Manual Start (for testing)

Option B: Background Process with PM2 (Recommended)

Option C: systemd Service (Linux)

7. Verify Server is Running

8. Configure WordPress Plugin

Troubleshooting

Server Won't Start

Browser Launch Fails

Permission Errors

WordPress Can't Connect to Server

Server Crashes During Flow Execution

Security Considerations

Local Network Only

Firewall Configuration

Process Isolation

Performance Optimization

Browser Reuse

Concurrent Flows

Resource Cleanup

Maintenance

Updating the API

Log Rotation

Monitoring

Related Documentation