Self-host: precise local setup docs + CLICKHOUSE_SECURE support (local ClickHouse) [Devin]

[devin-ai-integration]

📥 Pull Request

📘 Description

Enables comprehensive local self-hosting of AgentOps by adding configurable ClickHouse connection support and precise setup documentation. This allows developers to run the full stack (dashboard, API, ClickHouse, Supabase) locally for development and testing.

Key Changes:

• CLICKHOUSE_SECURE environment variable: Makes ClickHouse connection security configurable (defaults to false for local HTTP, can be set to true for cloud HTTPS)
• Comprehensive setup documentation: Added step-by-step Quick Start guide to app/README.md plus detailed troubleshooting docs
• Environment variable completeness: Added missing S3 bucket env vars to compose files
• OTLP collector JWT default: Clarified JWT_SECRET fallback for local development

🧪 Testing

Performed complete end-to-end testing of local setup:

• ✅ Full stack startup (dashboard, API, ClickHouse, Supabase)
• ✅ User signup/login flow
• ✅ OpenAI example script with OTLP trace ingestion
• ✅ Trace verification in both ClickHouse and dashboard UI
• ✅ Projects and API keys functionality

⚠️ Critical Review Areas

1. CLICKHOUSE_SECURE backward compatibility: Changed from hardcoded secure: bool = True to secure: bool = CLICKHOUSE_SECURE (defaults to false). Could break existing cloud deployments if they don't explicitly set CLICKHOUSE_SECURE=true.

2. JWT_SECRET change: Modified OTLP collector compose from ${JWT_SECRET:-} to ${JWT_SECRET_KEY:-super-secret-jwt-token-with-at-least-32-characters-long}. May impact existing deployments using JWT_SECRET.

3. New environment dependencies: Added S3 bucket env vars to compose.yaml. Could cause startup issues if these aren't defined in existing deployments.

4. Documentation accuracy: Setup instructions must work for new users on fresh machines.

🔍 Human Review Checklist

• Verify CLICKHOUSE_SECURE=false doesn't break cloud deployments that expect HTTPS
• Confirm JWT_SECRET_KEY change doesn't impact existing OTLP collector deployments
• Test documentation steps on a fresh machine to ensure accuracy
• Verify no real credentials are present in committed documentation files
• Check that new S3 env vars in compose.yaml are backward compatible

---

Link to Devin run: https://app.devin.ai/sessions/10deeaa5961b4b2ab68ee073277cd71e
Requested by: @areibman

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring