Skip to content

Operations

This guide covers installing, upgrading, and managing formae on your system.

Installation

Supported Platforms

formae supports the following platforms:

Operating System Architecture
Linux x86_64
MacOS arm64

Install formae

Run the installation script:

/bin/bash -c "$(curl -fsSL https://hub.platform.engineering/setup/formae.sh)"

This script installs formae to /opt/pel/formae/.

Configure Your PATH

Add formae to your shell's PATH:

For zsh users (macOS default):

echo 'export PATH=/opt/pel/formae/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

For bash users:

echo 'export PATH=/opt/pel/formae/bin:$PATH' >> ~/.profile
source ~/.profile

Verify Installation

Confirm formae is installed correctly:

formae --version

Upgrading

Upgrade to Latest Version

To upgrade formae to the latest version:

formae upgrade

Upgrade or Downgrade to a Specific Version

List all available versions:

formae upgrade list

Install a specific version:

formae upgrade --version ${selected.version.semver}

Replace ${selected.version.semver} with the desired version number (e.g., 0.74.0).

Logging and Observability

Log Files

The formae agent logs to a configured, rotated log file. By default, logs are stored locally for troubleshooting and debugging.

OpenTelemetry Integration

formae supports OpenTelemetry for advanced observability:

  • Logging: Enable structured logging with OpenTelemetry
  • Metrics: Export metrics for collection by your observability platform

For detailed configuration options, see the Configuration documentation.

Security and Networking

Authentication

Basic Authentication

Basic authentication may be configured via plugins section of the formae configuration.

Cli: 

plugins {
  authentication {
    type = "basic"
    username = "myUserName"
    password = "mySecretPass"
  }
}

Agent: 

plugins {
  authentication {
    type = "basic"
    authorizedUsers = new Listing<User> {
      new {
        username = "myUserName"
        // BCrypt salted password hash
        password = "$2y$10$ki1wCrM94EViuTv0dRNEVuP3ujj2/uu2Zh8/FyFvExjZyrsdtr1SS"
      }
      new {
        username = "anotherUserName"
        password = "$2y$10$ki1wCrM94EViuTv0dRNEVuP3ujj2/uu2Zh8/FyFvExjZyrsdtr1SS"
      }
    }
  }
}

These configurations may be combined for single system use.

BCrypt password hashes may be generated utilizing the following command: 

htpasswd -bnBC 10 "" mySuperStrongPassword | tr -d ':'

TLS

Configure TLS for the agent: 

agent {
  server {
    hostname = "myhostname.com"
    tlsCert = "/path/to/myhostname.com.crt"
    tlsKey = "/path/to/myhostname.com.key"
  }
}

Networking

Tailscale (experimental)

The formae agent has experimental support for in process (no tailscale install required) connectivity to your tailscale tailnet. This functionality allows you to easily setup centralized access without complex VPC/VPN setups.

Configure Tailscale: 

plugins {
  network {
    type = "tailscale"
    hostname = "myhostname"
    // set to true for auto tls termination on your tailnet
    tls = true
    authKey = "your-tailscale-authkey"
    // set to associate tags for access control
    advertiseTags {
      "tag:formae"
    }
  }
}