Quick Start

This guide will get you started on using Terrabuild. For this, you are invited to clone the playground repository. You just need Terrabuild and Docker to go through this guide.

The playground repository defines following projects and dependencies:

flowchart LR
  classDef default fill:moccasin,stroke:black
  classDef project fill:gainsboro,stroke:black,rx:10,ry:10
  classDef build fill:palegreen,stroke:black,rx:20,ry:20
  classDef publish fill:skyblue,stroke:black,rx:20,ry:20
  classDef target fill:white,stroke-width:2px,stroke-dasharray: 5 2

  subgraph A[".net WebApi"]
    subgraph targetBuildA["target build"]
      direction LR
      buildA(["@dotnet build"])
    end

    subgraph targetBuildA["target build"]
      direction LR
      buildA(["@dotnet build"])
    end

    subgraph targetPublishA["target dist"]
      direction LR
      publishA(["@dotnet publish"]) --> dockerA(["@docker build"])
    end

    class targetBuildA build
    class targetPublishA publish
  end

  subgraph B["Vue.js WebApp"]
    subgraph targetBuildB["target build"]
      direction LR
      publishB(["@npm build"])
    end

    subgraph targetPublishB["target dist"]
      direction LR
      dockerB(["@docker build"])
    end

    class targetBuildB build
    class targetPublishB publish
  end

  subgraph C[".net Library"]
    subgraph targetBuildC["target build"]
      direction LR
      buildC(["@dotnet build"])
    end

    class targetBuildC build
  end

  subgraph D["Typescript Library"]
    subgraph targetBuildD["target build"]
      direction LR
      buildD(["@npm build"])
    end

    class targetBuildD build
  end

  publish([dist])
  targetBuildB --> targetBuildD
  targetBuildA --> targetBuildC
  targetPublishA --> targetBuildA
  publish -.-> targetPublishA
  
  targetPublishB --> targetBuildB
  publish -.-> targetPublishB

  class A,B,C,D project
  class publish target

Building

We want to be able to build artifacts for the whole workspace (a part of a monorepo configured for Terrabuild). For this, just issue the following command wherever you are in your workspace:

terrabuild run dist

Terrabuild will resolve all nodes dependencies, reuse build outputs from cache if available - and complete as fast as possible with a mix of task optimizations, caching and parallel builds! If a file is modified, Terrabuild will only rebuild impacted projects leading to very efficient workflow for developers.

Configuration

This can be implemented using following configurations:

# require all dependencies to be built before building this target
target build {
    depends_on = [ target.^build ]
}

# dist requires project to be built before proceeding
target dist {
    depends_on = [ target.build ]
}

# default variables for targets
variable config {
    description = "configuration to build"
    default = "Debug"
}

# .net sdk version is forced and build is happening in a container
# no need to install .net sdk on developer machines
# also the default values define the target configuration
extension @dotnet {
    container = "mcr.microsoft.com/dotnet/sdk:8.0"
    defaults {
        configuration = var.config
    }
}

# nodejs version is forced and build is happening in a container
# no need to install nodejs on developer machines
extension @npm {
    container = "node:22"
}

# terraform version is forced and build is happening in a container
# no need to install terraform on developer machines
extension @terraform {
    container = "hashicorp/terraform:1.12"
}

# configure docker extension (see Dockerfile for ARG)
extension @docker {
    defaults {
        image = "ghcr.io/magnusopera/sample/webapi"
        arguments = { configuration: var.config }
    }
}

# project is based on .net: dependency on src/libs/cslib is detected automatically
# also defines labels for scoped builds
project {
    labels = [ "app" "dotnet" ]
    @dotnet { }
}

target build {
    @dotnet build { }
}

# to build docker image we need to publish the .net project
# and then build the image on top of this (check Dockerfile)
# Docker is targetting linux/x64
target dist {
    @dotnet publish { runtime = "linux-x64" }
    @docker build { platform = "linux/amd64" }
}

extension @docker {
    defaults {
        image = "ghcr.io/magnusopera/sample/webapp"
        arguments = { configuration: var.config }
    }
}

# project is based on nodejs: dependency on src/libs/tslib is detected automatically.
# As an example, it is forced here but not mandatory.
project {
    labels = [ "app" "web" ]
    dependencies = [ "../../libs/tslib" ]
    @npm { }
}

target build {
    @npm build { }
}

target dist {
    @docker build { }
}

project {
    labels = [ "lib" ]
    @dotnet { }
}

target build {
    @dotnet build
}

project {
    labels = [ "lib" ]
    @npm { }
}

target build {
    @npm build
}

Caching

When you are ready to enable caching, add the block workspace in your WORKSPACE file:

workspace {
    id = "5db875fc-0b0c-4b98-a7e7-dbf5eafeaceb"
}

Do not forget to connect to your workspace to enable caching. You will need to generate a token on your account:

terrabuild login --space 5db875fc-0b0c-4b98-a7e7-dbf5eafeaceb --token <token>