61f6b8d2d5
Comprehensive deploy safety audit implementing 19 improvements across CI/CD pipeline, test coverage, and source code. ### CI/CD Pipeline - ruff + mypy added to both release.yml and keboola-deploy.yml (continue-on-error) - Smoke test added to keboola-deploy.yml (was missing) - Automatic rollback on smoke test failure in release.yml - Expanded smoke-test.sh with catalog, admin/tables, marketplace.zip, metrics - Required status checks via .github/settings.yml - Dependabot + CODEOWNERS + pre-commit hooks + ruff config ### Source Code - DB schema version check in /api/health (db_schema: ok/mismatch/unhealthy) - Config versioning (config_version: 1 in instance.yaml, non-blocking validation) - BigQuery extractor ATTACH error handling (try/except around INSTALL+ATTACH) - Post-deploy smoke test script for prod VM validation ### Test Coverage (~50 new tests) - v13->v14 migration, Email magic link TTL, PAT, Marketplace ZIP/Git, Jira webhooks, Hybrid Query BQ, Keboola/BQ extractor failure modes, Orchestrator failure modes Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
88 lines
2.4 KiB
Markdown
88 lines
2.4 KiB
Markdown
# Quick Start Guide
|
|
|
|
## Prerequisites
|
|
|
|
- Python 3.10+
|
|
- Docker + Docker Compose (for production deployment)
|
|
- Data source credentials (Keboola token, BigQuery project, etc.)
|
|
|
|
## Local Development Setup
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
git clone <repo-url>
|
|
cd ai-data-analyst
|
|
```
|
|
|
|
2. Create virtual environment and install dependencies:
|
|
```bash
|
|
python3 -m venv .venv && source .venv/bin/activate
|
|
uv pip install ".[dev]"
|
|
```
|
|
|
|
3. Configure your instance:
|
|
```bash
|
|
cp config/instance.yaml.example config/instance.yaml
|
|
# Edit config/instance.yaml with your settings
|
|
```
|
|
|
|
4. Set up environment variables:
|
|
```bash
|
|
cp config/.env.template .env
|
|
# Edit .env with your data source credentials
|
|
```
|
|
|
|
5. Register your tables via the admin API or CLI:
|
|
```bash
|
|
# Via CLI
|
|
da admin register-table --source-type keboola --bucket "in.c-crm" --table "company" --query-mode local
|
|
|
|
# Or start the server and use the web UI at /admin/tables
|
|
```
|
|
|
|
6. Start the FastAPI server:
|
|
```bash
|
|
uvicorn app.main:app --reload
|
|
```
|
|
|
|
7. Trigger a data sync:
|
|
```bash
|
|
curl -X POST http://localhost:8000/api/sync/trigger
|
|
# Or: da sync
|
|
```
|
|
|
|
## Docker Deployment
|
|
|
|
```bash
|
|
# Start app + scheduler
|
|
docker compose up
|
|
|
|
# Include telegram bot
|
|
docker compose --profile full up
|
|
|
|
# HTTPS mode — Caddy + corporate-CA certs
|
|
docker compose -f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.tls.yml \
|
|
--profile tls up -d
|
|
```
|
|
|
|
See [DEPLOYMENT.md](DEPLOYMENT.md) for full server setup instructions.
|
|
|
|
## Using with Claude Code
|
|
|
|
Open the project in Claude Code. The CLAUDE.md file will guide the AI assistant through setup and analysis workflows.
|
|
|
|
### Analyst Setup
|
|
|
|
1. Visit your instance URL (e.g., https://data.yourcompany.com)
|
|
2. Sign in with your company email
|
|
3. Access data through the API or download parquets for local analysis
|
|
|
|
### Analysis Workflow
|
|
|
|
1. Sync latest data: `curl -X POST https://data.yourcompany.com/api/sync/trigger`
|
|
2. Open Claude Code in your project directory
|
|
3. Ask Claude to analyze your data using DuckDB
|
|
|
|
## Hackathon
|
|
|
|
See [`HACKATHON.md`](HACKATHON.md) for the deploy-and-develop playbook. Per-developer dev VMs are the supported pattern — point your VM at your branch image with `gcloud compute ssh <vm> --command "sudo sed -i 's/^AGNES_TAG=.*/AGNES_TAG=dev-<slug>/' /opt/agnes/.env && sudo /usr/local/bin/agnes-auto-upgrade.sh"`.
|