Run On

Stoobly Scaffold Runtime Options - Questions & Answers

The --run-on option when creating a scaffold app determines whether workflows run locally on your machine or in Docker containers. This provides flexibility for different development environments and team preferences.

Understanding Runtime Options

Q: What runtime options are available for scaffold apps?

A: Scaffold supports two runtime options: docker (containerized execution) and local (native execution on your machine). You can configure one or both.

Example:

# Docker only (default)
stoobly-agent scaffold app create my-app --run-on docker

# Local only
stoobly-agent scaffold app create my-app --run-on local

# Both Docker and local
stoobly-agent scaffold app create my-app --run-on docker --run-on local

Q: What's the difference between Docker and local runtime?

A: Docker runtime runs workflows in isolated containers with consistent environments, while local runtime executes workflows directly on your machine using your installed Python and dependencies.

Example:

# Docker: Isolated, consistent, requires Docker installed
stoobly-agent scaffold app create my-app --run-on docker

# Local: Uses your machine's Python, faster startup, no Docker needed
stoobly-agent scaffold app create my-app --run-on local

Q: Which runtime option should I choose?

A: Use Docker for team consistency and isolation, or local for faster iteration and simpler setup. You can enable both to support different team member preferences.

Example:

# For teams: Enable both options
stoobly-agent scaffold app create team-project --run-on docker --run-on local

# Team members can then choose:
# Docker user: make -f .stoobly/services/.Makefile record
# Local user: stoobly-agent scaffold workflow up record

Docker Runtime

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 --run-on docker

# All team members get the same environment
make -f .stoobly/services/.Makefile record

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 running
docker --version
docker ps

# Create Docker-based scaffold
stoobly-agent scaffold app create my-app --run-on docker

Q: How do I specify a custom Docker socket path?

A: Use the --docker-socket-path option when creating the app.

Example:

stoobly-agent scaffold app create my-app \
  --run-on docker \
  --docker-socket-path /var/run/docker.sock

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:

# Create Docker-based app
stoobly-agent scaffold app create my-app --run-on docker

# Start workflow (runs in containers)
make -f .stoobly/services/.Makefile record

# View running containers
docker ps

# Stop workflow (cleans up containers)
make -f .stoobly/services/.Makefile record/down

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:

# Same command works on all platforms
stoobly-agent scaffold app create my-app --run-on docker
make -f .stoobly/services/.Makefile record

Q: How do I troubleshoot Docker runtime issues?

A: Check Docker is running, verify permissions, and review container logs.

Example:

# 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

Local Runtime

Q: What are the benefits of using local runtime?

A: Local runtime offers faster startup times, simpler debugging, direct access to your filesystem, and no Docker dependency.

Example:

stoobly-agent scaffold app create my-app --run-on local

# Faster startup, no container overhead
stoobly-agent scaffold workflow up record

Q: What are the requirements for local runtime?

A: You need Python 3.10, 3.11, or 3.12 installed, and stoobly-agent installed via pipx.

Example:

# Verify Python version
python3 --version  # Should be 3.10, 3.11, or 3.12

# Install stoobly-agent
pipx install stoobly-agent

# Create local runtime scaffold
stoobly-agent scaffold app create my-app --run-on local

Q: How do local workflows work?

A: Local workflows run stoobly-agent directly on your machine, proxying requests to your services without containerization.

Example:

# Create local runtime app
stoobly-agent scaffold app create my-app --run-on local

# Start workflow (runs locally)
stoobly-agent scaffold workflow up record

Q: Can I use local runtime if my services are in Docker?

A: Yes, local runtime only affects how stoobly-agent runs. Your services can still run in Docker containers.

Example:

# Stoobly runs locally, services in Docker
stoobly-agent scaffold app create my-app --run-on local

# Add service that runs in Docker
stoobly-agent scaffold service create api \
  --hostname api.local \
  --upstream-hostname localhost \
  --upstream-port 8080

# Start your service in Docker
docker run -p 8080:8080 my-api-image

# Start stoobly workflow locally
stoobly-agent scaffold workflow up record

Q: How do I troubleshoot local runtime issues?

A: Check Python version, verify stoobly-agent installation, and review logs.

Example:

# Check Python version
python3 --version

# Verify stoobly-agent
stoobly-agent --version

# Check logs with verbose output
stoobly-agent scaffold workflow up record \
  --log-level debug

