FlowMaker Deployment CLI (`./deployment/fm`)

The fm CLI manages multi-instance FlowMaker deployments with Caddy reverse proxy support.

Location: deployment/fm (1721 lines of bash)

Quick Start

# 1. Start Caddy (shared reverse proxy)
./fm caddy:rebuild

# 2. Create an instance (interactive)
./fm create dev

# 3. Start the instance
./fm up dev --workers

# 4. Trust the CA certificate (one-time)
./fm caddy:ca
sudo trust anchor ~/caddy-root-ca.crt  # Arch Linux
# OR
sudo cp ~/caddy-root-ca.crt /usr/local/share/ca-certificates/caddy-local.crt && sudo update-ca-certificates  # Debian/Ubuntu

Access your instance at https://frontend.dev.flowmaker.localhost

Instance Management
Worker Development
Caddy Management
CDN Operations
Initialization & Sync
Architecture
Configuration
Services
HTTPS & Certificates
Troubleshooting

Instance Management

Create Instance

./fm create <name>

Creates a new instance with isolated Docker network, domain, and persistent storage.

[NOTE!lightbulb/WORKER VERSION INFERENCE] Worker versions are automatically inferred from docker-compose.workers.yml at creation time.

[WARNING!warning/UNIQUENESS ENFORCEMENT] Network and domain uniqueness is enforced - conflicts trigger automatic suggestions.

See Create Instance for details.

Start Instance

./fm up <name> [--workers] [--local]

Starts an instance with optional worker services.

[WARNING!warning/WORKERS NOT INCLUDED BY DEFAULT] Worker services are not started unless you use --workers.

See Start Instance for details.

Stop Instance

./fm down <name>

Stops all services for an instance.

[WARNING!error/DATA PERSISTS] This command stops but does not remove containers or volumes. Data persists.

See Stop Instance for details.

List Instances

./fm list

Shows all instances with domain, network, and status.

Example:

NAME            DOMAIN                      NETWORK       STATUS
----            ------                      -------       ------
dev             dev.flowmaker.localhost     dev-net       running
staging         staging.flowmaker.localhost staging-net   stopped

Instance Status

./fm ps <name>

List containers for an instance with IP addresses and status.

See Instance Status for details.

View Logs

./fm logs <name> [service]

View logs for an instance or specific service.

[NOTE!info/FOLLOW MODE] Logs are shown in follow mode by default. Press Ctrl+C to stop.

See View Logs for details.

Delete Instance

./fm delete <name>

⚠️ WARNING: Permanently removes an instance and all its data.

Worker Development

Launch Local Worker

./fm launch-worker <instance> [options] <worker-name> [process-command...]

Run a worker process from your local repository against a running instance.

Options:

--id <worker-id> - Custom worker ID
--port <port> - ZMQ port to bind
--flowmaker-workers-path=<path> - Path to worker-cli root

[NOTE!lightbulb/LOCAL DEVELOPMENT WORKFLOW] Develop workers in your IDE with hot-reload - no Docker image rebuilds needed.

[WARNING!warning/INSTANCE MUST BE RUNNING] The instance must be running for service IP resolution.

[WARNING!error/STALE CONFIG FORM] Frontend rebuild uploads the latest config form. Without rebuilding, you serve a stale config form.

Saving Defaults: Create deployment/.env:

FLOWMAKER_WORKERS_PATH=/path/to/worker-cli
LAUNCH_WORKER_DEFAULT_PROCESS=npx tsx src/index.ts

Then:

./fm launch-worker v2 timer

See Launch Local Worker for details.

Multi-Language Support:

TypeScript: ./fm launch-worker v2 timer npx tsx src/index.ts
Python: ./fm launch-worker v2 ml-workers python -m src
C#: ./fm launch-worker v2 plc-workers dotnet run

Caddy Management

Caddy is the shared reverse proxy for all instances.

Commands

Command	Description
`./fm caddy:rebuild`	Regenerate network config and restart Caddy
`./fm caddy:stop`	Stop Caddy
`./fm caddy:delete`	Stop and remove all data (CA, volumes)
`./fm caddy:logs`	View Caddy logs
`./fm caddy:ca [dest]`	Export CA certificate (default: ~/caddy-root-ca.crt)

[NOTE!info/AUTO NETWORK DISCOVERY] Caddy config is auto-generated from all instance .env files.

See Caddy Management for details.

