Skip to content
flowctl

Getting Started

Flowctl uses PostgreSQL as its database. This is the only external dependency. Everything else is included in the binary.

Quick Start

Section titled “Quick Start”

For a quick setup, you can use the provided docker-compose.yml file. Alternatively, you can set up flowctl manually with the following steps.

  1. Download the binary

    Download the latest release for your platform from GitHub Releases.

  2. Start PostgreSQL

    If you have Docker installed:

    Terminal window
    docker run -d \
      --name flowctl-postgres \
      -e POSTGRES_USER=flowctl \
      -e POSTGRES_PASSWORD=flowctl \
      -e POSTGRES_DB=flowctl \
      -p 5432:5432 \
      postgres:17-alpine

  3. Configure flowctl

    Terminal window
    flowctl --new-config

    This will generate a default config.toml file in the current directory. Customize it if required. Create the flows directory as specified in flows_directory in config.toml.

  4. DB migration

    Terminal window
    flowctl install

    This will perform DB migrations. It is safe to run this multiple times.

  5. Start flowctl

    Terminal window
    flowctl start

    This will start the server and the background workers. The application will be available at http://localhost:7000. This will use the config.toml in the current working directory by default. You can pass --config flag to use a different config.

  6. Login

    Use the admin credentials you configured in config.toml.

Configuration

Section titled “Configuration”

The config.toml file controls all aspects of flowctl’s behavior. Here’s a comprehensive guide to the available settings:

Application Settings

Section titled “Application Settings”
[app]
  admin_username = "flowctl_admin"
  admin_password = "your_secure_password"
  flows_directory = "flows"
  root_url = "http://localhost:7000"
  use_tls = false
  http_tls_cert = "server_cert.pem"
  http_tls_key = "server_key.pem"
  secure_cookie_key = "base64_encoded_key"
  • admin_username / admin_password: Credentials for the admin user account. Change the default password for security.
  • root_url: The base URL where flowctl is accessible. Update this if running behind a proxy or on a different port.
  • flows_directory: Directory path where flow definitions are stored. Can be relative or absolute.
  • use_tls: Enable HTTPS (default: false). Set to true for production deployments.
  • http_tls_cert / http_tls_key: Paths to TLS certificate and key files when use_tls is enabled.
  • secure_cookie_key: Base64-encoded key for encrypting session cookies. This is used by the simplessions package to create a secure cookie. Valid key lengths are 16, 24, or 32 bytes to select AES-128, AES-192, or AES-256. Config generated by --new-config creates a random 16 byte key.

Database Settings

Section titled “Database Settings”
[db]
  host = "127.0.0.1"
  port = 5432
  dbname = "flowctl"
  user = "flowctl"
  password = "flowctl"
  • host: PostgreSQL server hostname or IP address
  • port: PostgreSQL server port (default: 5432)
  • dbname: Name of the database to use
  • user / password: Database authentication credentials

Keystore Configuration

Section titled “Keystore Configuration”
[app.keystore]
  keeper_url = "base64key://..."

The keystore manages encryption keys for sensitive data. The keeper_url uses a URI scheme to specify the storage backend. This uses the gocloud package which supports multiple KMS backends. The default config uses a local encryption key.

Scheduler Settings

Section titled “Scheduler Settings”
[app.scheduler]
  backend = ""
  workers = 20
  cron_sync_interval = "5m0s"
  • backend: Scheduler backend type. Leave empty to use the default postgres backend (only available backend currently).
  • workers: Number of concurrent workers for executing flows (default: number of CPU threads)
  • cron_sync_interval: How often to sync scheduled flows from the database (default: 5m0s)

Logger Configuration

Section titled “Logger Configuration”
[app.logger]
  backend = "file"
  log_directory = "/var/log/flowctl"
  max_size_bytes = 0
  retention_time = 0
  scan_interval = "1h"
  • log_directory: Directory for log files when using file backend. This directory should exist.
  • max_size_bytes: Maximum size per log file in bytes (0 = unlimited)
  • retention_time: How long to keep log files in hours (0 = unlimited)
  • scan_interval: Interval between scans for the log manager to delete / manage logs

OIDC Authentication

Section titled “OIDC Authentication”
[app.oidc]
  client_id = "your-client-id"
  client_secret = "your-client-secret"
  issuer = "https://your-oidc-provider.com/"

Configure OpenID Connect for single sign-on:

  • client_id: OAuth2 client ID from your OIDC provider
  • client_secret: OAuth2 client secret
  • issuer: OIDC provider’s issuer URL

Next Steps

Section titled “Next Steps”