Temporal Local Development Environment

Production-ready setup for developing Temporal workflows locally with Python, including HTTP API support and example workflows.

🚀 Quick Start

# 1. Initialize (one time)
./init.sh

# 2. Run example workflow
./scripts/run.sh examples/hello_activity_choice.py

# 3. Access Temporal UI
open http://localhost:8080

---

📁 Project Structure

temporal-official/
├── api/              # HTTP API (FastAPI server, worker, client)
├── examples/         # Example workflows (4 examples)
├── workflows/        # Your custom workflows (add here)
├── scripts/          # Helper scripts (run, start, stop, test, check)
├── config/           # Docker configurations
├── docs/             # Documentation
├── init.sh           # One-time setup script
└── requirements.txt  # Python dependencies

---

📦 Prerequisites

• Docker & Docker Compose - For Temporal server
• Python 3.8+ - For workflows
• Git - For version control

---

🔧 Installation

# Run initialization script
./init.sh

This will:

• Create Python virtual environment
• Install dependencies
• Start Docker services
• Verify everything works

---

🎯 Usage

Running Workflows Directly

# Run any workflow
./scripts/run.sh examples/hello_activity_choice.py
./scripts/run.sh examples/my_first_workflow.py "World" "false"
./scripts/run.sh examples/hello_activity_retry.py
./scripts/run.sh examples/hello_continue_as_new.py

How it works:

• Script connects directly to Temporal server
• Creates worker inline
• Executes workflow
• Returns result
• No separate services needed

Using HTTP API

# Start API + Worker services
./scripts/start_api_services.sh

# Trigger via HTTP
curl -X POST http://localhost:8000/workflows/shopping \
  -H "Content-Type: application/json" \
  -d '{"items":[{"fruit":"APPLE","amount":5}]}'

# Or use Python client
python api/example_api_client.py

# Stop services
./scripts/stop_api_services.sh

How it works:

• Worker runs continuously in background
• API server accepts HTTP requests
• Workflows triggered via REST API
• Useful for production/microservices

Check Status

./scripts/check_services.sh

---

🌐 Access Points

Service	URL	Purpose
Temporal UI	http://localhost:8080	Monitor workflows
API Server	http://localhost:8000	Trigger workflows via HTTP
API Docs	http://localhost:8000/docs	Interactive API documentation
gRPC	localhost:7233	Direct Temporal connection

---

🛠️ Development

Create Your Workflow

1. Create file in workflows/:

# workflows/my_workflow.py
from temporalio import workflow, activity
from datetime import timedelta

@activity.defn
async def my_activity(data: str) -> str:
    return f"Processed: {data}"

@workflow.defn
class MyWorkflow:
    @workflow.run
    async def run(self, input: str) -> str:
        result = await workflow.execute_activity(
            my_activity,
            input,
            start_to_close_timeout=timedelta(seconds=10),
        )
        return result

2. Run it:

./scripts/run.sh workflows/my_workflow.py

Add Dependencies

# Add to requirements.txt
echo "package-name==version" >> requirements.txt

# Install
source .venv/bin/activate
pip install -r requirements.txt

---

📚 Documentation

• docs/DEVELOPMENT.md - Workflow development & helper scripts
• docs/API.md - Complete HTTP API guide

---

🔍 Common Commands

Service Management

# Check status
./scripts/check_services.sh

# Start Docker
docker compose -f config/docker-compose.yml up -d

# Stop Docker
docker compose -f config/docker-compose.yml down

# View logs
docker compose -f config/docker-compose.yml logs -f

Workflow Execution

# Direct execution (development)
./scripts/run.sh examples/hello_activity_choice.py

# Via API (production-like)
./scripts/start_api_services.sh
./scripts/test_api.sh
./scripts/stop_api_services.sh

---

🐛 Troubleshooting

Services Won't Start

# Check status
./scripts/check_services.sh

# Restart Docker
docker compose -f config/docker-compose.yml restart

Import Errors

# Reinstall dependencies
rm -rf .venv
./init.sh

Port Conflicts

# Check what's using port
lsof -i :8000

# Kill process
kill $(lsof -ti:8000)

---

💡 Two Ways to Run Workflows

1. Direct Execution (Development)

./scripts/run.sh examples/hello_activity_choice.py

Pros:

• ✅ Simple and fast
• ✅ No background services
• ✅ Self-contained
• ✅ Great for testing

How it works:

• Script creates its own worker
• Connects directly to Temporal
• Executes and exits

2. API Services (Production)

./scripts/start_api_services.sh
curl -X POST http://localhost:8000/workflows/shopping ...

Pros:

• ✅ Trigger from any language
• ✅ Long-running workers
• ✅ HTTP integration
• ✅ Microservices ready

How it works:

• Worker runs continuously
• API accepts HTTP requests
• Workflows queued and processed

---

📖 Resources

• Temporal Documentation: https://docs.temporal.io/
• Python SDK Docs: https://docs.temporal.io/dev-guide/python
• Python SDK API: https://python.temporal.io/
• Community Slack: https://temporal.io/slack

---

✅ Quick Reference

# Setup (one time)
./init.sh

# Check status
./scripts/check_services.sh

# Run workflow
./scripts/run.sh examples/hello_activity_choice.py

# Start API
./scripts/start_api_services.sh

# Test API
./scripts/test_api.sh

# Stop API
./scripts/stop_api_services.sh

# Docker commands
docker compose -f config/docker-compose.yml up -d    # Start
docker compose -f config/docker-compose.yml ps       # Status
docker compose -f config/docker-compose.yml down     # Stop

---

🎉 Ready to build workflows with Temporal!

For detailed guides, see:

• Development Guide - Workflows & scripts
• API Guide - HTTP API details