start-genai-backend · diff
git:20260203.566fc00 to git:20260304.0624edd
43 added, 75 removed. Audit A to B.
---
name: start-genai-backend
- description: Start the GenAI Engine backend server and frontend UI. Use when you need to launch the API server at localhost:3030 and the frontend at localhost:3000.
- allowed-tools: Bash, Read
+ description: Start the GenAI Engine backend server and frontend UI. Use when you need to launch the API server and the frontend locally.
+ allowed-tools: Bash, Read, Task
---
# Start GenAI Engine Backend Server
- ## Pre-flight Checks
-
- ### 1. Verify PostgreSQL is running
- ```bash
- cd ./genai-engine
- docker compose ps db
- ```
+ ## Step 1 — GPT Key Gate
- If not running or unhealthy, start it:
- ```bash
- docker compose up -d db
- sleep 3
- docker compose ps db
- ```
+ Use the Read tool to read `./genai-engine/.env`.
- ## Environment Variables
+ Check that `GENAI_ENGINE_OPENAI_GPT_NAMES_ENDPOINTS_KEYS` is present and has a non-empty value (not just `GENAI_ENGINE_OPENAI_GPT_NAMES_ENDPOINTS_KEYS=` with nothing after the `=`).
- Set ALL of these environment variables before starting:
+ If the value is missing or empty:
+ - **STOP immediately. Do not proceed to Step 2.**
+ - Tell the user: "Setup cannot continue. Please open `genai-engine/.env` and set `GENAI_ENGINE_OPENAI_GPT_NAMES_ENDPOINTS_KEYS` using the format: `MODEL_NAME::ENDPOINT_URL::API_KEY` (e.g. `gpt-4o::https://api.openai.com/::sk-...`). Run the skill again once the key is set."
- ```bash
- # Database
- export POSTGRES_USER=postgres
- export POSTGRES_PASSWORD=changeme_pg_password
- export POSTGRES_URL=localhost
- export POSTGRES_PORT=5432
- export POSTGRES_DB=arthur_genai_engine
- export POSTGRES_USE_SSL=false
+ ## Step 2 — Delegate Startup to Bash Sub-Agent
- # Application
- export PYTHONPATH="src:$PYTHONPATH"
- export GENAI_ENGINE_SECRET_STORE_KEY="some_test_key"
- export GENAI_ENGINE_ENVIRONMENT=local
- export GENAI_ENGINE_ADMIN_KEY=changeme123
- export GENAI_ENGINE_INGRESS_URI=http://localhost:3030
- export GENAI_ENGINE_ENABLE_PERSISTENCE=enabled
- export ALLOW_ADMIN_KEY_GENERAL_ACCESS=enabled
- ```
+ Only proceed here if Step 1 passed. Spawn a Task sub-agent with subagent_type="Bash" and the following self-contained prompt:
- ## LLM Provider Configuration
+ ---
+ Start the GenAI Engine backend and frontend. Report success or failure for each step.
- Load LLM configuration from the `.env` file:
+ **Step 1 — Verify PostgreSQL is running:**
```bash
- source ./genai-engine/.env
- export OPENAI_API_KEY
- export GENAI_ENGINE_OPENAI_PROVIDER
- export GENAI_ENGINE_OPENAI_GPT_NAMES_ENDPOINTS_KEYS
+ cd genai-engine && docker compose ps db
```
-
- If `OPENAI_API_KEY` is not set in `.env`, inform the user they need to add it for LLM features to work.
-
- ## Start Backend Server
-
- Run the server in the background so it doesn't block:
+ If not running or unhealthy, start it:
```bash
- cd ./genai-engine
- poetry run serve
+ cd genai-engine && docker compose up -d db && sleep 3
```
- Server will be available at:
- - **API**: `http://localhost:3030`
- - **Swagger Docs**: `http://localhost:3030/docs`
- - **Health Check**: `http://localhost:3030/health`
-
- ## Start Frontend
+ **Step 2 — Start the backend server in the background:**
```bash
- cd ./genai-engine/ui
- yarn install
- yarn dev
+ cd genai-engine && \
+ set -a && source .env && set +a && \
+ export POSTGRES_USER=postgres \
+ POSTGRES_PASSWORD=changeme_pg_password \
+ POSTGRES_URL=localhost \
+ POSTGRES_PORT=5432 \
+ POSTGRES_DB=arthur_genai_engine \
+ POSTGRES_USE_SSL=false \
+ PYTHONPATH="src:$PYTHONPATH" \
+ GENAI_ENGINE_SECRET_STORE_KEY="some_test_key" \
+ GENAI_ENGINE_ENVIRONMENT=local \
+ GENAI_ENGINE_ADMIN_KEY=changeme123 \
+ GENAI_ENGINE_ENABLE_PERSISTENCE=enabled \
+ ALLOW_ADMIN_KEY_GENERAL_ACCESS=enabled && \
+ poetry run serve &
```
- Frontend will be available at: `http://localhost:3000`
-
- ## Authentication
-
- To make API requests, use the admin key as a Bearer token:
- ```
- Authorization: Bearer changeme123
+ **Step 3 — Wait for the backend to become healthy:**
+ ```bash
+ sleep 5 && curl -s -H "Authorization: Bearer changeme123" http://localhost:3030/health
```
- ## Verification
-
- After starting, verify the server is running:
+ **Step 4 — Start the frontend and capture the URL:**
```bash
- curl -s -H "Authorization: Bearer changeme123" http://localhost:3030/health
+ cd genai-engine/ui && yarn install && yarn dev 2>&1 | tee /tmp/vite-fe.log &
+ sleep 3 && grep -m1 "Local:" /tmp/vite-fe.log
```
- If successful, report the server is ready. If it fails, check the server logs for errors.
-
- ## Troubleshooting
-
- - If port 3030 is in use: `lsof -i :3030` to find the process
- - If database connection fails: verify PostgreSQL is running with `docker compose ps`
- - If import errors: ensure `PYTHONPATH` includes `src`
+ Report the following when done:
+ - Backend API: the health check URL with `/docs` appended
+ - Frontend: the Local URL that Vite printed
+ - Auth header: `Authorization: Bearer changeme123`
+ ---