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 --app-dir-path ./team-project

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
cd my-app

# 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 record/logs

# Check Docker compose status
docker-compose -f .stoobly/services/record/.docker-compose.yml ps

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 --app-dir-path ./my-app

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 --app-dir-path ./my-app

# Or use the Makefile
make -f .stoobly/services/.Makefile 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 \
  --app-dir-path ./my-app

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

# Start stoobly workflow locally
stoobly-agent scaffold workflow up record --app-dir-path ./my-app

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 \
  --app-dir-path ./my-app

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 --app-dir-path ./my-app

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 --app-dir-path ./my-app

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

# Or use local runtime (same configuration)
stoobly-agent scaffold workflow up record --app-dir-path ./my-app

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 --app-dir-path ./my-app
stoobly-agent scaffold workflow up mock --app-dir-path ./my-app
stoobly-agent scaffold workflow up test --app-dir-path ./my-app

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 --app-dir-path ./my-app

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 --app-dir-path ./my-app
# ~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 --app-dir-path ./my-app

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 --app-dir-path ./team-project

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

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 --app-dir-path ./team-project

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 \
  --app-dir-path ./team-project

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 \
  --app-dir-path ./my-app

# Run tests
npm test

# Cleanup
stoobly-agent scaffold workflow down test --app-dir-path ./my-app

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 --app-dir-path .
          npm test
          stoobly-agent scaffold workflow down test --app-dir-path .

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 --app-dir-path ./my-app

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 --app-dir-path ./my-app

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 --app-dir-path ./team-project
stoobly-agent scaffold service create frontend --hostname frontend.local --app-dir-path ./team-project

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

This comprehensive guide covers all aspects of choosing and using Docker vs local runtime options for Stoobly scaffold, helping teams make informed decisions based on their needs.
PreviousMakefileNextInstalling the Agent

Last updated

Was this helpful?