Scaffold

Background

Without scaffold, setting up Stoobly to record and mock requests involves three core challenges:

• Service orchestration

  • Configure Stoobly to intercept traffic for multiple services

  • Dynamically generate SSL certificates

  • Support customization through adding user-defined services

• Consistent ease-of-use across team members

  • Stoobly version management

  • Automated onboarding

  • Opinionated process for recoding, mocking, and testing

• Separating configuration for different workflows e.g. development and CI

  • Defining a consistent file structure across workflows

  • Scoping container to specific workflows

  • Namespacing containers to enable the same workflow to run multiple times

To solve these challenges, scaffold provides a framework to define services and customize workflows.

What is Scaffold?

Scaffold is implemented as a CLI command to offer an out-of-the-box solution to build a containerized solution to record, mock, and test your applications. These workflows can be easily integrated into CI pipelines and test environments without needing to spend extra development time orchestrating a test setup.

With scaffold, we take an opinionated approach:

• Use Docker Compose to declaratively define all the services and networking configuration

• Automatically run Stoobly maintained services for the user such as 1 Stoobly UI, a stoobly-agent proxy per service, and a "Gateway" that intelligently routes requests to the correct service

• Use CLI commands to make it easy to add new services

• Allow configuration to be provided in specific files with a consistent experience

As a result, we can enforce best practices and make it easy to run dozens of services in complex setups. There are also opinionated ways of running services and configuring everything correctly for different use-cases such as recording requests, mocking requests, or for a CI pipeline with end-to-end tests.

Terminology

Application

An application represents a source-controlled code repository that depends on one or more services.

Networks

The following networks are created when running a workflow. When defining custom container services, they may need to belong in either (but not both) of the following networks:

• app.ingress - container services that need to reference a service by hostname.

• app.egress - container services that need to access or be accessed by service containers.

Service

A service represents an application dependency. The service is often, but not necessary responds to HTTP(s) requests. HTTP(s) services can be either:

A "local" service is one that is defined by the user and runs as a Docker container on the user's local environment or machine. The user is expected to provide the Docker Compose specification. These are services that your team owns.

An "external" service is one that isn't ran by the user directly such as services and APIs provided by other teams or third-party ones such as payment processors and other APIs. The user is expected to provide the hostname to this service's API.

Core Services

Core services are automatically created as part of a scaffolded application. These include:

• stoobly-agent proxies - a proxy will be created per service

• A Stoobly UI - a single UI that can access your mock data across services

• Gateway - intelligently routes requests to the correct service

Core services or their configurations should not be modified.

Workflow

A workflow belongs to a service and captures a specific use-case for it. Use cases include, but are not limited to recording, mocking, and testing requests.

When creating a service, the following workflows can be added:

• mock - used for mocking requests

• record - used for recording requests

• test - used for running a scaffolded application in CI or testing environments

Custom Workflow

These are custom workflows defined by the user.

Next steps

How to Scaffold an App