diff --git a/.github/workflows/robot-tests.yml b/.github/workflows/robot-tests.yml index 4ba9b251..060d3699 100644 --- a/.github/workflows/robot-tests.yml +++ b/.github/workflows/robot-tests.yml @@ -145,7 +145,7 @@ jobs: # Show logs every 10 attempts to help debug if [ $((i % 10)) -eq 0 ]; then echo "Still waiting... showing recent logs:" - docker compose -f docker-compose-test.yml logs --tail=20 friend-backend-test + docker compose -f docker-compose-test.yml logs --tail=20 chronicle-backend-test fi if [ $i -eq 40 ]; then echo "✗ Backend failed to start - showing full logs:" @@ -223,7 +223,7 @@ jobs: working-directory: backends/advanced run: | echo "=== Backend Logs (last 50 lines) ===" - docker compose -f docker-compose-test.yml logs --tail=50 friend-backend-test + docker compose -f docker-compose-test.yml logs --tail=50 chronicle-backend-test echo "" echo "=== Worker Logs (last 50 lines) ===" docker compose -f docker-compose-test.yml logs --tail=50 workers-test diff --git a/CLAUDE.md b/CLAUDE.md index ec326b6d..e505b25a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -13,6 +13,49 @@ This supports a comprehensive web dashboard for management. **❌ No Backward Compatibility**: Do NOT add backward compatibility code unless explicitly requested. This includes fallback logic, legacy field support, or compatibility layers. Always ask before adding backward compatibility - in most cases the answer is no during active development. +## Initial Setup & Configuration + +Chronicle includes an **interactive setup wizard** for easy configuration. The wizard guides you through: +- Service selection (backend + optional services) +- Authentication setup (admin account, JWT secrets) +- Transcription provider configuration (Deepgram, Mistral, or offline ASR) +- LLM provider setup (OpenAI or Ollama) +- Memory provider selection (Chronicle Native with Qdrant or OpenMemory MCP) +- Network configuration and HTTPS setup +- Optional services (speaker recognition, Parakeet ASR) + +### Quick Start +```bash +# Run the interactive setup wizard from project root +uv run python wizard.py + +# Or use the quickstart guide for step-by-step instructions +# See quickstart.md for detailed walkthrough +``` + +### Setup Documentation +For detailed setup instructions and troubleshooting, see: +- **[@quickstart.md](quickstart.md)**: Beginner-friendly step-by-step setup guide +- **[@Docs/init-system.md](Docs/init-system.md)**: Complete initialization system architecture and design +- **[@Docs/getting-started.md](Docs/getting-started.md)**: Technical quickstart with advanced configuration +- **[@backends/advanced/SETUP_SCRIPTS.md](backends/advanced/SETUP_SCRIPTS.md)**: Setup scripts reference and usage examples +- **[@backends/advanced/Docs/quickstart.md](backends/advanced/Docs/quickstart.md)**: Backend-specific setup guide + +### Wizard Architecture +The initialization system uses a **root orchestrator pattern**: +- **`wizard.py`**: Root setup orchestrator for service selection and delegation +- **`backends/advanced/init.py`**: Backend configuration wizard +- **`extras/speaker-recognition/init.py`**: Speaker recognition setup +- **Service setup scripts**: Individual setup for ASR services and OpenMemory MCP + +Key features: +- Interactive prompts with validation +- API key masking and secure credential handling +- Environment file generation with placeholders +- HTTPS configuration with SSL certificate generation +- Service status display and health checks +- Automatic backup of existing configurations + ## Development Commands ### Backend Development (Advanced Backend - Primary) diff --git a/Docs/getting-started.md b/Docs/getting-started.md index 6483f00f..2a93ec1d 100644 --- a/Docs/getting-started.md +++ b/Docs/getting-started.md @@ -396,7 +396,7 @@ uv sync --group (whatever group you want to sync) ## Troubleshooting **Service Issues:** -- Check logs: `docker compose logs friend-backend` +- Check logs: `docker compose logs chronicle-backend` - Restart services: `docker compose restart` - View all services: `docker compose ps` diff --git a/Docs/init-system.md b/Docs/init-system.md index ea4db94d..3df6316c 100644 --- a/Docs/init-system.md +++ b/Docs/init-system.md @@ -230,7 +230,7 @@ curl http://localhost:8767/health docker compose logs [service-name] # Backend logs -cd backends/advanced && docker compose logs friend-backend +cd backends/advanced && docker compose logs chronicle-backend # Speaker Recognition logs cd extras/speaker-recognition && docker compose logs speaker-service diff --git a/backends/advanced/Docs/HTTPS_SETUP.md b/backends/advanced/Docs/HTTPS_SETUP.md index 155172c4..54852a20 100644 --- a/backends/advanced/Docs/HTTPS_SETUP.md +++ b/backends/advanced/Docs/HTTPS_SETUP.md @@ -89,7 +89,7 @@ CORS_ORIGINS=https://localhost,https://127.0.0.1,https://100.83.66.30 **Services started:** - ✅ nginx (ports 443/80) - SSL termination and proxy - ✅ webui (port 5173, internal) - Vite dev server -- ✅ friend-backend (port 8000, internal) +- ✅ chronicle-backend (port 8000, internal) - ✅ mongo, qdrant (databases) **Access:** https://localhost/ or https://your-ip/ @@ -99,7 +99,7 @@ CORS_ORIGINS=https://localhost,https://127.0.0.1,https://100.83.66.30 **Services started:** - ✅ nginx (ports 443/80) - but without SSL certificates - ✅ webui (port 5173, direct access) - Vite dev server -- ✅ friend-backend (port 8000) +- ✅ chronicle-backend (port 8000) - ✅ mongo, qdrant (databases) **Access:** http://localhost:5173 @@ -169,7 +169,7 @@ docker compose restart nginx **Problem:** "Cross-Origin Request Blocked" **Solution:** 1. Update CORS_ORIGINS in `.env` to include your HTTPS origin -2. Restart backend: `docker compose restart friend-backend` +2. Restart backend: `docker compose restart chronicle-backend` ### Microphone Access Denied @@ -192,7 +192,7 @@ docker compose restart nginx ### Standard Setup - **3000** - HTTP (webui production) - **5173** - HTTP (webui development) -- **8000** - HTTP (friend-backend) +- **8000** - HTTP (chronicle-backend) ## Live Recording Feature diff --git a/backends/advanced/Docs/README.md b/backends/advanced/Docs/README.md index 5943c5e5..428789bc 100644 --- a/backends/advanced/Docs/README.md +++ b/backends/advanced/Docs/README.md @@ -189,7 +189,7 @@ backends/advanced-backend/ - **Debug API**: `GET /api/debug/memory/*` endpoints show real-time system status - **Configuration**: Check `memory_config.yaml` for behavior controls -- **Logs**: Check Docker logs with `docker compose logs friend-backend` +- **Logs**: Check Docker logs with `docker compose logs chronicle-backend` - **Documentation**: Each doc file links to relevant code sections --- diff --git a/backends/advanced/Docs/architecture.md b/backends/advanced/Docs/architecture.md index d5edb6a3..7c6427bb 100644 --- a/backends/advanced/Docs/architecture.md +++ b/backends/advanced/Docs/architecture.md @@ -585,7 +585,7 @@ stateDiagram-v2 ```mermaid graph LR subgraph "Docker Network" - Backend[friend-backend
uv + FastAPI] + Backend[chronicle-backend
uv + FastAPI] WebUI[webui
React Dashboard] Proxy[nginx
Load Balancer] Mongo[mongo:4.4.18
Primary Database] @@ -616,7 +616,7 @@ graph LR ### Container Specifications -#### Backend Container (`friend-backend`) +#### Backend Container (`chronicle-backend`) - **Base**: Python 3.12 slim with uv package manager - **Dependencies**: FastAPI, WebSocket libraries, audio processing tools - **Volumes**: Audio chunk storage, debug directories diff --git a/backends/advanced/Docs/auth.md b/backends/advanced/Docs/auth.md index 2aa7d254..acbf8df4 100644 --- a/backends/advanced/Docs/auth.md +++ b/backends/advanced/Docs/auth.md @@ -260,7 +260,7 @@ curl -X POST "http://localhost:8000/auth/jwt/login" \ #### 3. Admin User Creation ```bash # Check logs for admin creation -docker compose logs friend-backend | grep -i admin +docker compose logs chronicle-backend | grep -i admin # Verify environment variables echo $ADMIN_PASSWORD @@ -272,7 +272,7 @@ echo $ADMIN_PASSWORD docker exec -it mongo-container mongosh chronicle # View authentication logs -docker compose logs friend-backend | grep -i auth +docker compose logs chronicle-backend | grep -i auth # Test API endpoints curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/users/me diff --git a/backends/advanced/Docs/quickstart.md b/backends/advanced/Docs/quickstart.md index fc5a77b7..1c12c598 100644 --- a/backends/advanced/Docs/quickstart.md +++ b/backends/advanced/Docs/quickstart.md @@ -394,7 +394,7 @@ uv sync --group (whatever group you want to sync) ## Troubleshooting **Service Issues:** -- Check logs: `docker compose logs friend-backend` +- Check logs: `docker compose logs chronicle-backend` - Restart services: `docker compose restart` - View all services: `docker compose ps` diff --git a/backends/advanced/nginx.conf.template b/backends/advanced/nginx.conf.template index 8c2d825d..e5a3e025 100644 --- a/backends/advanced/nginx.conf.template +++ b/backends/advanced/nginx.conf.template @@ -43,8 +43,8 @@ http { } # Upstream services - upstream friend_backend { - server friend-backend:8000; + upstream chronicle_backend { + server chronicle-backend:8000; } upstream friend_webui { @@ -70,7 +70,7 @@ http { # Backend API endpoints location /api/ { - proxy_pass http://friend_backend/api/; + proxy_pass http://chronicle_backend/api/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; @@ -80,7 +80,7 @@ http { # Authentication endpoints location /auth/ { - proxy_pass http://friend_backend/auth/; + proxy_pass http://chronicle_backend/auth/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; @@ -90,7 +90,7 @@ http { # Users endpoints location /users/ { - proxy_pass http://friend_backend/users/; + proxy_pass http://chronicle_backend/users/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; @@ -100,7 +100,7 @@ http { # WebSocket endpoints for audio streaming location /ws_pcm { - proxy_pass http://friend_backend/ws_pcm; + proxy_pass http://chronicle_backend/ws_pcm; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; @@ -117,7 +117,7 @@ http { } location /ws_omi { - proxy_pass http://friend_backend/ws_omi; + proxy_pass http://chronicle_backend/ws_omi; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; @@ -135,7 +135,7 @@ http { # Legacy WebSocket endpoint location /ws { - proxy_pass http://friend_backend/ws; + proxy_pass http://chronicle_backend/ws; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; @@ -153,7 +153,7 @@ http { # Health check endpoints location /health { - proxy_pass http://friend_backend/health; + proxy_pass http://chronicle_backend/health; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; @@ -162,7 +162,7 @@ http { # Readiness check endpoint location /readiness { - proxy_pass http://friend_backend/readiness; + proxy_pass http://chronicle_backend/readiness; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; @@ -171,7 +171,7 @@ http { # Audio file serving location /audio/ { - proxy_pass http://friend_backend/audio/; + proxy_pass http://chronicle_backend/audio/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; diff --git a/backends/advanced/tests/test_integration.py b/backends/advanced/tests/test_integration.py index 5b607a76..4364e1b9 100644 --- a/backends/advanced/tests/test_integration.py +++ b/backends/advanced/tests/test_integration.py @@ -457,7 +457,7 @@ def start_services(self): logger.info(f"🔄 Found {len(running_services)} running test services") # Check if test backend is healthy (only skip if not rebuilding) try: - health_check = subprocess.run(["docker", "compose", "-f", "docker-compose-test.yml", "ps", "friend-backend-test"], capture_output=True, text=True) + health_check = subprocess.run(["docker", "compose", "-f", "docker-compose-test.yml", "ps", "chronicle-backend-test"], capture_output=True, text=True) if "healthy" in health_check.stdout or "Up" in health_check.stdout: logger.info("✅ Test services already running and healthy, skipping restart") self.services_started = True diff --git a/backends/advanced/webui/README.md b/backends/advanced/webui/README.md index 303b2780..9642eb7e 100644 --- a/backends/advanced/webui/README.md +++ b/backends/advanced/webui/README.md @@ -57,7 +57,7 @@ A modern React-based web interface for the Chronicle AI-powered personal audio s 4. **Start backend services:** ```bash cd ../ - docker compose up friend-backend mongo qdrant + docker compose up chronicle-backend mongo qdrant ``` ### Docker Development @@ -70,7 +70,7 @@ docker compose --profile dev up ``` This starts: -- Backend services (friend-backend, mongo, qdrant) +- Backend services (chronicle-backend, mongo, qdrant) - React dev server with hot reload (http://localhost:5173) ## Production Deployment @@ -79,7 +79,7 @@ This starts: ```bash cd backends/advanced -docker compose up webui friend-backend mongo qdrant +docker compose up webui chronicle-backend mongo qdrant ``` The production build will be available at http://localhost:3000 diff --git a/backends/simple/README.md b/backends/simple/README.md index 46908810..d9cb2c69 100644 --- a/backends/simple/README.md +++ b/backends/simple/README.md @@ -115,7 +115,7 @@ For full transcription and memory features, use the [Advanced Backend](../advanc ### Logs ```bash # View service logs -docker compose logs -f friend-backend +docker compose logs -f chronicle-backend # Check audio processing tail -f ./audio_chunks/ diff --git a/backends/simple/docker-compose.yml b/backends/simple/docker-compose.yml index 3581d650..8ae18950 100644 --- a/backends/simple/docker-compose.yml +++ b/backends/simple/docker-compose.yml @@ -1,5 +1,5 @@ services: - friend-backend: + chronicle-backend: build: context: . dockerfile: Dockerfile @@ -14,6 +14,6 @@ services: environment: - NGROK_AUTHTOKEN=${NGROK_AUTHTOKEN} - NGROK_DOMAIN=${NGROK_DOMAIN} - command: "http friend-backend:8000 --domain=${NGROK_DOMAIN}" + command: "http chronicle-backend:8000 --domain=${NGROK_DOMAIN}" depends_on: - - friend-backend + - chronicle-backend diff --git a/skaffold.yaml b/skaffold.yaml index 279566ce..718e61a3 100644 --- a/skaffold.yaml +++ b/skaffold.yaml @@ -184,7 +184,7 @@ profiles: build: artifacts: - - image: friend-backend-test + - image: chronicle-backend-test context: backends/advanced docker: dockerfile: Dockerfile @@ -195,7 +195,7 @@ profiles: deploy: docker: - images: [friend-backend-test, webui-test, mongo-test, qdrant-test, redis-test] + images: [chronicle-backend-test, webui-test, mongo-test, qdrant-test, redis-test] diff --git a/tests/TESTING_USER_GUIDE.md b/tests/TESTING_USER_GUIDE.md index d1ebbd9d..5dc6bf6d 100644 --- a/tests/TESTING_USER_GUIDE.md +++ b/tests/TESTING_USER_GUIDE.md @@ -722,7 +722,7 @@ robot --rerunfailed output.xml tests/ CLEANUP_CONTAINERS=false robot tests/endpoints/auth_tests.robot # Inspect backend logs -docker logs advanced-friend-backend-test-1 +docker logs advanced-chronicle-backend-test-1 # Inspect database docker exec -it advanced-mongo-test-1 mongosh test_db diff --git a/tests/endpoints/rq_queue_tests.robot b/tests/endpoints/rq_queue_tests.robot index f8b91346..892a1090 100644 --- a/tests/endpoints/rq_queue_tests.robot +++ b/tests/endpoints/rq_queue_tests.robot @@ -28,11 +28,11 @@ Restart Backend Service Log Restarting backend service to test job persistence # Stop backend container - Run Process docker compose -f ${COMPOSE_FILE} stop friend-backend-test + Run Process docker compose -f ${COMPOSE_FILE} stop chronicle-backend-test ... cwd=. timeout=30s # Start backend container again - Run Process docker compose -f ${COMPOSE_FILE} start friend-backend-test + Run Process docker compose -f ${COMPOSE_FILE} start chronicle-backend-test ... cwd=. timeout=60s # Wait for backend to be ready again diff --git a/tests/run-robot-tests.sh b/tests/run-robot-tests.sh index d56adab7..4ec3c657 100755 --- a/tests/run-robot-tests.sh +++ b/tests/run-robot-tests.sh @@ -108,26 +108,26 @@ fi # Clean up any existing test containers and volumes for fresh start print_info "Cleaning up any existing test environment..." -docker compose -f docker-compose-ci.yml down -v 2>/dev/null || true +docker compose -f docker-compose-test.yml down -v 2>/dev/null || true # Force remove any stuck containers with test names print_info "Removing any stuck test containers..." -docker rm -f advanced-mongo-test-1 advanced-redis-test-1 advanced-qdrant-test-1 advanced-friend-backend-test-1 advanced-workers-test-1 advanced-webui-test-1 2>/dev/null || true +docker rm -f advanced-mongo-test-1 advanced-redis-test-1 advanced-qdrant-test-1 advanced-chronicle-backend-test-1 advanced-workers-test-1 advanced-webui-test-1 2>/dev/null || true # Start infrastructure services (MongoDB, Redis, Qdrant) print_info "Starting MongoDB, Redis, and Qdrant (fresh containers)..." -docker compose -f docker-compose-ci.yml up -d --quiet-pull mongo-test redis-test qdrant-test +docker compose -f docker-compose-test.yml up -d --quiet-pull mongo-test redis-test qdrant-test # Wait for MongoDB print_info "Waiting for MongoDB (up to 60s)..." for i in {1..30}; do - if docker compose -f docker-compose-ci.yml exec -T mongo-test mongosh --eval "db.adminCommand({ping: 1})" > /dev/null 2>&1; then + if docker compose -f docker-compose-test.yml exec -T mongo-test mongosh --eval "db.adminCommand({ping: 1})" > /dev/null 2>&1; then print_success "MongoDB is ready" break fi if [ $i -eq 30 ]; then print_error "MongoDB failed to start" - docker compose -f docker-compose-ci.yml logs mongo-test + docker compose -f docker-compose-test.yml logs mongo-test exit 1 fi sleep 2 @@ -142,7 +142,7 @@ for i in {1..30}; do fi if [ $i -eq 30 ]; then print_error "Qdrant failed to start" - docker compose -f docker-compose-ci.yml logs qdrant-test + docker compose -f docker-compose-test.yml logs qdrant-test exit 1 fi sleep 2 @@ -150,10 +150,10 @@ done # Build and start backend print_info "Building backend..." -docker compose -f docker-compose-ci.yml build friend-backend-test +docker compose -f docker-compose-test.yml build chronicle-backend-test print_info "Starting backend..." -docker compose -f docker-compose-ci.yml up -d friend-backend-test +docker compose -f docker-compose-test.yml up -d chronicle-backend-test # Wait for backend print_info "Waiting for backend (up to 120s)..." @@ -164,7 +164,7 @@ for i in {1..40}; do fi if [ $i -eq 40 ]; then print_error "Backend failed to start" - docker compose -f docker-compose-ci.yml logs friend-backend-test + docker compose -f docker-compose-test.yml logs chronicle-backend-test exit 1 fi sleep 3 @@ -172,18 +172,18 @@ done # Start workers print_info "Starting RQ workers..." -docker compose -f docker-compose-ci.yml up -d workers-test +docker compose -f docker-compose-test.yml up -d workers-test # Wait for workers container print_info "Waiting for workers container (up to 30s)..." for i in {1..15}; do - if docker compose -f docker-compose-ci.yml ps workers-test | grep -q "Up"; then + if docker compose -f docker-compose-test.yml ps workers-test | grep -q "Up"; then print_success "Workers container is running" break fi if [ $i -eq 15 ]; then print_error "Workers container failed to start" - docker compose -f docker-compose-ci.yml logs workers-test + docker compose -f docker-compose-test.yml logs workers-test exit 1 fi sleep 2 @@ -192,7 +192,7 @@ done # Verify workers are registered print_info "Waiting for workers to register with Redis (up to 60s)..." for i in {1..30}; do - WORKER_COUNT=$(docker compose -f docker-compose-ci.yml exec -T workers-test uv run python -c 'from rq import Worker; from redis import Redis; import os; r = Redis.from_url(os.getenv("REDIS_URL", "redis://redis-test:6379/0")); print(len(Worker.all(connection=r)))' 2>/dev/null || echo "0") + WORKER_COUNT=$(docker compose -f docker-compose-test.yml exec -T workers-test uv run python -c 'from rq import Worker; from redis import Redis; import os; r = Redis.from_url(os.getenv("REDIS_URL", "redis://redis-test:6379/0")); print(len(Worker.all(connection=r)))' 2>/dev/null || echo "0") if [ "$WORKER_COUNT" -ge 6 ]; then print_success "Found $WORKER_COUNT workers registered" @@ -201,7 +201,7 @@ for i in {1..30}; do if [ $i -eq 30 ]; then print_error "Workers failed to register after 60s" - docker compose -f docker-compose-ci.yml logs --tail=50 workers-test + docker compose -f docker-compose-test.yml logs --tail=50 workers-test exit 1 fi @@ -236,10 +236,10 @@ if [ $TEST_EXIT_CODE -ne 0 ]; then print_info "Showing service logs..." cd ../backends/advanced echo "=== Backend Logs (last 50 lines) ===" - docker compose -f docker-compose-ci.yml logs --tail=50 friend-backend-test + docker compose -f docker-compose-test.yml logs --tail=50 chronicle-backend-test echo "" echo "=== Worker Logs (last 50 lines) ===" - docker compose -f docker-compose-ci.yml logs --tail=50 workers-test + docker compose -f docker-compose-test.yml logs --tail=50 workers-test cd ../../tests fi @@ -286,12 +286,12 @@ fi if [ "$CLEANUP_CONTAINERS" = "true" ]; then print_info "Cleaning up test containers..." cd ../backends/advanced - docker compose -f docker-compose-ci.yml down -v + docker compose -f docker-compose-test.yml down -v cd ../../tests print_success "Cleanup complete" else print_warning "Skipping container cleanup (CLEANUP_CONTAINERS=false)" - print_info "To cleanup manually: cd backends/advanced && docker compose -f docker-compose-ci.yml down -v" + print_info "To cleanup manually: cd backends/advanced && docker compose -f docker-compose-test.yml down -v" fi if [ $TEST_EXIT_CODE -eq 0 ]; then diff --git a/tests/setup/README.md b/tests/setup/README.md index b5ea71c8..3e9ba561 100644 --- a/tests/setup/README.md +++ b/tests/setup/README.md @@ -213,7 +213,7 @@ REBUILD=true robot tests/ CLEANUP_CONTAINERS=false robot tests/endpoints/failing_test.robot # Inspect logs -docker logs advanced-friend-backend-test-1 +docker logs advanced-chronicle-backend-test-1 docker logs advanced-mongo-test-1 # Inspect database