Guide

Getting Started with Fabric

Install Fabric and run your first geospatial processing pipeline in under 10 minutes.

Beginner 10 min

What is Fabric?

Fabric is a command-line tool for managing containerized geospatial data processing workflows. It provides workspace management, reproducible pipeline execution, and Docker-based task orchestration.

Key Features:

  • Workspace isolation - Keep projects organized with isolated environments
  • YAML-based pipelines - Define complex multi-task workflows declaratively
  • Docker-powered tasks - Reproducible execution anywhere Docker runs
  • Expression language - Dynamic parameter passing between tasks

Prerequisites

Before installing Fabric, ensure you have:

  • Docker Desktop installed and running
  • macOS, Linux, or Windows with WSL2
  • At least 8GB RAM available for Docker

Installation

Using Homebrew (macOS)

brew tap m33/fabric
brew install fabric

Using Go

go install github.com/m33/fabric@latest

Linux / WSL

curl -fsSL https://get.fabric.m33.io | bash

Verify Installation

Run the doctor command to check your system:

fabric --version
fabric doctor

The fabric doctor command checks Docker connectivity and available resources. You should see output like:

fabric version 1.0.0

System Check:
  Docker: OK (running)
  Memory: OK (16GB available)
  Disk:   OK (45GB free)

Quick Start

1. Initialize a Workspace

Create a new workspace for your project:

fabric workspace init my-first-project
fabric workspace use my-first-project

This creates a .fabricrc configuration file and isolated environment.

2. Check Available Tasks

List the built-in tasks available:

fabric task list

3. Create Your First Pipeline

Create a file called hello.yaml:

name: hello-fabric
description: A simple test pipeline

inputs:
    message:
        type: string
        default: "Hello from Fabric!"

tasks:
    greet:
        image: alpine:latest
        image_args:
            - echo
            - "{{ pipeline.inputs.message }}"

4. Run the Pipeline

fabric run hello.yaml

You should see:

Running pipeline: hello-fabric
Task [greet] starting...
Hello from Fabric!
Task [greet] completed in 1.2s
Pipeline completed successfully!

Running Real-World Pipelines

Fabric comes with pre-built pipelines for geospatial processing. Try the forest monitoring pipeline:

# Pull the required task images
fabric image pull forest-indices
fabric image pull sentinel2-download

# Run forest monitoring on a study area
fabric run forest-monitoring \
  --input-study-area "Black Forest, Germany" \
  --output ./results/

Workspace Management

Fabric uses workspaces to isolate projects:

# List all workspaces
fabric workspace list

# Switch between workspaces
fabric workspace use another-project

# See current workspace
fabric workspace current

# Delete a workspace
fabric workspace delete old-project

Next Steps

Now that you have Fabric running, explore these guides:

Explore our pattern library:

Troubleshooting

Docker not found

Make sure Docker Desktop is running:

docker info

If Docker isn't found, install it from docker.com.

Permission denied

On Linux, you may need to add your user to the docker group:

sudo usermod -aG docker $USER
# Log out and back in for changes to take effect

Task image not found

Pull the required images before running:

fabric image pull <task-name>

Getting Help