Introduction

Operations and platform teams today are struggling with the immense and growing complexity of their infrastructure. Despite using IaC tools, they are constantly fighting a losing battle against infrastructure drift, undocumented changes, and the operational challenges that come from relying on multiple tools and sources of truth.

That’s where formae comes in. It’s an Infrastructure-as-Code (IaC) platform that unifies your live environment into a single, versioned system of record, giving you the power to safely manage and evolve it with code. It automatically discovers and tracks new resources and changes across your infrastructure, regardless of their origin. formae versions every change in its internal state and makes your infrastructure accessible as code at any level of granularity—always up to date.

Getting started

Get up and running with formae in under 15 minutes. This guide will walk you through installing formae, configuring your environment, and managing your first infrastructure.

Prerequisites

Before you begin, ensure you have:

  • A Unix-based operating system (macOS or Linux)
  • A working account and access to the cloud provider supported by formae
  • Basic familiarity with command-line tools
  • (Optional) A code editor with Pkl support for the best development experience

Estimated time: 15 minutes

Step 1: Install formae

Download and install formae using our installation script:

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

This script will install formae to /opt/pel/formae/ and make the CLI tools available on your system.

Step 2: Configure shell PATH

Add formae to your shell's PATH so you can run commands from anywhere:

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 the installation:

formae --version

You should see the formae version number displayed.

Step 3: Choose an example to begin with

Go to /opt/pel/formae/examples/ and choose and example for the cloud you want to work with.

Step 4: Start the formae agent

The formae agent manages infrastructure operations and state synchronization. Start it in a terminal window:

formae agent start

The agent will run in the foreground and display a message indicating it has started successfully. Keep this terminal open and use a separate terminal for the next steps.

Step 5: Apply your first forma

In a new terminal window, provision the infrastructure defined in the example you chose:

cd /opt/pel/formae/examples/<CLOUD YOU CHOSE>/<EXAMPLE YOU CHOSE>
formae apply --mode reconcile --watch <THE MAIN ENTRY POINT OF THE EXAMPLE - SEE README>

When you run an apply command, formae executes it asynchronously on the agent. The --watch flag allows you to track live updates on the progress of your forma command. You can safely exit the watch at any time (Ctrl+C) - the operation will continue running on the agent in the background.

Expected output:

You'll see live updates on the infrastructure provisioning progress as formae creates the resource, including the command ID, status, and elapsed time.

Note: The --mode parameter is mandatory. We'll explore different apply modes in detail in the Workflows section.

Step 6: Verify your deployment

Verify in your cloud account using its web console or any other tool you prefer if the resources declared in the example of your choice have been created.

formae inventory:

Check that formae has the resource under management:

formae inventory resources

This command lists all resources currently managed by formae.

Step 7: Clean up resources

To avoid unnecessary charges, let's clean up the resources we created. Use the destroy command to delete resources you created during this quick start:

formae destroy --watch <THE MAIN ENTRY POINT OF THE EXAMPLE - SEE README>

The destroy command removes all resources defined in the specified forma file. The --watch flag allows you to monitor the deletion progress in real-time.

Expected output:

You'll see live updates as formae removes the resources, including the command ID, status, and elapsed time.

What's next?

Now that you have formae up and running, explore these topics:

Want to learn more? Check out our Architecture guide to understand how formae works under the hood.