Flowmaker SDK [beta]Docs
search
GitHub

Create Instance (./fm create)

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

./fm create <name>

Overview

The create command sets up everything needed for a new FlowMaker instance:

  1. Instance directory at deployment/instances/<name>/
  2. .env file generated from template with unique network/domain
  3. docker-compose.override.yml template for customizations
  4. Volume directories for persistent data

Interactive Prompts

Prompt Default Unique? Description
Instance name (required) Yes Instance identifier (folder name)
Docker network name <name>-net Yes Docker network for service isolation
Domain <name>.flowmaker.localhost Yes Base domain for all services
Protocol https No http or https
Docker registry from .env.defaults No Container registry URL
Core version from .env.defaults No FlowMaker core services version

[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 - if a conflict exists, the CLI suggests an alternative.

Examples

Basic Usage

$ ./fm create dev
✓ Created instance at deployment/instances/dev
✓ Environment file: deployment/instances/dev/.env
✓ Override template: deployment/instances/dev/docker-compose.override.yml

ℹ Rebuilding Caddy network config...

Instance 'dev' is ready!

Name Conflict Resolution

$ ./fm create dev
⚠ Value 'dev-net' already exists. Please choose a unique value.
? Docker network name [dev-net-2]:

Generated Files

Instance .env

FM_INSTANCE=dev
FM_NETWORK=dev-net
FM_DOMAIN=dev.flowmaker.localhost
FM_DC_VOLUMEROOT=./instances/dev/volumes
FM_UID=1000
FM_GID=1000
FM_PROTOCOL=https
DOCKER_REGISTRY=ghcr.io/industream
CORE_VERSION=2.1.0
FRONT_VERSION=2.1.0
UIMAKER_VERSION=1.2.21

# Worker versions (uncomment to override defaults)
# WORKER_TIMER_VERSION=2.1.0
# WORKER_HTTP_VERSION=2.1.0

[NOTE!info/WORKER VERSIONS COMMENTED] Worker versions are automatically commented in the .env file. Uncomment to override defaults.

[WARNING!warning/UID/GID CAPTURED] FM_UID and FM_GID are captured at creation time from the current user.

Version Hierarchy

  1. docker-compose.workers.yml - Default versions
  2. Instance .env - Uncommented overrides (highest priority)
# docker-compose.workers.yml
worker-timer:
  image: ${DOCKER_REGISTRY}/flowmaker.boxes/flow-box-timer:${WORKER_TIMER_VERSION:-2.1.0}

# instances/dev/.env
WORKER_TIMER_VERSION=2.1.0  # Override default

Common Workflows

Quick Development Setup

./fm create dev
./fm up dev --workers

Custom Worker Versions

./fm create custom-workers
nano instances/custom-workers/.env

# Uncomment and modify:
WORKER_TIMER_VERSION=2.1.0
WORKER_MQTT_CLIENT_VERSION=3.0.0-beta

Troubleshooting

"Instance already exists" Error

rm -rf instances/<name>
./fm create <name>

Permission Issues on Volumes

sudo chown -R $USER:$USER instances/<name>/volumes

References

  • deployment/fm - cmd_create function
  • deployment/.env.template - Instance .env template
  • Start Instance