Supporting Both Runtimes

Q: Why would I enable both Docker and local runtimes?

A: Enabling both allows team members to choose their preferred runtime based on their environment, while maintaining compatibility.

Example:

# Enable both runtimes
stoobly-agent scaffold app create my-app --run-on docker --run-on local

# Team member A uses Docker
make -f .stoobly/services/.Makefile record

# Team member B uses local
stoobly-agent scaffold workflow up record

Q: How do I create a scaffold that supports both runtimes?

A: Specify both --run-on docker and --run-on local when creating the app.

Example:

stoobly-agent scaffold app create team-project \
  --run-on docker \
  --run-on local \
  --proxy-port 8080 \
  --ui-port 4200

Q: Do both runtimes use the same configuration?

A: Yes, both runtimes share the same service configurations, workflows, and recorded data.

Example:

# Create app with both runtimes
stoobly-agent scaffold app create my-app --run-on docker --run-on local

# Add service (works for both)
stoobly-agent scaffold service create api --hostname api.local

# Use Docker runtime
make -f .stoobly/services/.Makefile record

# Or use local runtime (same configuration)
stoobly-agent scaffold workflow up record

Q: Can I switch between Docker and local runtime after creating the app?

A: Yes, you can manually update the app configuration or recreate the app with different runtime options.

Example:

# Initially created with Docker only
stoobly-agent scaffold app create my-app --run-on docker

# Later, recreate to add local support
stoobly-agent scaffold app create my-app --run-on docker --run-on local
# (This updates the configuration without deleting data)

Runtime-Specific Workflows

Q: How do I explicitly use Docker runtime for a workflow?

A: Use the Makefile commands, which are configured for Docker execution.

Example:

# Docker runtime via Makefile
make -f .stoobly/services/.Makefile record
make -f .stoobly/services/.Makefile mock
make -f .stoobly/services/.Makefile test

Q: How do I explicitly use local runtime for a workflow?

A: Use the stoobly-agent scaffold workflow commands directly.

Example:

# Local runtime via CLI
stoobly-agent scaffold workflow up record
stoobly-agent scaffold workflow up mock
stoobly-agent scaffold workflow up test

Q: How do I force a specific runtime when both are configured?

A: The Makefile uses Docker by default. For local, use the CLI commands directly.

Example:

# App supports both runtimes
stoobly-agent scaffold app create my-app --run-on docker --run-on local

# Force Docker
make -f .stoobly/services/.Makefile record

# Force local
stoobly-agent scaffold workflow up record

Performance Considerations

Q: Which runtime is faster for development?

A: Local runtime typically has faster startup times, while Docker provides better isolation and consistency.

Example:

# Local: Faster startup
time stoobly-agent scaffold workflow up record
# ~2-5 seconds

# Docker: Slower startup but isolated
time make -f .stoobly/services/.Makefile record
# ~10-30 seconds (first time, includes image pull)

Q: Does Docker runtime use more resources?

A: Yes, Docker adds overhead for containerization, but provides better isolation and cleanup.

Example:

# Docker: More memory/CPU but isolated
make -f .stoobly/services/.Makefile record
docker stats  # View resource usage

# Local: Less overhead but shares system resources
stoobly-agent scaffold workflow up record

Q: How do I optimize Docker runtime performance?

A: Use local Docker images, enable BuildKit, and allocate sufficient resources to Docker.

Example:

# 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

Team Collaboration with Different Runtimes

Q: How do I set up a project that works for team members with different preferences?

A: Enable both runtimes and document both approaches in your README.

Example:

# Project setup (team lead)
stoobly-agent scaffold app create team-project --run-on docker --run-on local
stoobly-agent scaffold service create api --hostname api.local

# Document in README:
# Docker users: make -f .stoobly/services/.Makefile record
# Local users: stoobly-agent scaffold workflow up record

Q: How do I ensure consistency when team members use different runtimes?

A: Use the same service configurations and share recorded data via version control.

Example:

# Both runtimes share the same data
git add .stoobly/
git commit -m "Add scaffold configuration and snapshots"

# Team member A (Docker)
git pull
make -f .stoobly/services/.Makefile mock

# Team member B (Local)
git pull
stoobly-agent scaffold workflow up mock

Q: Can Docker and local users work on the same project simultaneously?

A: Yes, but they should use different workflow namespaces to avoid conflicts.

Example:

