Skip to main content

Getting Started

The Runs Service is a gRPC-based service (using buf connect) that manages workflow runs, actions, and execution states. It supports both SQLite for local development and PostgreSQL for production environments.

Prerequisites​

Before you begin, ensure you have the following installed:

  • Go: Version 1.26.3 or later
  • Make: For running build and test automation
  • PostgreSQL 15+: (Optional) Required for production-like setups
  • Buf CLI: (Optional) For protocol buffer linting and generation

Installation​

The Runs Service is located in the runs/ directory of the Flyte repository.

  1. Clone the repository:

    git clone https://github.com/flyteorg/flyte.git
    cd flyte/runs

  2. Build the service:

    go build -o runs-service cmd/main.go

Hello World / Quick Start​

1. Start the Service​

The service uses SQLite by default and will automatically create a runs.db file in the current directory.

./runs-service --config config.yaml

2. Create a Run (Go Client)​

Create a file named hello_run.go to interact with the service:

package main

import (
	"context"
	"fmt"
	"log"
	"net/http"

	"connectrpc.com/connect"
	"github.com/flyteorg/flyte/v2/gen/go/flyteidl2/common"
	"github.com/flyteorg/flyte/v2/gen/go/flyteidl2/core"
	"github.com/flyteorg/flyte/v2/gen/go/flyteidl2/task"
	"github.com/flyteorg/flyte/v2/gen/go/flyteidl2/workflow"
	"github.com/flyteorg/flyte/v2/gen/go/flyteidl2/workflow/workflowconnect"
)

func main() {
	// Initialize the Connect client
	client := workflowconnect.NewRunServiceClient(
		http.DefaultClient,
		"http://localhost:8090",
	)

	// Define a simple container task run
	req := &workflow.CreateRunRequest{
		Id: &workflow.CreateRunRequest_RunId{
			RunId: &common.RunIdentifier{
				Org:     "flyte",
				Project: "examples",
				Domain:  "development",
				Name:    "hello-world-run",
			},
		},
		Task: &workflow.CreateRunRequest_TaskSpec{
			TaskSpec: &task.TaskSpec{
				TaskTemplate: &core.TaskTemplate{
					Target: &core.TaskTemplate_Container{
						Container: &core.Container{
							Image: "alpine",
							Args:  []string{"echo", "Hello from Runs Service!"},
						},
					},
				},
			},
		},
	}

	// Execute the request
	resp, err := client.CreateRun(context.Background(), connect.NewRequest(req))
	if err != nil {
		log.Fatalf("Failed to create run: %v", err)
	}

	fmt.Printf("Successfully created run: %s\n", resp.Msg.Run.Action.Id.Run.Name)
}

Run the client:

go run hello_run.go

Configuration​

The service is configured via YAML files. Two templates are provided:

SQLite (Default)​

Edit config.yaml for local development:

runs:
  server:
    port: 8090
database:
  sqlite:
    file: "./runs.db"

PostgreSQL​

Edit config-postgres.yaml for production:

database:
  postgres:
    host: "localhost"
    port: 5433
    dbname: "flyte_runs"
    username: "postgres"
    password: "postgres"
    extraOptions: "sslmode=disable"

Verify Installation​

Confirm the service is healthy by querying the health endpoint:

curl http://localhost:8090/healthz

You can also run the built-in integration tests:

make integration-test

Other Install Options​

Docker Compose​

Run the service along with a PostgreSQL database using Docker:

cd runs
docker compose up --build

Manual PostgreSQL Setup​

If you prefer to run PostgreSQL manually:

docker run --name flyte-runs-postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=flyte_runs \
  -p 5433:5432 \
  -d postgres:15

./runs-service --config config-postgres.yaml

Next Steps​

Troubleshooting​

  • Port 8090 already in use: Change the port value in your config.yaml.
  • Database connection failed:
    • For SQLite, ensure the directory is writable.
    • For PostgreSQL, verify the container is running: docker ps.
  • Missing generated code: If you modify .proto files, run make buf from the repository root to regenerate Go bindings.