Docker
Stoobly Scaffold Docker Runtime - Questions & Answers
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-agent scaffold app create my-app --runtime docker
# All team members get the same environment
make -f .stoobly/services/.Makefile recordQ: 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 running
docker --version
docker ps
# Create Docker-based scaffold
stoobly-agent scaffold app create my-app --runtime dockerQ: 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.
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.
Example:
Last updated
Was this helpful?