For Developers & Contributors

This guide is for developing 2LY itself—modifying the codebase, adding features, or fixing bugs.

Just want to use 2LY? You're in the wrong place. See Installation for production setup (Docker-only, much simpler).

Set up a local environment for contributing to 2LY. This allows you to run the backend, frontend, and runtime locally with hot reload for rapid development.

Quick Reference: For complete development workflows and commands, see the dev/README.md in the repository.

Prerequisites

Required for development:

Node.js 22+
Docker

Setup

1. Fork and Clone

git clone https://github.com/YOUR_USERNAME/2ly.git
cd 2ly

2. Install Dependencies

npm install

3. Generate Cryptographic Keys (First Time Only)

npm run setup-local

This generates cryptographic keys to dev/.docker-keys/ that are shared between Docker services and local development processes. You only need to run this once - keys persist across sessions.

What does this do? Generates encryption keys, JWT signing keys, and NATS authentication tokens required for the backend and runtime to operate securely.

4. Start Development Environment

Start infrastructure services (Docker):

npm run start:dev

This starts Dgraph, NATS, and other infrastructure services in Docker.

Run services locally (for development):

# In separate terminals:
npm run dev:backend    # Backend at http://localhost:3000
npm run dev:frontend   # Frontend at http://localhost:8888
npm run dev:main-runtime  # Runtime process

Running services locally provides hot reload and better debugging experience.

Development Mode: The infrastructure (Dgraph, NATS) runs in Docker while your code (backend, frontend, runtime) runs locally with hot reload. This gives you the best of both worlds.

Development Workflow

Create a Feature Branch

git checkout -b feature/your-feature-name

Make Changes with Hot Reload

When running services locally (npm run dev:*), changes to code will automatically reload:

Backend: Changes trigger restart with Nodemon
Frontend: Vite hot module replacement (HMR)
Runtime: Requires manual restart with npm run dev:main-runtime

Run Tests

# Run all tests
npm run test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npm run test:cov

# Run integration tests
npm run test:integration

# Run E2E tests
npm run test:e2e

Lint and Format

# Lint all packages
npm run lint

# Format code
npm run format

# Type check
npm run typecheck

Build for Production

# Build all packages
npm run build

# Build specific package
npm run build -w @2ly/backend
npm run build -w @2ly/frontend
npm run build -w @2ly/runtime

Generate GraphQL Types

After modifying GraphQL schemas:

npm run codegen

Project Structure

packages/
  backend/      # GraphQL API
  frontend/     # React UI
  runtime/      # MCP runtime
  common/       # Shared code
  twoly/        # Python SDK

Development Services & Ports

When running locally, these services are available:

Service	Port	Description
Frontend	8888	React development server
Backend GraphQL	3000	Apollo Server (HTTP & WebSocket)
Dgraph Ratel	8000	Graph database UI
NATS Dashboard	8001	Message broker monitoring
Dgraph Alpha	9080	GraphQL endpoint
NATS	4222	Message broker

Troubleshooting

Port conflicts:

# Check which ports are in use
lsof -i :8888,3000,4222,8000,8001,9080

# Kill processes on specific port
kill -9 $(lsof -t -i:3000)

Docker not running:

# Check Docker status
docker --version
docker compose version

# Start Docker Desktop (macOS)
open -a Docker

Node version issues:

# Check Node version (must be 22+)
node --version

# Use nvm to switch versions
nvm install 22
nvm use 22

Database issues:

# Reset Dgraph database
docker compose -f dev/docker-compose.dev.yml down -v
docker compose -f dev/docker-compose.dev.yml up -d dgraph

NATS connection issues:

# Check NATS logs
docker compose -f dev/docker-compose.dev.yml logs nats

# Restart NATS
docker compose -f dev/docker-compose.dev.yml restart nats

Module not found errors:

# Clean install
rm -rf node_modules package-lock.json
npm install

Next Steps

Development Guide - Comprehensive development documentation
Issues & PRs - How to contribute code
dev/README.md - Complete command reference

Need Help? Join our Discord community or open an issue on GitHub.

Development Setup