Skip to content

Local Development

This guide covers the local development workflow for digitalNXT Agency.

Development Workflow

Starting Development

After completing the installation and setup:

# Activate virtual environment
source .venv/bin/activate  # On Windows: .\.venv\Scripts\activate

When you specify the created .venv as Python interpreter for this project in Visual Studio Code this environment is used throughout your code and activated automatically in your terminal as well.

Development Environment Stack

The Agency framework includes a comprehensive development stack with Temporal, Langfuse, and OpenTelemetry for local development.

🚀 Quick Start

# Start the complete development environment
just dev-start

# Open development UIs in browser
just dev-ui

# Start a worker to process Temporal workflows
just worker

📦 Development Services

Service URL Purpose
Langfuse UI http://localhost:3000 LLM observability and tracing
Temporal Web UI http://localhost:8080 Workflow orchestration monitoring
Temporal Server localhost:7233 Workflow execution engine
OpenTelemetry Collector localhost:4317/4318 Distributed tracing collection
PostgreSQL (Langfuse) localhost:5432 Langfuse data persistence
PostgreSQL (Temporal) localhost:5433 Temporal data persistence

🔐 Default Credentials

Langfuse Local Development:

  • URL: http://localhost:3000
  • Email: admin@langfuse.local
  • Password: password
  • Public Key: pk-lf-1234567890abcdef
  • Secret Key: sk-lf-1234567890abcdef1234567890abcdef

Just Commands Reference

🚀 Development Environment Commands

# Start complete development stack (Langfuse + Temporal + OpenTelemetry)
just dev-start

# Stop all development services
just dev-stop

# View logs from all services
just dev-logs

# View logs from specific service (langfuse, temporal, temporal-postgres, etc.)
just dev-logs-service langfuse

# Check status of all services
just dev-status

# Clean up all services and data (⚠️  destructive)
just dev-clean

# Open development UIs in browser
just dev-ui

👷 Worker Commands

# Start Temporal worker to process workflows
just worker

# Start Streamlit app with worker (interactive development)
just streamlit

# Stop worker processes
just worker-stop

🛠️ Development Tools

# View all available commands
just --list

# Install dependencies
just install

# Run linting and formatting (ruff check + format)
just lint-format

# Run tests with coverage reporting
just test

# Start documentation server
just docs

# Build documentation for production
just docs-build

# Sort imports in a specific file
just sort-imports path/to/file.py

Docker Compose Setup

The development environment uses Docker Compose to orchestrate multiple services:

🐳 Service Architecture

graph TB
    subgraph "Client Applications"
        Streamlit[Streamlit App<br/>:8501]
        Worker[Temporal Worker<br/>Python Process]
    end

    subgraph "Development UIs"
        LangfuseUI[Langfuse UI<br/>:3000]
        TemporalUI[Temporal Web UI<br/>:8080]
    end

    subgraph "Core Services"
        Temporal[Temporal Server<br/>:7233]
        LangfuseServer[Langfuse Server<br/>:3000]
        OTelCollector[OpenTelemetry Collector<br/>:4317/:4318]
    end

    subgraph "Data Persistence"
        LangfuseDB[PostgreSQL Langfuse<br/>:5432]
        TemporalDB[PostgreSQL Temporal<br/>:5433]
        Redis[Redis<br/>:6379]
        ClickHouse[ClickHouse<br/>:8123/:9000]
        MinIO[MinIO S3<br/>:9010]
    end

    Worker --> Temporal
    Streamlit --> Worker

    LangfuseUI --> LangfuseServer
    TemporalUI --> Temporal

    Worker --> OTelCollector
    OTelCollector --> LangfuseServer

    LangfuseServer --> LangfuseDB
    LangfuseServer --> Redis
    LangfuseServer --> ClickHouse
    LangfuseServer --> MinIO

    Temporal --> TemporalDB

    classDef app fill:#e3f2fd
    classDef ui fill:#fff3e0
    classDef service fill:#e8f5e8
    classDef data fill:#fce4ec

    class Streamlit,Worker app
    class LangfuseUI,TemporalUI ui
    class Temporal,LangfuseServer,OTelCollector service
    class LangfuseDB,TemporalDB,Redis,ClickHouse,MinIO data

📋 Docker Compose Services

The docker-compose.yml includes:

Core Services:

  • temporal - Temporal server for workflow orchestration
  • langfuse - Langfuse server for LLM observability
  • otel-collector - OpenTelemetry collector for trace routing

Web UIs:

  • temporal-web - Temporal Web UI for workflow monitoring
  • langfuse - Includes built-in web interface

Data Persistence:

  • temporal-postgres - PostgreSQL for Temporal data
  • langfuse-postgres - PostgreSQL for Langfuse data
  • langfuse-redis - Redis for Langfuse caching
  • langfuse-clickhouse - ClickHouse for analytics
  • langfuse-minio - MinIO for S3-compatible storage

🔄 Service Management

# Start specific services only
docker-compose up temporal temporal-postgres temporal-web

# Start with custom configuration
AGENCY_ENVIRONMENT=production just dev-start

# View service health
docker-compose ps

# Follow logs from specific service
docker-compose logs -f langfuse

# Restart specific service
docker-compose restart temporal

# Remove specific service and its data
docker-compose down temporal
docker volume rm agency-temporal-postgres-data

Project Structure

agency/
├── .cicd/                  # CI/CD Pipeline templates and helper functions
├── config/                 # Configuration files for this project
├── agency/                 # Main application package
├── tests/                  # Test files
├── docs/                   # Documentation
├── .env.example            # Template file for environment variables
├── .pre-commit-config.yaml # Pre-commit hook configuration
├── Justfile                # Just command configuration
├── mkdocs.yaml             # Documentation configuration
├── pipeline.yml            # CI/CD pipeline configuration
├── pyproject.toml          # Project configuration
└── README.md               # Project overview

Development Tips

  • Use the virtual environment for all development work
  • Run tests before committing changes
  • Run linter before committing changes
  • Keep dependencies minimal and documented (ideally)

Next Steps