CDN Operations

Reset CDN Seed Flag

./fm cdn-reset <instance> [worker-name]

Resets CDN seed flag for workers, triggering re-seed on restart.

See CDN Operations for details.

Initialization & Sync

Initialize Instance

./fm init <instance>

Sets up environment config and creates default scheduler in ConfigHub.

[WARNING!error/INSTANCE MUST BE RUNNING] ConfigHub must be accessible for initialization.

[NOTE!lightbulb/RANDOM SCHEDULER COLOR] Scheduler is created with a random pastel color for UI identification.

See Initialization & Sync for details.

Sync Versions

./fm sync <instance>

Syncs instance versions from release-tracker.

Architecture

./
├── .env.defaults                     # Shared defaults
├── .env.template                     # Instance .env template
├── docker-compose.yml                # Core services
├── docker-compose.workers.yml        # Worker services
├── docker-compose.infra.yml          # Caddy base config
├── docker-compose.infra.override.yml # Generated: instance networks
├── fm                                # CLI
├── volumes/caddy/                    # Caddy data & CA
└── instances/
    └── <name>/
        ├── .env                      # Instance config
        ├── docker-compose.override.yml
        └── volumes/                  # Instance data

Network Isolation

Each instance runs on its own Docker network:

dev → dev-net → *.dev.flowmaker.localhost
staging → staging-net → *.staging.flowmaker.localhost

[NOTE!info/CADDY ROUTING] Caddy attaches to all instance networks and routes traffic by hostname.

Configuration

Environment Files

File	Purpose
`.env.defaults`	Project-wide defaults
`.env.template`	Instance .env template
`instances/<name>/.env`	Instance-specific config
`instances/<name>/docker-compose.override.yml`	Custom overrides

Instance Overrides

services:
  worker-timer:
    image: ${DOCKER_REGISTRY}/flowmaker.boxes/flow-box-timer:custom-tag

  flowmaker-scheduler:
    environment:
      - FM_DEBUG=true
      - FM_LOG_LEVEL=debug

[NOTE!info/VERSION HIERARCHY]

.env.defaults - Project defaults

Instance .env - Instance overrides

docker-compose.workers.yml - Worker version defaults

Services

Core Services

Service	Caddy Route
etcd	-
etcd-browser	`etcd.<domain>`
flowmaker-scheduler	-
flowmaker-confighub	`confighub.<domain>`
flowmaker-logging	`logger.<domain>`
flowmaker-frontend	`frontend.<domain>`

Workers (`--workers`)

Worker versions from docker-compose.workers.yml:

WORKER_TIMER_VERSION=2.1.0
WORKER_HTTP_CLIENT_VERSION=2.1.0

HTTPS & Certificates

Caddy auto-generates certificates with built-in local CA.

Trust the CA

./fm caddy:ca

# Arch Linux
sudo trust anchor ~/caddy-root-ca.crt

# Debian/Ubuntu
sudo cp ~/caddy-root-ca.crt /usr/local/share/ca-certificates/caddy-local.crt
sudo update-ca-certificates

# macOS
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ~/caddy-root-ca.crt

Firefox: Settings → Privacy & Security → Certificates → View Certificates → Authorities → Import

Troubleshooting

DNS not resolving *.localhost

# Add to /etc/hosts
127.0.0.1 frontend.dev.flowmaker.localhost confighub.dev.flowmaker.localhost

Permission denied on volumes

sudo chown -R $USER:$USER ./instances/*/volumes

Caddy not routing

./fm list - Ensure instance running
./fm caddy:rebuild - Rebuild config
./fm caddy:logs - Check logs

Worker connection issues

Check worker logs: ./fm logs dev worker-timer
Verify scheduler running: ./fm ps dev | grep scheduler
Check ZMQ port: ss -tlnH | grep 5570

Direct Port Mode (No Caddy)

docker compose -p fm-dev \
  --env-file .env.defaults \
  --env-file ./instances/dev/.env \
  -f docker-compose.yml \
  -f docker-compose.ports.yml \
  up -d

Service	URL
Frontend	http://localhost:3030
ConfigHub	http://localhost:4000
Logger	http://localhost:3040

References

deployment/README.md - Full deployment documentation
deployment/fm - CLI source code
deployment/docker-compose.yml - Core services
deployment/docker-compose.workers.yml - Worker services

FlowMaker Deployment CLI (./deployment/fm)