Scaffold
Stoobly Scaffold Commands - Questions & Answers for Team Use
Scaffold commands enable Stoobly for team collaboration. The workflow is: create an app, add services, and use the automatically generated record, mock, and test workflows for each service. Custom workflows can be created as needed.
Getting Started with Scaffold
Q: What is scaffolding in Stoobly?
A: Scaffolding creates a structured project setup for team collaboration, with workflows for recording, mocking, and testing HTTP requests across multiple services. The scaffold structure is created under .stoobly/services/ in the current directory.
Example:
# Create a scaffold app (creates .stoobly/services/ in current directory)
stoobly-agent scaffold app create my-app
# Add a service
stoobly-agent scaffold service create apiQ: Why should I use scaffold for team development?
A: Scaffold provides version-controlled configuration, consistent environments across team members, and automated workflow management for recording, mocking, and testing APIs.
Example:
# Team member 1 creates the scaffold
stoobly-agent scaffold app create team-project
# Team member 2 clones and uses it
git clone <repo>
stoobly-agent scaffold workflow up test Q: How do I create a scaffold script for my project?
A: Create a shell script with only the scaffold creation commands (app and services). Include workflow commands as commented examples for reference. The contents of the script will depend on the type of services and workflows.
Example:
Creating an Application
Q: How do I create a new scaffold application?
A: Use scaffold app create with your application name to generate the scaffold structure under .stoobly/services/ in the current directory.
Example:
Q: How do I create a scaffold app in a specific directory?
A: By default, the scaffold is created in the current directory. Use the --app-dir-path option only when you need to specify a different location.
Example:
Q: How do I create a scaffold app with custom ports?
A: Use --proxy-port and --ui-port options to specify custom ports for the proxy and UI.
Example:
Q: How do I create a scaffold app with test framework integrations?
A: Use the --plugin option to include Cypress or Playwright integrations.
Example:
Q: What runtime environments are supported for scaffold apps?
A: Scaffold supports local (default) and Docker runtime environments.
Example:
Q: How do I check whether my app is configured with local or Docker runtime?
A: Check the .stoobly/services/.config.yml file and look for the APP_RUNTIME configuration property to see which runtime is configured.
Example:
The APP_RUNTIME property will indicate whether the app is configured to run with local or Docker.
Q: What files are created when I scaffold an app?
A: Scaffolding creates a .stoobly/services/ directory in the current directory with service definitions and workflow templates.
Example:
Creating Services
Q: How do I add a service to my scaffold app?
A: Use scaffold service create with the service name to add a new service. By default, commands use the current directory. Use --app-dir-path only when you need to specify a different location.
Example:
Q: How do I create a service with a custom hostname?
A: Use the --hostname option to specify a custom hostname for the service.
Example:
Q: How do I create a service that proxies to a service that does not run on localhost?
A: Configure the service using --hostname, --port, and --scheme to define how clients connect to Stoobly. Only use --upstream-hostname, --upstream-port, and --upstream-scheme when the upstream server differs from these values.
Important:
The
--upstream-*options are overrides, not replacements. Always set--hostname,--port, and--schemefirst, then add--upstream-*options only when they differ. If the upstream uses the same port and scheme, do not specify--upstream-portor--upstream-scheme.
Example:
Q: For Docker runtime, how do I create a service that proxies to a service that runs on localhost?
A: Use --hostname, --port, and --scheme to define how clients connect to Stoobly, then add the --local flag. You must specify --upstream-port with a different port than --port, and run your local service on that upstream port.
Important:
--port- The port Stoobly listens on (what clients/tests connect to)--scheme- The scheme Stoobly uses (http or https)--local- Automatically sets--upstream-hostnameto localhost--upstream-port- Required and must be different from--port- This is where your local service runs--upstream-scheme- Optional - Only specify if your local service uses a different scheme than--schemeDo not specify
--upstream-hostnamewhen using--local(it will be ignored)You must run your local service on
--upstream-port, not on--portDifferent types of services have different recommended option configurations, match against the following examples.
Examples:
Q: How do I set the port for a service?
A: Use the --port option to specify the port where Stoobly exposes the service (the port your tests/clients will use). For local services (using --local), you must specify --upstream-port with a different port and run your service on that upstream port.
Key difference:
--port- The port Stoobly listens on (what you connect to in tests) - always required--upstream-port- The port of the actual service Stoobly proxies to - required when using--localand must be different from--port
Example:
Q: How do I control the startup order of services?
A: Use the --priority option (1.0-9.0) where lower values start first.
Example:
Q: How do I create a service with environment variables?
A: Use the --env option (can be used multiple times) to set environment variables.
Example:
Q: How do I create a service with specific workflows?
A: By default, all three workflows (mock, record, test) are created. Use the --workflow option only when you want to create a subset of workflows.
Common pattern: Frontend services that serve static assets typically only need the test workflow, as they don't require recording or mocking. The test workflow serves the built application from fixtures for E2E testing.
Example:
Q: What are the default workflows created for each service?
A: By default, three workflows are created: record (capture requests), mock (serve mocked responses), and test (validate responses).
Example:
Q: How do I set up a frontend service to serve static assets for E2E testing?
A: Frontend services typically only need the test workflow since they serve static assets from fixtures rather than recording or mocking requests. Modify the service's test/init script (located at .stoobly/services/<service-name>/test/init) to copy your built application to the public fixture folder.
Example:
Example init script:
This setup allows your E2E tests to request the application under test from the frontend service, which serves the static assets from the fixtures folder.
Managing Services
Q: How do I list all services in my scaffold app?
A: Use scaffold service list to display all configured services. Run from your app directory, or use --app-dir-path to specify the location.
Example:
Q: How do I view details about a specific service?
A: Use scaffold service show with the service name.
Example:
Q: How do I list services in a specific format?
A: Use the --format option to specify output format (table, json, csv).
Example:
Q: How do I filter services by workflow?
A: Use the --workflow option to filter services by their workflows.
Example:
Q: How do I update a service configuration?
A: Use scaffold service update with the options you want to change.
Example:
Q: How do I rename a service?
A: Use scaffold service update with the --name option.
Example:
Q: How do I delete a service?
A: Use scaffold service delete with the service name.
Example:
Working with Workflows
Q: What workflows are available by default?
A: Three workflows are created by default for each service: record (capture requests), mock (serve mocked responses), and test (validate responses).
Example:
Q: How do I start a workflow?
A: Use scaffold workflow up with the workflow name to start all services in that workflow. Run from your app directory, or use --app-dir-path to specify the location.
Example:
Q: How do I stop a workflow?
A: Use scaffold workflow down with the workflow name to stop all services.
⚠️ IMPORTANT: Always use stoobly-agent scaffold workflow down to stop workflows. DO NOT use Unix commands like pkill, kill, or docker stop - these can leave the system in an inconsistent state.
Example:
Q: How do I view logs from a workflow?
A: Use scaffold workflow logs to display logs from workflow services.
Example:
Q: How do I start a workflow with specific services only?
A: Use the --service option to select which services to run.
Example:
Q: How do I start a workflow in detached mode?
A: Use the --detached flag to run the workflow in the background.
Example:
Q: How do I skip hostname installation prompts?
A: Use the --hostname-install-confirm option to automatically confirm or deny hostname installation.
Example:
Q: How do I skip CA certificate installation prompts?
A: Use the --ca-certs-install-confirm option to automatically confirm or deny CA certificate installation.
Example:
Creating Custom Workflows
Q: How do I create a custom workflow?
A: Use scaffold workflow create with a workflow name and template to create a custom workflow.
Example:
Q: What templates can I use for custom workflows?
A: You can use mock, record, or test as templates for custom workflows.
Example:
Q: How do I create a custom workflow for multiple services?
A: Use multiple --service options to include multiple services in the workflow.
Example:
Q: How do I copy an existing workflow?
A: Use scaffold workflow copy to duplicate a workflow with a new name.
Example:
SSL/TLS Certificate Management
Q: How do I generate SSL certificates for HTTPS services?
A: Use scaffold app mkcert.
Example:
Q: How do I generate certificates for specific services only?
A: Use the --service option with the mkcert command.
Example:
Hostname Management
Q: How do I install hostnames for services?
A: Use scaffold hostname install to add service hostnames to /etc/hosts.
Example:
Q: How do I uninstall hostnames for services?
A: Use scaffold hostname uninstall to remove service hostnames from /etc/hosts.
Example:
Q: How do I manage hostnames for specific services?
A: Use the --service option to target specific services.
Example:
Team Collaboration Workflows
Q: How do I set up a scaffold project for my team?
A: Create the scaffold app, add services, and commit the configuration to version control so team members can use it.
Example:
Q: How do I share recorded requests with my team?
A: Use scenario snapshots to create committable files that can be shared via version control.
Example:
Q: How do I run the same workflow across different environments?
A: Create custom workflows for each environment using templates.
Example:
Quick Reference
Q: What's the complete end-to-end workflow for setting up and using a team project?
A: This is a comprehensive step-by-step guide covering the full workflow from initial setup through running tests and sharing results with your team.
Example:
Last updated
Was this helpful?