This document covers Docker-specific runtime options for Stoobly scaffold. For general runtime topics, see README.md. For local runtime, see local.md.
Docker Runtime Overview
Q: What are the benefits of using Docker runtime?
A: Docker provides environment consistency across team members, dependency isolation, easy cleanup, and works the same on all operating systems.
Example:
stoobly-agentscaffoldappcreatemy-app--runtimedocker# All team members get the same environmentmake-f.stoobly/services/.Makefilerecord
Q: What are the requirements for Docker runtime?
A: You need Docker installed and running on your machine. The Docker daemon must be accessible.
Example:
# Verify Docker is installed and runningdocker--versiondockerps# Create Docker-based scaffoldstoobly-agentscaffoldappcreatemy-app--runtimedocker
Q: How do I specify a custom Docker socket path?
A: Use the --docker-socket-path option when creating the app.
Example:
Q: How do Docker-based workflows work?
A: Docker workflows use docker-compose to orchestrate containers for stoobly-agent, your services, and any dependencies, providing complete isolation.
Example:
Q: What files are created when I scaffold an app with Docker runtime?
A: Scaffolding creates a .stoobly/services/ directory in the current directory with Docker configurations, Makefile, service definitions, and workflow templates.
Example:
Q: Can I use Docker runtime on Windows, Mac, and Linux?
A: Yes, Docker runtime works consistently across all platforms as long as Docker Desktop (Windows/Mac) or Docker Engine (Linux) is installed.
Example:
Q: How do I troubleshoot Docker runtime issues?
A: Check Docker is running, verify permissions, and review container logs.
Example:
Docker Workflows
Q: How do I explicitly use Docker runtime for a workflow?
A: Use the Makefile commands, which are configured for Docker execution.
Example:
Q: How do I use Docker runtime?
A: Create the app with --runtime docker and use Makefile commands for workflows.
Example:
Docker Performance
Q: How do I optimize Docker runtime performance?
A: Use local Docker images, enable BuildKit, and allocate sufficient resources to Docker.
Example:
Docker Migration
Q: How do I migrate from local to Docker runtime?
A: Recreate the app with Docker runtime and start using Makefile commands.
Example:
Getting Started with Make Commands
Q: Where is the Makefile located after scaffolding?
A: The Makefile is automatically created at .stoobly/services/.Makefile in your application directory after scaffolding with --runtime docker.
Example:
Q: How do I run make commands from my project root?
A: Use the -f flag to specify the Makefile path, or create a symlink in your project root.
Example:
Recording Workflow
Q: How do I start a recording workflow?
A: Use make record to start the recording workflow, which sets up the proxy to capture HTTP requests.
Example:
Q: How do I stop a recording workflow?
A: Use make record/down to stop and clean up the recording workflow.
Example:
Q: How do I view logs from the recording workflow?
A: Use make record/logs to display logs from all services in the recording workflow.
Example:
Q: How do I list services in the recording workflow?
A: Use make record/services to display all configured services for the recording workflow.
Example:
Q: How do I view the recorded requests report?
A: Use make record/report to display a list of all intercepted and recorded requests.
Example:
Mock Workflow
Q: How do I start a mock workflow?
A: Use make mock to start the mock workflow, which serves mocked responses based on recorded data.
Example:
Q: How do I stop a mock workflow?
A: Use make mock/down to stop and clean up the mock workflow.
Example:
Q: How do I view logs from the mock workflow?
A: Use make mock/logs to display logs from all services in the mock workflow.
Example:
Q: How do I list services in the mock workflow?
A: Use make mock/services to display all configured services for the mock workflow.
Example:
Q: How do I view the mock requests report?
A: Use make mock/report to display a list of all mocked requests.
Example:
Test Workflow
Q: How do I start a test workflow?
A: Use make test to start the test workflow, which runs automated tests against your services.
Example:
Q: How do I stop a test workflow?
A: Use make test/down to stop and clean up the test workflow.
Example:
Q: How do I view logs from the test workflow?
A: Use make test/logs to display logs from all services in the test workflow.
Example:
Q: How do I list services in the test workflow?
A: Use make test/services to display all configured services for the test workflow.
Example:
Q: How do I view the test requests report?
A: Use make test/report to display a list of all test requests and results.
Example:
Scenario Management
Q: How do I create a scenario using make?
A: Use make scenario/create with the name variable to create a new scenario.
Example:
Q: How do I list all scenarios using make?
A: Use make scenario/list to display all available scenarios.
Example:
Q: How do I delete a scenario using make?
A: Use make scenario/delete with the key variable to delete a specific scenario.
Example:
Q: How do I snapshot a scenario using make?
A: Use make scenario/snapshot with the key variable to create committable files for a scenario.
Example:
Q: How do I reset a scenario to its snapshot state?
A: Use make scenario/reset with the key variable to restore a scenario from its snapshot.
Example:
Q: How do I overwrite a scenario using make?
A: Use make scenario/overwrite with the key variable to overwrite an existing scenario.
Example:
Certificate Management
Q: How do I install the CA certificate using make?
A: The CA certificate is automatically installed when you start a workflow, but you can manually trigger it with make ca-cert/install.
Example:
Q: How do I skip the CA certificate installation prompt?
A: Set the STOOBLY_CA_CERTS_INSTALL_CONFIRM environment variable to y before running the workflow.
Example:
Hostname Management
Q: How do I skip the hostname installation prompt?
A: Set the STOOBLY_HOSTNAME_INSTALL_CONFIRM environment variable to y to automatically confirm hostname installation.
Example:
Q: How do I prevent hostname installation?
A: Set the STOOBLY_HOSTNAME_INSTALL_CONFIRM environment variable to n to skip hostname installation.
Example:
Intercept Management
Q: How do I enable intercept mode using make?
A: Use make intercept/enable with an optional scenario_key to enable request interception.
Example:
Q: How do I disable intercept mode using make?
A: Use make intercept/disable to turn off request interception.
Example:
Environment Variables & Configuration
Q: How do I specify a custom application directory?
A: Set the STOOBLY_APP_DIR environment variable to point to your application directory.
Example:
Q: How do I use a custom .env file with workflows?
A: Set the STOOBLY_DOTENV_FILE environment variable to specify your .env file path.
Example:
Q: How do I specify custom CA certificate directory?
A: Set the STOOBLY_CA_CERTS_DIR environment variable to your custom certificate directory.
Example:
Q: How do I pass additional service options to workflows?
A: Set the STOOBLY_WORKFLOW_SERVICE_OPTIONS environment variable with your custom options.
Example:
Q: How do I specify a custom context directory?
A: Set the STOOBLY_CONTEXT_DIR environment variable to your desired context directory.
Example:
Advanced Workflow Options
Q: How do I pass additional options to workflow up commands?
A: Use the options variable to pass extra options to the workflow.
Example:
Q: How do I run a workflow with a custom namespace?
A: Use the namespace variable to specify a custom workflow namespace.
Note: Namespaces are only supported by test workflows and custom workflows based on the test workflow template. Record and mock workflows do not support namespaces.
Example:
Q: How do I filter services when starting a workflow?
A: Set the STOOBLY_WORKFLOW_SERVICE_OPTIONS environment variable to specify which services to include.
Example:
Combining Multiple Environment Variables
Q: How do I run a fully automated workflow without any prompts?
A: Set both hostname and CA certificate confirmation environment variables before running the workflow.
Example:
Q: How do I run a workflow with custom directories and environment?
A: Set multiple environment variables to customize all aspects of the workflow.
Example:
Docker Runtime Troubleshooting
Q: How do I check if stoobly-agent is installed?
A: The Makefile automatically checks and installs stoobly-agent via pipx if needed. You can manually trigger this with make stoobly/install.
Example:
Q: How do I verify Python version compatibility?
A: Use make python/validate to check if you have a compatible Python version (3.10, 3.11, or 3.12).
Example:
Q: What do I do if pipx is not installed?
A: The Makefile automatically installs pipx if it's missing. You can manually trigger this with make pipx/install.
Example:
Q: How do I view what services are configured?
A: Use the workflow-specific services command to list all configured services.
Example:
Q: How do I validate my service configuration?
A: Use scaffold service show to view the current configuration.
Example:
Q: What do I do if a workflow fails to start?
A: Check the logs for errors and verify service configurations.
Example:
Docker Quick Reference
Q: What are the most common make commands I'll use?
A: Here's a quick reference of the most frequently used commands:
Example:
Q: How do I create an alias for easier make command usage?
A: Add an alias to your shell configuration file for convenience.
# Same command works on all platforms
stoobly-agent scaffold app create my-app --runtime docker
make -f .stoobly/services/.Makefile record
# Check Docker status
docker ps
# View workflow logs
make -f .stoobly/services/.Makefile mock/logs
# Check intercepted request logs
make -f .stoobly/services/.Makefile mock/report
# Docker runtime via Makefile
make -f .stoobly/services/.Makefile record
make -f .stoobly/services/.Makefile mock
make -f .stoobly/services/.Makefile test
# App created with Docker runtime
stoobly-agent scaffold app create my-app --runtime docker
make -f .stoobly/services/.Makefile record
# Use local images (faster)
export STOOBLY_IMAGE_USE_LOCAL=1
make -f .stoobly/services/.Makefile record
# Enable Docker BuildKit
export DOCKER_BUILDKIT=1
make -f .stoobly/services/.Makefile record
# Currently using local (default)
# Recreate with Docker runtime
stoobly-agent scaffold app create my-app --runtime docker
# Now use Docker runtime commands
make -f .stoobly/services/.Makefile record
cd /path/to/your-app
ls .stoobly/services/.Makefile
# Option 1: Specify the Makefile path
make -f .stoobly/services/.Makefile record
# Option 2: Create a symlink (one-time setup)
ln -s .stoobly/services/.Makefile Makefile
make record
make -f .stoobly/services/.Makefile record
make -f .stoobly/services/.Makefile record/down
make -f .stoobly/services/.Makefile record/logs
make -f .stoobly/services/.Makefile record/services
make -f .stoobly/services/.Makefile record/report
make -f .stoobly/services/.Makefile mock
make -f .stoobly/services/.Makefile mock/down
make -f .stoobly/services/.Makefile mock/logs
make -f .stoobly/services/.Makefile mock/services
make -f .stoobly/services/.Makefile mock/report
make -f .stoobly/services/.Makefile test
make -f .stoobly/services/.Makefile test/down
make -f .stoobly/services/.Makefile test/logs
make -f .stoobly/services/.Makefile test/services
make -f .stoobly/services/.Makefile test/report
make -f .stoobly/services/.Makefile scenario/create name="User Login Flow"
make -f .stoobly/services/.Makefile scenario/list
make -f .stoobly/services/.Makefile scenario/delete key=<SCENARIO-KEY>
make -f .stoobly/services/.Makefile scenario/snapshot key=<SCENARIO-KEY>
make -f .stoobly/services/.Makefile scenario/reset key=<SCENARIO-KEY>
make -f .stoobly/services/.Makefile scenario/overwrite key=<SCENARIO-KEY>
make -f .stoobly/services/.Makefile ca-cert/install
export STOOBLY_CA_CERTS_INSTALL_CONFIRM=y
make -f .stoobly/services/.Makefile record
export STOOBLY_HOSTNAME_INSTALL_CONFIRM=y
make -f .stoobly/services/.Makefile record
export STOOBLY_HOSTNAME_INSTALL_CONFIRM=n
make -f .stoobly/services/.Makefile mock
make -f .stoobly/services/.Makefile intercept/enable scenario_key=<SCENARIO-KEY>
make -f .stoobly/services/.Makefile intercept/disable
export STOOBLY_APP_DIR=/path/to/my-app
make -f .stoobly/services/.Makefile record
export STOOBLY_DOTENV_FILE=/path/to/custom.env
make -f .stoobly/services/.Makefile mock
export STOOBLY_CA_CERTS_DIR=/path/to/certs
make -f .stoobly/services/.Makefile record
export STOOBLY_WORKFLOW_SERVICE_OPTIONS="--service api --service database"
make -f .stoobly/services/.Makefile record
export STOOBLY_CONTEXT_DIR=/path/to/context
make -f .stoobly/services/.Makefile test
make -f .stoobly/services/.Makefile record options="--detach"
make -f .stoobly/services/.Makefile test namespace=my-custom-namespace
export STOOBLY_WORKFLOW_SERVICE_OPTIONS="--service api --service frontend"
make -f .stoobly/services/.Makefile mock
export STOOBLY_HOSTNAME_INSTALL_CONFIRM=y
export STOOBLY_CA_CERTS_INSTALL_CONFIRM=y
make -f .stoobly/services/.Makefile record
make -f .stoobly/services/.Makefile stoobly/install
make -f .stoobly/services/.Makefile python/validate
make -f .stoobly/services/.Makefile pipx/install
make -f .stoobly/services/.Makefile record/services
make -f .stoobly/services/.Makefile mock/services
make -f .stoobly/services/.Makefile test/services
stoobly-agent scaffold service show api
# View logs
make -f .stoobly/services/.Makefile record/logs
# Verify services
make -f .stoobly/services/.Makefile record/services
# Check Docker containers
docker ps
# Start workflows
make -f .stoobly/services/.Makefile record # Start recording
make -f .stoobly/services/.Makefile mock # Start mocking
make -f .stoobly/services/.Makefile test # Start testing
# Stop workflows
make -f .stoobly/services/.Makefile record/down
make -f .stoobly/services/.Makefile mock/down
make -f .stoobly/services/.Makefile test/down
# View logs
make -f .stoobly/services/.Makefile record/logs
make -f .stoobly/services/.Makefile mock/logs
make -f .stoobly/services/.Makefile test/logs
# Manage scenarios
make -f .stoobly/services/.Makefile scenario/list
make -f .stoobly/services/.Makefile scenario/create name="My Scenario"
make -f .stoobly/services/.Makefile scenario/snapshot key=<SCENARIO-KEY>
# View reports
make -f .stoobly/services/.Makefile record/report
make -f .stoobly/services/.Makefile mock/report
# Add to ~/.bashrc or ~/.zshrc
alias smake='make -f .stoobly/services/.Makefile'
# Then use it like:
smake record
smake mock/down
smake scenario/list
