local-development

# Airweave Local Development Use this sub-skill when a future Airweave task needs the local Docker stack running or diagnosed. It owns stack bootstrap, restart/recreate/destroy decisions, `.env` seeding, service profiles, port checks, and health recovery. Do not use this sub-skill for backend endpoint details, connector implementation, frontend page logic, MCP transport behavior, or Monke connector orchestration. After the stack is healthy, route search, collection, source-connection, connect-session, and webhook workflows to `../backend-api/SKILL.md`. ## Safe operating rules 1. Work from an explicit repository root. The bundled helper accepts `--repo-root /path/to/airweave` and works from any current directory. 2. Prefer `status` before mutation: ```bash bash skills/disco/airweave/sub-skills/local-development/scripts/local-stack.sh \ --repo-root "$AIRWEAVE_REPO" status ``` 3. A plain `start` is state-preserving: it seeds `.env` only when needed, starts missing/stopped services, and reuses running containers instead of deleting data. 4. Use `restart` for already-created containers when you want to preserve Postgres/Redis/Vespa volumes. 5. Use `recreate` only when container state is stale or service definitions changed; it removes compose containers and volumes, then starts fresh from the current `.env`. 6. Use `destroy` only with explicit user intent. It removes compose containers and Docker volumes; it does not intentionally edit `.env` or purge manually managed host files. ## Common commands ```bash # Fresh or reuse-safe start, including backend, frontend, connect widget, Vespa, Temporal, Redis, Postgres, Svix. bash skills/disco/airweave/sub-skills/local-development/scripts/local-stack.sh \ --repo-root "$AIRWEAVE_REPO" start # Backend/service stack without frontend UI. bash skills/disco/airweave/sub-skills/local-development/scripts/local-stack.sh \ --repo-root "$AIRWEAVE_REPO" start --skip-frontend # Preserve data; restart existing containers and rerun health checks. bash skills/disco/airweave/sub-skills/local-development/scripts/local-stack.sh \ --repo-root "$AIRWEAVE_REPO" restart # Recreate containers and compose volumes from current repo config. bash skills/disco/airweave/sub-skills/local-development/scripts/local-stack.sh \ --repo-root "$AIRWEAVE_REPO" recreate # Destructive cleanup; add --yes for noninteractive confirmation. bash skills/disco/airweave/sub-skills/local-development/scripts/local-stack.sh \ --repo-root "$AIRWEAVE_REPO" destroy ``` Equivalent environment toggles are supported for automation: `NONINTERACTIVE=1`, `SKIP_FRONTEND=1`, `SKIP_CONNECT=1`, `SKIP_LOCAL_EMBEDDINGS=1`, `ENABLE_DOCLING=1`, `VERBOSE=1`, and `QUIET=1`. ## Startup decisions - Fresh checkout with no `.env`: the helper copies `.env.example`, generates missing `ENCRYPTION_KEY`, `STATE_SECRET`, `SVIX_JWT_SECRET`, `FIRST_SUPERUSER_PASSWORD`, and `POSTGRES_PASSWORD`, fills safe local defaults such as `FIRST_SUPERUSER=admin@example.com`, `POSTGRES_USER=airweave`, `SKIP_AZURE_STORAGE=true`, `STORAGE_BACKEND=filesystem`, and `SPARSE_EMBEDDER=fastembed_bm25`. - Embeddings: OpenAI keys prefer `openai_text_embedding_3_small` with 1536 dimensions and skip the local embeddings container. Mistral keys prefer `mistral_embed` with 1024 dimensions. No API key on a freshly seeded env uses `local_minilm` with 384 dimensions and starts the local embeddings container. An existing `.env` is not overwritten except for missing required values. - Reusing containers: if Airweave containers already run, `start` reports status instead of recreating them. If containers exist but are stopped, `start` brings them back up and runs health checks. - Optional profiles: `--skip-frontend`, `--skip-connect`, `--skip-local-embeddings`, and `--enable-docling` map to the compose profiles for frontend, connect widget, local embeddings, and Docling OCR. ## Expected local service surface See `references/local-stack.md` for the service graph, ports, startup modes, and health commands. The primary expected endpoints are: - Backend API: `http://localhost:8001`, health at `/health` and readiness at `/health/ready` - Frontend UI: `http://localhost:8080` unless skipped - Connect widget: `http://localhost:8082` unless skipped - Vespa document/query API: `http://localhost:8081`, config server on `19071` - Temporal gRPC/UI: `7233`, `8233`, and `http://localhost:8088` - PostgreSQL: `localhost:5432`; Redis: `localhost:6379`; Svix: `http://localhost:8071` - Local embeddings: host `9878` when `DENSE_EMBEDDER=local_minilm`; Docling: `5001` only when enabled ## Verification hooks For command-level checks before a real stack run: ```bash bash -n skills/disco/airweave/sub-skills/local-development/scripts/local-stack.sh bash skills/disco/airweave/sub-skills/local-development/scripts/local-stack.sh --help bash skills/disco/airweave/sub-skills/local-development/scripts/local-stack.sh --repo-root "$AIRWEAVE_REPO" status ``` For a backend-native smoke after the stack is healthy and a Python 3.13 backend environment with `pytest`/`pytest-asyncio` is active: ```bash cd "$AIRWEAVE_REPO/backend" TEST_ENV=local python -m pytest tests/e2e/smoke/test_storage_backend.py -q ``` This storage smoke verifies the backend health endpoint, stub-source sync, ARF files, manifests, and entity files. If it fails because `stub` is unavailable, check whether internal sources are enabled for the local test environment before treating storage as broken. ## Troubleshooting entry points - Docker or Compose missing, daemon down, or port conflicts: `references/troubleshooting.md#docker-compose-and-port-failures` - Missing or invalid env values, including `STATE_SECRET` and `SVIX_JWT_SECRET` length validation: `references/troubleshooting.md#environment-and-settings-failures` - Vespa init or schema dimension mismatch: `references/troubleshooting.md#vespa-failures` - Backend, Temporal worker, Svix, or storage smoke failures: `references/troubleshooting.md#backend-worker-svix-and-storage-failures`