Local

Stoobly Scaffold Local Runtime - Questions & Answers

This document covers local runtime-specific customization options for Stoobly scaffold. For general customization topics, see README.md. For Docker runtime customization, see docker.md.

---

Local Runtime Structure

Q: Which files are created for both Docker and local runtime?

A: Both runtimes create the Makefile, stoobly-ui service, and user-defined service directories.

Example:

# Common to both:
.stoobly/services/
├── Makefile                    # Both
├── stoobly-ui/                 # Both
└── your-service/               # Both

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

A: Docker runtime creates additional core services (build, entrypoint, gateway) for containerized execution, while local runtime creates a simpler structure for native execution.

Example:

# Local runtime - Simplified structure
stoobly-agent scaffold app create my-app --runtime local

# Creates:
# - stoobly-ui/ (UI service)
# - your-services/ (only user services)
# No build/, entrypoint/, or gateway/ directories

Note: With local runtime, your services run natively on your machine rather than in containers. You'll need to configure your applications to use Stoobly's proxy directly.

---

Local Runtime Customization

Q: How do I configure my application to use Stoobly with local runtime?

A: Configure your application to use Stoobly's proxy by setting HTTP_PROXY and HTTPS_PROXY environment variables, or by configuring your application's HTTP client to use the proxy.

Example:

# Set proxy environment variables
export HTTP_PROXY=http://localhost:8080
export HTTPS_PROXY=http://localhost:8080

# Run your application
npm start

Q: How do I add environment variables for local runtime?

A: For local runtime, set environment variables in your shell or use a .env file that your application reads. Unlike Docker runtime, there's no docker-compose.yml to configure.

Example:

# Set environment variables before running
export DATABASE_URL=postgres://localhost/testdb
export API_KEY=test-key-123
export NODE_ENV=test

# Or use a .env file
cat > .env << EOF
DATABASE_URL=postgres://localhost/testdb
API_KEY=test-key-123
NODE_ENV=test
EOF

Q: How do I run tests with local runtime?

A: Run your tests directly with proxy environment variables set, or configure your test framework to use Stoobly's proxy.

Example:

# Set proxy and run tests
export HTTP_PROXY=http://localhost:8080
export HTTPS_PROXY=http://localhost:8080
npx playwright test

# Or configure in your test config
# playwright.config.ts
export default defineConfig({
  use: {
    proxy: {
      server: 'http://localhost:8080',
    },
  },
});

Q: How do I use a custom context directory?

A: Use the --context-dir-path option when running workflow commands to specify a custom Stoobly data directory.

Example:

stoobly-agent scaffold workflow up test --context-dir-path /path/to/custom/.stoobly

Q: How do I run workflows with custom namespaces?

A: Use the --namespace option to specify a custom workflow namespace when running workflow commands.

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:

stoobly-agent scaffold workflow up test --namespace my-custom-namespace

Q: How do I run workflows in dry-run mode?

A: Use the --dry-run flag to see what commands would be executed without running them.

Example:

stoobly-agent scaffold workflow up test --dry-run

---

Advanced Configuration

Q: How do I increase logging verbosity?

A: Use the --log-level option when starting a workflow to set the logging level.

Example:

stoobly-agent scaffold workflow up test --log-level debug

Q: How do I follow workflow logs in real-time?

A: Use the --follow flag with the scaffold workflow logs command to stream logs continuously.

Example:

stoobly-agent scaffold workflow logs record --follow

---

Local Runtime Troubleshooting

Q: How do I verify my local service configuration?

A: Check the service's configure script and run it manually, then verify Stoobly configuration.

Example:

# View service config
cat .stoobly/services/my-service/mock/configure

# Run configure script
bash .stoobly/services/my-service/mock/configure

# Verify Stoobly config
stoobly-agent config dump

Q: Where can I find workflow logs for local runtime?

A: Workflow logs are stored in .stoobly/tmp/<workflow>/logs/, same as Docker runtime.

Example:

# View request logs
cat .stoobly/tmp/mock/logs/requests.json