forked from molecule-ai/molecule-core
24fec62d7f
Forked clean from public hackathon repo (Starfire-AgentTeam, BSL 1.1) with full rebrand to Molecule AI under github.com/Molecule-AI/molecule-monorepo. Brand: Starfire → Molecule AI. Slug: starfire / agent-molecule → molecule. Env vars: STARFIRE_* → MOLECULE_*. Go module: github.com/agent-molecule/platform → github.com/Molecule-AI/molecule-monorepo/platform. Python packages: starfire_plugin → molecule_plugin, starfire_agent → molecule_agent. DB: agentmolecule → molecule. History truncated; see public repo for prior commits and contributor attribution. Verified green: go test -race ./... (platform), pytest (workspace-template 1129 + sdk 132), vitest (canvas 352), build (mcp). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
134 lines
4.4 KiB
Markdown
134 lines
4.4 KiB
Markdown
# Local Development
|
|
|
|
## Starting the Stack
|
|
|
|
```bash
|
|
docker compose up
|
|
```
|
|
|
|
This starts:
|
|
|
|
| Service | Port | Description |
|
|
|---------|------|-------------|
|
|
| Postgres | internal only | Primary database |
|
|
| Redis | internal only | Ephemeral state |
|
|
| Platform (Go) | `:8080` | Control plane API |
|
|
| Canvas (Next.js) | `:3000` | Visual frontend |
|
|
| Langfuse web | `:3001` (host) / `:3000` (internal) | Observability UI |
|
|
| Langfuse worker | — | Background processing |
|
|
| ClickHouse | — | Langfuse dependency |
|
|
|
|
Each workspace container is provisioned **on demand** by the platform when a user creates or imports one.
|
|
|
|
Langfuse uses a dedicated `langfuse` Postgres database. The compose stack creates it automatically before starting the Langfuse service, so it does not conflict with the platform's `molecule` schema.
|
|
|
|
### Infrastructure Only
|
|
|
|
To start just Postgres, Redis, and Langfuse (no application code):
|
|
|
|
```bash
|
|
docker compose -f docker-compose.infra.yml up
|
|
```
|
|
|
|
### Optional Profiles
|
|
|
|
```bash
|
|
docker compose --profile multi-provider up # Add LiteLLM proxy (unified LLM API)
|
|
docker compose --profile local-models up # Add Ollama (local LLM models)
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
### Platform (Go)
|
|
|
|
```
|
|
DATABASE_URL=postgres://dev:dev@postgres:5432/molecule?sslmode=prefer
|
|
REDIS_URL=redis://redis:6379
|
|
PORT=8080
|
|
SECRETS_ENCRYPTION_KEY=dev-key-change-in-production
|
|
WORKSPACE_DIR=/path/to/molecule-monorepo # Optional global fallback; prefer per-workspace workspace_dir in org.yaml or API
|
|
```
|
|
|
|
### Canvas (Next.js)
|
|
|
|
```
|
|
NEXT_PUBLIC_PLATFORM_URL=http://localhost:8080
|
|
NEXT_PUBLIC_WS_URL=ws://localhost:8080/ws
|
|
```
|
|
|
|
### Workspace Runtime
|
|
|
|
```
|
|
WORKSPACE_ID= # assigned by platform on provision
|
|
WORKSPACE_CONFIG_PATH= # path to config folder inside container
|
|
MODEL_PROVIDER= # e.g. anthropic:claude-sonnet-4-6
|
|
TIER= # 1, 2, 3, or 4
|
|
PLATFORM_URL= # http://platform:8080
|
|
PARENT_ID= # set by platform during team expansion (empty for top-level)
|
|
ANTHROPIC_API_KEY= # or OPENAI_API_KEY, etc.
|
|
LANGFUSE_HOST= # http://langfuse-web:3000 (internal container port; host-mapped to :3001)
|
|
LANGFUSE_PUBLIC_KEY=
|
|
LANGFUSE_SECRET_KEY=
|
|
LANGSMITH_TRACING=true # LangGraph reads this to enable tracing
|
|
```
|
|
|
|
## Technology Versions
|
|
|
|
```
|
|
Go 1.25+ (go.mod)
|
|
Python 3.11+
|
|
Node.js 22+
|
|
Next.js 15
|
|
React Flow 12 (@xyflow/react)
|
|
a2a-sdk 0.3+ (A2A server SDK, install with a2a-sdk[http-server])
|
|
langfuse 3.x (self-hosted Docker)
|
|
Postgres 16
|
|
Redis 7
|
|
Docker Compose 2.x
|
|
```
|
|
|
|
## Running Tests
|
|
|
|
### Unit Tests
|
|
|
|
```bash
|
|
cd platform && go test -race ./... # Go tests with race detection (358 tests)
|
|
cd canvas && npm test # Vitest tests (188 tests)
|
|
cd workspace-template && python -m pytest -v # Workspace runtime tests (148 tests)
|
|
```
|
|
|
|
### Integration Tests
|
|
|
|
```bash
|
|
bash test_api.sh # 62 API tests (requires platform running)
|
|
bash test_a2a_e2e.sh # 22 A2A e2e tests (requires platform + 2 agents)
|
|
bash test_activity_e2e.sh # 25 activity/task E2E tests (requires platform + 1 agent)
|
|
```
|
|
|
|
### CI Pipeline
|
|
|
|
GitHub Actions runs automatically on push to `main` and on PRs (`.github/workflows/ci.yml`):
|
|
- **platform-build** — Go build, vet, `go test -race` with coverage profiling (25% baseline threshold)
|
|
- **canvas-build** — npm build, `vitest run` (no `--passWithNoTests` -- tests must exist and pass)
|
|
- **mcp-server-build** — npm build
|
|
- **python-lint** — `pytest --cov=. --cov-report=term-missing` (pytest-cov enabled)
|
|
|
|
Postgres and Redis are not exposed to the host -- use `docker compose exec postgres psql` or `docker compose exec redis redis-cli` for direct access.
|
|
|
|
## Utility Scripts
|
|
|
|
| Script | Purpose |
|
|
|--------|---------|
|
|
| `infra/scripts/setup.sh` | Initialize the local environment |
|
|
| `infra/scripts/nuke.sh` | Tear down and clean up everything |
|
|
| `bundle-compile.sh` | Compile workspace config folders into `.bundle.json` files |
|
|
| `test_api.sh` | Run 62 platform API integration tests |
|
|
| `test_a2a_e2e.sh` | Run 22 A2A end-to-end tests |
|
|
| `test_activity_e2e.sh` | Run 25 activity/task E2E tests |
|
|
| `setup-org.sh` | Create default 15-agent org hierarchy (PM + Marketing/Research/Dev teams, all Claude Code) |
|
|
|
|
## Related Docs
|
|
|
|
- [Architecture](../architecture/architecture.md) — System overview
|
|
- [Observability](./observability.md) — Langfuse details
|