Skip to content

AGENTS.md

Latest commit

 

History

History
41 lines (35 loc) · 4.86 KB

AGENTS.md

File metadata and controls

41 lines (35 loc) · 4.86 KB

zqsdev.com Operations Notes

This file captures the details an operator or automation agent needs to keep the backend healthy.

Systemd service

  • Unit file: /etc/systemd/system/zqs-terminal.service.
  • Runs /opt/zqsdev/bin/zqs-terminal-server as the zqsdev user with WorkingDirectory=/opt/zqsdev.
  • Environment is loaded from /etc/zqsdev/server.env (contains OPENAI_API_KEY, GROQ_API_KEY, GOOGLE_API_KEY, HOST=0.0.0.0, PORT=8787, STATIC_DIR=/opt/zqsdev/static, RUST_LOG=info).
  • Manage lifecycle with sudo systemctl status|restart|stop zqs-terminal.service; logs append to /opt/zqsdev/backend.log (mirrored as ./backend.log) and can also be read with journalctl -u zqs-terminal.service.
  • The service binds to TCP 0.0.0.0:8787 and automatically restarts on failure (Restart=on-failure, RestartSec=5s). Tail the live log with make backend-log.

Public ingress

  • Nginx proxy: /etc/nginx/sites-enabled/api.zqsdev.com forwards HTTPS traffic on api.zqsdev.com to http://127.0.0.1:8787. Keep the /api/* prefix when adding new endpoints.
  • TLS certificate: managed by Certbot (/etc/letsencrypt/live/api.zqsdev.com/), renews automatically.
  • If the proxy breaks, reload Nginx with sudo systemctl reload nginx after adjustments.
  • Netlify rewrite: /api/* → https://api.zqsdev.com/api/:splat. Re-deploy the site after editing netlify.toml.
  • Netlify build pipeline: publish-only (no build command). Always run make build && make test locally so the committed static/ assets and build_id.js are fresh before pushing.

Update workflow

Run make update from the repo root to:

  1. git pull --rebase the repository.
  2. Rebuild the WebAssembly bundle and proxy binaries (make build).
    • make build now chains into make rag, so ensure OPENAI_API_KEY/PINECONE_API_KEY/PINECONE_HOST are exported beforehand. Set SKIP_RAG=1 make build if you intentionally want to skip the RAG refresh (CI boxes without secrets should always do this).
    • The final step in make build is cargo build --release --manifest-path server/Cargo.toml; copy the resulting target/release/zqs_terminal_server to /opt/zqsdev/bin/zqs-terminal-server (use install+rename to avoid “text file busy”) before restarting the service, or the backend will continue serving the previous version even after a restart.
  3. Restart the systemd unit (sudo systemctl restart zqs-terminal.service).

Workflow notes

  • Before handoff, run make build and make test so the maintainer can refresh the live site with confidence.
  • Typical deploy loop: make build && make test, git push (Netlify redeploys the frontend automatically), restart the backend before running any prod tests with sudo systemctl restart zqs-terminal.service, and only then run make autotest BASE_URL=https://www.zqsdev.com to smoke-test production.
  • make update expects a clean working tree; regenerate artifacts, stage them (remember static/build_id.js and static/pkg/**/*), or stash before running so the initial git pull --rebase succeeds.
  • static/build_id.js is now tracked; always include the regenerated file produced by make build in your commits so Netlify's auto-deploys never fall back to the ?build=dev cache-buster.
  • make autotest now fails fast if the deployed build_id.js ever falls back to "dev", ensuring production assets are tied to a real commit.
  • Extend the automated test suite for every new feature or bugfix fix to keep coverage trending upward.
  • Run make rag (or python3 scripts/build_rag.py --skip-pinecone) after editing any static/data/*.json so the SQLite cache mirrors the résumé data even if Pinecone is updated later; make rag-inspect dumps per-source stats if you want to verify the on-disk contents.
  • After deploying, run make autotest BASE_URL=https://www.zqsdev.com (or your target) to ensure /api/ai returns grounded answers with context_chunks metadata.
  • Use the hidden version terminal command (or make version-check) to verify the frontend and backend are running the same release and to grab the GitHub commit links directly from production.
  • If make version-check reports an outdated backend commit, confirm the install/copy step above actually replaced /opt/zqsdev/bin/zqs-terminal-server and then rerun the restart; the API only reports the embedded env!(\"CARGO_PKG_VERSION\") from the running binary.

Versioning

  • The project version lives in VERSION, Cargo.toml, and server/Cargo.toml.
  • Always bump the version number before every commit with python3 scripts/bump_version.py or make bump-version. Do this prior to edits so both frontend and backend artifacts report the new release identifier and the version command stays trustworthy. Immediately stage the updated VERSION file (git add VERSION) and run make ensure-version-bumped to verify the bump is present in your staged changes before committing.