Local Development 🛠️

Test your Graph Compose workflows against your local services using ngrok tunnels!

What is ngrok? 🤔

ngrok is a powerful tool that creates secure tunnels between your local machine and the internet. When you're developing Graph Compose workflows that need to interact with your services, ngrok acts as a bridge that allows our cloud-based orchestration service to communicate with your local development environment.

Why Do We Need It? 🎯

When you're developing workflows with Graph Compose:

• Your services run locally (like http://localhost:3000)
• Graph Compose runs in the cloud and can't directly access your localhost
• You want to test workflows against your development version before deploying
• You need to debug and monitor the requests from Graph Compose to your service

ngrok solves these problems by creating a public URL that forwards Graph Compose's requests to your local server.

How Does It Work? 🔄

Here's how ngrok helps with Graph Compose workflow development:

1. You run your service locally (e.g., on port 3000)
2. ngrok creates a tunnel connecting your local port to their servers
3. You get a public URL (like https://abc123.ngrok.io)
4. When Graph Compose sends a request to this URL, ngrok forwards it to your local server
5. Your local server processes the request and responds, just like it would in production

Getting Started ✨

Let's walk through setting up ngrok step by step. Each step builds on the previous one, so make sure to follow them in order.

1. Install ngrok

First, install ngrok using one of these methods. Choose the method that matches your operating system:

# Mac (using Homebrew)
brew install ngrok

# npm (global install - requires Node.js)
npm install ngrok -g

# Debian/Ubuntu Linux
curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc | \
  sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null && \
  echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | \
  sudo tee /etc/apt/sources.list.d/ngrok.list && \
  sudo apt update && sudo apt install ngrok

# Windows (using Chocolatey package manager)
choco install ngrok

Don't have these package managers? No worries! You can also download ngrok directly from ngrok.com.

After installation, verify everything is working:

ngrok --version  # Should show the installed version number

2. Connect Your Account 🔑

ngrok requires a free account to work. This helps secure your tunnels and gives you access to the dashboard. Here's what to do:

1. Sign up for a free account at ngrok.com
2. After signing in, find your authtoken in the dashboard
3. Connect your local ngrok agent with this command:

ngrok config add-authtoken your-authtoken-here  # Replace with your actual token

3. Start Your Local Server 🏃‍♂️

Before creating a tunnel, you need a local server running. This is the server you want to make accessible to the internet:

# Example: Running on port 3000
npm run dev  # Or whatever command starts your local server

Make sure your server is running and accessible at http://localhost:3000 (or whatever port you're using) before proceeding.

4. Create a Tunnel 🚇

Now for the magic part! We'll create a tunnel that connects your local server to the internet. Here are different ways to do it:

# Basic tunnel - simplest way to start
ngrok http 3000  # Replace 3000 with your server's port number

# With inspection enabled - helps you see incoming requests
ngrok http --inspect 3000

# Using a custom domain (requires paid account)
# This gives you a consistent URL instead of a random one
ngrok http --domain=your-domain.ngrok.io 3000

When the tunnel starts, you'll see something like this:

Session Status                online
Account                       you@example.com
Version                       3.5.0
Region                        United States (us)
Forwarding                    https://abc123.ngrok.io -> http://localhost:3000

The Forwarding line shows your public URL (https://abc123.ngrok.io). Anyone can use this URL to access your local server!

Testing Your Workflow 🧪

Now that your local service is accessible to Graph Compose, you can test your workflows against it. Here's how to create and execute a workflow using either our Node.js SDK or the REST API:

import { GraphCompose } from '@graph-compose/sdk'

const client = new GraphCompose()

// Example: Testing a workflow that processes user data
const workflow = graph
  .node("process_user")
    .post("https://abc123.ngrok.io/api/users")  // Your local user service
    .withBody({
      name: "{{ context.name }}",
      email: "{{ context.email }}"
    })
  .end()
  
  .node("enrich_data")
    .post("https://abc123.ngrok.io/api/enrich")  // Your local enrichment service
    .withBody({
      userId: "{{ results.process_user.id }}",
      metadata: "{{ results.process_user.metadata }}"
    })
    .withDependencies(["process_user"])
  .end()
  
  .node("send_welcome")
    .post("https://abc123.ngrok.io/api/notifications")  // Your local notification service
    .withBody({
      userId: "{{ results.process_user.id }}",
      template: "welcome",
      data: "{{ results.enrich_data }}"
    })
    .withDependencies(["enrich_data"])
  .end();

// Execute the workflow
const result = await workflow.execute({
  name: "John Doe",
  email: "john@example.com",
  webhookUrl: "https://abc123.ngrok.io/webhook"  // For receiving workflow status updates
});

Common Development Scenarios 🎯

Here are some typical ways to use ngrok with Graph Compose:

1. Testing New Services

   • Develop your service locally
   • Expose it via ngrok
   • Create a workflow using the ngrok URL
   • Test and debug before deploying

2. Modifying Existing Services

   • Run the service locally with your changes
   • Use ngrok to expose it
   • Point your workflow to the ngrok URL instead of production
   • Verify your changes work as expected

3. Webhook Development

   • Create your webhook endpoint locally
   • Use ngrok to make it accessible
   • Configure Graph Compose to send webhooks to your ngrok URL
   • Monitor and debug incoming webhooks in real-time

Pro Tips 💡

Here are some advanced tips to make your development experience even better:

• 🔒 Use ngrok http --inspect to see all traffic in real-time (great for debugging webhooks!)
• 🔄 Keep ngrok running in a separate terminal or use tmux/screen (so it doesn't stop when you're working on code)
• 📝 Save ngrok URLs in your environment variables (makes it easier to update when they change)
• 🎯 Use the web interface at http://localhost:4040 to inspect requests (it's like Chrome DevTools for your tunnel)
• ⚡ Set up persistent URLs with a paid ngrok account (no more updating URLs every time)
• 🔐 Use environment variables for sensitive auth tokens (never commit them to code)
• 📡 Monitor your tunnels in the ngrok dashboard (see all active tunnels in one place)

Debugging with ngrok 🔍

One of ngrok's most powerful features is its debugging capabilities. Here's what you can do:

• 🔍 Inspect HTTP traffic in real-time (see exactly what's being sent/received)
• 🔄 Replay requests for testing (perfect for debugging webhooks)
• 🚨 View detailed error messages and stack traces (find problems quickly)
• 📊 Monitor request/response data and headers (make sure everything's correct)
• ⏱️ Check request timing and performance (optimize your endpoints)
• 📱 Test webhooks from external services (they can reach your localhost!)
• 🌐 Simulate different network conditions (test how your app behaves with slow connections)

Running ngrok Persistently 🔁

For continuous workflow development, you might want ngrok to run continuously. Here are your options:

• 🐳 Docker container: docker run -it -p 4040:4040 ngrok/ngrok http 3000
• 🔄 Linux systemd service: Run as a background service that starts with your system
• 🪟 Windows service: Run as a Windows background service
• 📦 Terminal multiplexer: Use tmux/screen to keep ngrok running in the background

Ready to test your Graph Compose workflows locally? Let's go! 🚀