Scaffold

Background

Before Scaffold existed, integrating a few services with Stoobly was easy and straightforward for most people. However for complex setups involving dozens of services that were or weren't owned by the user, it became difficult to integrate and manage. As the number of services increased so do did the operational complexity. There came a variety of challenges that users had to face.

First, there was a loose structure and no best practices enforced, which was fine when there were only a handful of services. Several questions arose:

• Should services be ran on the host as processes? Or as Docker containers?

• How do you mock third-party services or ones ran by other teams?

• What's the best way to provide TLS certificates, request data, assets, etc.?

There were also many difficulties figuring out the networking:

• How many stoobly-agent proxies should be ran? 1 for the whole system? 1 per service?

• How do you configure the proxies so API requests get routed to a service correctly?

• Which stoobly-agent should the Stoobly UI connect to and how?

As a result, there came a need for a way to bootstrap a complete setup with best practices enforced. This resulted in scaffold as a framework to provide a consistent experience for integrating and managing services with Stoobly.

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 to run everything as containers

• 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

Next let's define some terminology

Application

An application (or app) is a complete software system that includes 1 or more services.

When using scaffold, you must first create an "application"

Service

A service is a piece of software that runs such as a backend web server that handles HTTP requests

When using scaffold, 1 application must have 1 or more services

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.

Managed Service

A managed service is a service that is 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

Users should not be modifying managed services or their configurations!

The scaffold commands will automatically do that for you

Workflow

A workflow is a Stoobly use-case such as recording requests or mocking them.

Several workflows are included:

• mock - for mocking requests

• record - for recording requests

• test - 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