# Docker user
make -f .stoobly/services/.Makefile record namespace=docker-dev

# Local user (different machine or namespace)
stoobly-agent scaffold workflow up record \
  --namespace local-dev

CI/CD with Runtime Options

Q: Which runtime should I use in CI/CD?

A: Docker is recommended for CI/CD as it provides consistent, isolated environments.

Example:

#!/bin/bash
# CI/CD script with Docker runtime
export STOOBLY_HOSTNAME_INSTALL_CONFIRM=y
export STOOBLY_CA_CERTS_INSTALL_CONFIRM=y

# Use Docker runtime
make -f .stoobly/services/.Makefile test

# Run tests
npm test

# Cleanup
make -f .stoobly/services/.Makefile test/down

Q: Can I use local runtime in CI/CD?

A: Yes, if your CI environment has Python and stoobly-agent installed, local runtime can be faster.

Example:

#!/bin/bash
# CI/CD script with local runtime

# Install dependencies
pipx install stoobly-agent

# Use local runtime
stoobly-agent scaffold workflow up test \
  --ca-certs-install-confirm y \
  --hostname-install-confirm y

# Run tests
npm test

# Cleanup
stoobly-agent scaffold workflow down test

Q: How do I test both runtimes in CI/CD?

A: Create separate CI jobs for Docker and local runtimes.

Example:

# .github/workflows/test.yml
name: Test Both Runtimes

jobs:
  test-docker:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Test with Docker
        run: |
          make -f .stoobly/services/.Makefile test
          npm test
          make -f .stoobly/services/.Makefile test/down

  test-local:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install stoobly-agent
        run: pipx install stoobly-agent
      - name: Test with Local
        run: |
          stoobly-agent scaffold workflow up test --ca-certs-install-confirm y
          npm test
          stoobly-agent scaffold workflow down test

Migration Between Runtimes

Q: How do I migrate from Docker to local runtime?

A: Update the app configuration to include local runtime and use CLI commands instead of Makefile.

Example:

# Currently using Docker only
# Update to support both
stoobly-agent scaffold app create my-app --run-on docker --run-on local

# Switch to using local runtime
stoobly-agent scaffold workflow up record

Q: How do I migrate from local to Docker runtime?

A: Update the app configuration to include Docker runtime and start using Makefile commands.

Example:

# Currently using local only
# Update to support both
stoobly-agent scaffold app create my-app --run-on docker --run-on local

# Switch to using Docker runtime
make -f .stoobly/services/.Makefile record

Q: Will my recorded data work with both runtimes?

A: Yes, recorded data is stored in .stoobly/ and works with both runtimes.

Example:

# Record with Docker
make -f .stoobly/services/.Makefile record
# ... make requests ...
make -f .stoobly/services/.Makefile record/down

# Mock with local (uses same data)
stoobly-agent scaffold workflow up mock

Quick Reference

Q: What's a quick comparison of Docker vs Local runtime?

A: Here's a side-by-side comparison:

Docker Runtime:

✅ Consistent across all environments
✅ Complete isolation
✅ Easy cleanup
✅ Works on Windows, Mac, Linux
❌ Slower startup
❌ Requires Docker installed
❌ More resource usage

Local Runtime:

✅ Faster startup
✅ Simpler debugging
✅ Less resource usage
✅ No Docker required
❌ Requires Python 3.10+
❌ Less isolation
❌ Environment differences possible

Example:

# Choose based on your needs:

# Team consistency & isolation → Docker
stoobly-agent scaffold app create my-app --run-on docker

# Speed & simplicity → Local
stoobly-agent scaffold app create my-app --run-on local

# Flexibility → Both
stoobly-agent scaffold app create my-app --run-on docker --run-on local

Q: What's the recommended setup for a new team project?

A: Enable both runtimes to support different team member preferences and environments.

Example:

# Recommended team setup
stoobly-agent scaffold app create team-project \
  --run-on docker \
  --run-on local \
  --plugin cypress \
  --proxy-port 8080 \
  --ui-port 4200

# Add services
stoobly-agent scaffold service create api --hostname api.local
stoobly-agent scaffold service create frontend --hostname frontend.local

# Document both approaches in README
# Docker: make -f .stoobly/services/.Makefile record
# Local: stoobly-agent scaffold workflow up record

PreviousMakefile NextCustomization

Last updated 20 hours ago

Was this helpful?