diff --git a/.agent/workflows/deploy_to_production.md b/.agent/workflows/deploy_to_production.md index 1a136cb..9b6816f 100644 --- a/.agent/workflows/deploy_to_production.md +++ b/.agent/workflows/deploy_to_production.md @@ -7,21 +7,19 @@ **MAIN KNOWLEDGE POINT:** Agents and Users should refer to `.agent/workflows/deployment_reference.md` to understand the full proxy and architecture layout prior to running production debugging. -Follow these steps carefully: +1. **Automated Secret Fetching**: The `deploy_remote.sh` script will automatically pull the production password from the GitBucket Secret Vault if the `GITBUCKET_TOKEN` is available in `/app/.env.gitbucket`. +2. **Sync**: Sync local codebase to `/tmp/cortex-hub/` on the server. +3. **Migrate & Rebuild**: Overwrite production files and run `bash deploy_local.sh` on the server. +4. **Post-Deployment Health Check**: Run the `/frontend_tester` check to verify the UI and AI engine are still functional. -1. Sync the local codebase to a temporary directory on the production server via `rsync`. - * The destination is `/tmp/cortex-hub/`. - * Ensure you exclude `.git`, `node_modules`, `__pycache__`, and audio blobs before migrating. -2. Copy the synced files into the actual project directory replacing the old ones. -3. Run the local deployment script on the production server. - * `cd /home/coder/project/cortex-hub` - * `sudo bash local_deployment.sh` - -### Automated Script Example - -You should use the single bash script stored in the repository, `remote_deploy.sh`, which safely performs all these steps using secure shell arguments. - +### Automated Command ```bash -# Agents MUST explicitly ask the USER for the production password before executing: -REMOTE_PASS='' bash /app/remote_deploy.sh +# This script handles authentication, syncing, and remote rebuilding. +bash /app/deploy_remote.sh +``` + +### Post-Deployment (MANDATORY) +After the script completes, the agent MUST run the `frontend_tester` workflow: +```bash +/frontend_tester ``` diff --git a/.agent/workflows/deployment_reference.md b/.agent/workflows/deployment_reference.md index 5ca7b2e..7991b2d 100644 --- a/.agent/workflows/deployment_reference.md +++ b/.agent/workflows/deployment_reference.md @@ -42,15 +42,15 @@ ### The Scripts -1. **`remote_deploy.sh` (The Triggger)** +1. **`deploy_remote.sh` (The Triggger)** * **Where it runs**: *Locally on your dev machine* * **What it does**: 1. Uses `rsync` over SSH (`sshpass`) to securely copy local workspace (`/app/`) changes onto the production server `192.168.68.113` under a temporary `/tmp/` directory. 2. It specifically excludes massive or unnecessary folders (`.git`, `node_modules`, `__pycache__`). 3. Overwrites the destination project folder (`/home/coder/project/cortex-hub`) taking care to retain system permissions. - 4. SSH triggers the `local_deployment.sh` script centrally on the production server. + 4. SSH triggers the `deploy_local.sh` script centrally on the production server. -2. **`local_deployment.sh` (The Builder)** +2. **`deploy_local.sh` (The Builder)** * **Where it runs**: *Server 192.168.68.113* * **What it does**: 1. Destroys the old running containers. @@ -60,7 +60,7 @@ ### How to Release You or an Agent must safely pass the authentication key into the script from the command line. An Agent should **always prompt the USER** for this password before running it: ```bash -REMOTE_PASS='' bash /app/remote_deploy.sh +REMOTE_PASS='' bash /app/deploy_remote.sh ``` --- @@ -98,7 +98,7 @@ ... and passed safely into the `proxy_set_header Connection $connection_upgrade;` field. ### 3. "Port is already allocated" (Container Fails to Deploy) -**Symptoms**: Backend loads normally, but Frontend acts as `dead` or `Exit 1` silently during `remote_deploy.sh`. +**Symptoms**: Backend loads normally, but Frontend acts as `dead` or `Exit 1` silently during `deploy_remote.sh`. **Root Cause**: Binding collisions on the production host `192.168.68.113`. (e.g., trying to bind Nginx to host port `8000` when another container `python3_11` uses it). **Verification Check**: * Run `docker ps -a` on `192.168.68.113`. diff --git a/.agent/workflows/frontend_tester.md b/.agent/workflows/frontend_tester.md new file mode 100644 index 0000000..c50fd66 --- /dev/null +++ b/.agent/workflows/frontend_tester.md @@ -0,0 +1,44 @@ +--- +description: How to perform automated frontend health checks on production (ai.jerxie.com) +--- + +# Frontend Tester Checklist + +This workflow defines the steps for an AI agent to act as a **Frontend Tester** for the Cortex AI production environment. + +## 🔗 Target URL +- Production: `https://ai.jerxie.com` + +## 🕵️‍♂️ Monitoring Strategy + +### 1. Initial Access & Authentication +- **Step**: Navigate to `https://ai.jerxie.com`. +- **Observation**: Check if redirected to `/login` or OIDC provider. +- **Action**: If stuck at login, request the USER to perform the login. Once done, verify `localStorage` or page content to confirm active session. +- **AI Configuration**: When configuring a new Cortex AI project, fetch AI credentials (TTS/STT/LLM) from the GitBucket private snippet `AI_SNIPPET_ID` (stored in `.env.ai`). + +### 2. Smoke Testing Key Pages +Navigate to each core page and verify they render without crashes: +- **Home**: Check if the hero section and navigation sidebar are visible. +- **Coding Assistant**: Verify the chat input is present. +- **Profile**: Ensure user metadata loads correctly. +- **Settings (Admin)**: Check if system configurations are accessible. + +### 3. Error Observation +- **Console Logs**: Always check for `ERROR` or `Failed to load resource` messages in the browser console. +- **Network Traces**: Look for `4xx` or `5xx` responses in API calls to `https://ai.jerxie.com/api/...`. + +### 4. Bug Reporting Workflow +If an abnormality is found: +1. **Gather Evidence**: Take a screenshot of the UI state and copy the console error. +2. **Back-end Correlation**: Use `run_command` (if access is permitted) to check `journalctl` or backend container logs for matching timestamps. +3. **Report to GitBucket**: + - Fetch the API token from `/app/.env.gitbucket`. + - Create a new issue in `yangyangxie/cortex-hub` using the `gitbucket_api` workflow. + - Title: `BUG: [Short Description]` + - Body: Summary of findings, screenshot proof, and backend log snippet. + - Labels: `bug`, `Urgent` (if production is down). + +## 🚀 Future Automations +- Implement Playwright/Puppeteer scripts for deeper interaction testing (e.g., sending a test chat message). +- Automate periodic health checks via Cron. diff --git a/.agent/workflows/gitbucket_api.md b/.agent/workflows/gitbucket_api.md index 875e900..96935c1 100644 --- a/.agent/workflows/gitbucket_api.md +++ b/.agent/workflows/gitbucket_api.md @@ -69,6 +69,37 @@ rm -rf "$TMP_DIR" ``` +### AI Service Credentials Vault +Store AI provider keys (Gemini, DeepSeek, OpenAI) in a dedicated private snippet (e.g., `.env.ai`). +- **Snippet ID**: `6f583b2e0a6b7297970648c0c323e81d` +- **Keys Included**: `DEEPSEEK_API_KEY`, `GEMINI_API_KEY`, `OPENAI_API_KEY`, `EMBEDDING_API_KEY`, `OIDC_CLIENT_SECRET`. + +## AI Project Management & Task Orchestration +Since some GitBucket API features (like Search and Patch) are limited, use this "Audit Log" pattern for AI-driven development: + +### 1. Feature Initiation (Create Issue) +Start every complex task by creating an issue. This provides a central ID for all future actions. +```bash +# Create the task +curl -H "Authorization: token " \ + -X POST -d '{"title": "Feature: [Name]", "body": "Goal: ...\n\n### Tasks:\n- [ ] Step 1\n- [ ] Step 2"}' \ + https://gitbucket.jerxie.com/api/v3/repos/owner/repo/issues +``` + +### 2. Progress Documentation (Comments) +Instead of updating the issue body (unsupported), add a comment for every major milestone or sub-task completion. +```bash +# Document progress +curl -H "Authorization: token " \ + -X POST -d '{"body": "STT Backend logic implemented in /app/core/stt.py"}' \ + https://gitbucket.jerxie.com/api/v3/repos/owner/repo/issues//comments +``` + +### 3. Orchestration Workflow +- **List All**: `GET /api/v3/repos/owner/repo/issues` to see the current backlog. +- **Detailed Context**: `GET .../issues//comments` to read the history of an ongoing task. +- **Finish**: Post a final summary comment and (optionally) use the browser subagent to close the issue in the UI. + ## Security Best Practices - **Private Only**: Never store credentials in "Public" or "Secret" snippets. - **Rotation**: Update the snippet regularly; agents will automatically pick up the new values. diff --git a/.gitignore b/.gitignore index e70abdd..01b11ed 100644 --- a/.gitignore +++ b/.gitignore @@ -13,4 +13,5 @@ ai-hub/app/config.yaml **/config.yaml data/audio/* -data/* \ No newline at end of file +data/* +.env.gitbucket \ No newline at end of file diff --git a/deploy_remote.sh b/deploy_remote.sh index c1f905b..e7ff0a7 100755 --- a/deploy_remote.sh +++ b/deploy_remote.sh @@ -86,3 +86,5 @@ EOF echo "Done! The new code is deployed to $HOST." +echo "CRITICAL: Run the automated Frontend Health Check now to verify production stability." +echo "Command: /frontend_tester"