Skip to content

QUICK_START.md

Latest commit

 

History

History
195 lines (140 loc) · 4.18 KB

QUICK_START.md

File metadata and controls

195 lines (140 loc) · 4.18 KB
Raw
title AllSource - Quick Start Guide
status CURRENT
last_updated 2026-02-02
category guide

AllSource - Quick Start Guide

⚡ Using as a Library

The fastest way to get started is adding allsource-core to your Rust project:

cargo add allsource-core@0.2

Or add to your Cargo.toml (pin to minor version for stability):

[dependencies]
# allsource-core: High-performance event store
# Pin to minor version - allows patch updates only
allsource-core = "0.2"

Version Pinning: We recommend pinning to "0.2" (minor version) rather than "0.2.0" (exact) or "0" (major only). This allows automatic patch updates for bug fixes while avoiding breaking changes. See our Dependency Management Guide for best practices.

Links: crates.io · docs.rs · GitHub

🏃 Running the Full Stack

Step 1: Install Dependencies (One-Time Setup)

# Install Bun if you don't have it
curl -fsSL https://bun.sh/install | bash

# Install all project dependencies
bun install

# Install Go dependencies
cd apps/control-plane && go mod download && cd ../..

Step 2: Start Services (3 Terminals)

Terminal 1 - Event Store Core:

cd apps/core
cargo run --release
# Wait for: "🚀 AllSource Core listening on 0.0.0.0:3900"

Terminal 2 - Control Plane:

cd apps/control-plane
go run main.go
# Wait for: "🚀 Control Plane listening on port 3901"

Terminal 3 - Web UI:

cd apps/web
bun dev
# Wait for: "▲ Next.js 14.1.0 - Local: http://localhost:3000"

Step 3: Open Dashboard

Visit: http://localhost:3000

🎯 Quick Demo Actions

1. Ingest Events

Click "Ingest Demo Event" button → Watch stats update in real-time

2. Query by Entity

  1. Copy the entity ID shown in the button (e.g., user-789)
  2. Paste into "Entity ID" filter
  3. Click "Search"
  4. Expand an event to see the payload

3. API Test

# Ingest via API
curl -X POST http://localhost:3900/api/v1/events \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "test.event",
    "entity_id": "demo-123",
    "payload": {"message": "Hello AllSource!"}
  }'

# Query the event
curl "http://localhost:3900/api/v1/events/query?entity_id=demo-123" | jq

🐛 Troubleshooting

"Port already in use"

# Check what's using the ports
lsof -i :3900  # Core
lsof -i :3901  # Control Plane
lsof -i :3000  # Web UI

# Kill if needed
kill -9 <PID>

"Rust/Go/Bun not found"

"Service won't start"

# Check logs for errors
cd apps/core && cargo run  # See Rust errors
cd apps/control-plane && go run main.go  # See Go errors
cd apps/web && bun dev  # See Next.js errors

"Can't connect to Core from Control Plane"

Make sure Core is running first! Control Plane depends on Core.

📝 Useful Commands

# View all make targets
make help

# Install everything
make install

# Run all services (requires tmux or manually open 3 terminals)
make dev

# Clean all builds
make clean

# Run demo script (after services are running)
./demo-script.sh

# Format code
bun format

🔗 Service URLs

Service URL Purpose
Web UI http://localhost:3000 Visual dashboard
Event Store API http://localhost:3900 Core event operations
Control Plane http://localhost:3901 Cluster management
Query Service http://localhost:3902 Elixir query processing

📚 Next Steps

  1. Read the full README: README.md
  2. Understand the architecture: ARCHITECTURE.md
  3. Prepare for demo: DEMO.md
  4. Try the demo script: ./demo-script.sh

🆘 Still Stuck?

Check these files:

  • README.md - Full documentation
  • DEMO.md - Presentation guide
  • ARCHITECTURE.md - Technical deep-dive

Or create an issue describing your problem!

AllSource - You're ready to roll! 🚀