Development Guide

It’s recommended to complete the Quick Start once before doing local development to ensure the basic environment and .env configuration are usable.

Frontend

Dependencies

1. Node.js >= 18
2. npm (or pnpm / yarn; examples use npm by default)

# For Ubuntu Server 24.04
sudo apt update
sudo apt install -y nodejs npm

# For TencentOS Server 4.4
sudo dnf install -y nodejs npm

Recommendation: use nvm to manage Node versions and keep them consistent.

Installation & CLI Debugging

# Initialize (first run only; installs dependencies under client/tagentic-client-vue)
make init_client

# Build (artifacts output to server/static/app)
make client
# After starting the backend service (see Backend section), you can access the built assets directly in the browser

Common Issues (Frontend)

• Node version too low: upgrade to Node 18+; check with node -v.
• Slow or failed dependency installation: configure a mirror registry or retry; use pnpm if needed.
• Blank page after build: ensure the backend is running, static paths are correct, and check the browser console for CORS or 404 errors.

Backend

The backend runs in a container by default (Sanic + Python); no need to install Python on the host. The following commands assume Docker/Compose are available.

Debugging (CLI)

# 1. Complete all steps in [Deploy] (including preparing deploy/default/.env)
# 2. Sync the .env used for deployment to server/ (so the debug container can read it)
cp deploy/default/.env server/.env

# 3. Start the server debug container (bind-mount mode; no need to rebuild the image)
sudo make debug
# After success, the backend runs with mounted files so your local code changes take effect immediately

Port: the backend listens on 8000 by default (container mapped to the host). Static assets: frontend build artifacts are in server/static/app, served directly by the backend in debug mode.

VS Code Quick Debug

Use the Command Palette (Cmd/Ctrl + Shift + P), type Preferences: Open Keyboard Shortcuts (JSON), and add:

{
  "key": "cmd+r",
  "command": "workbench.action.terminal.sendSequence",
  "args": { "text": "make debug\n" }
}

Logs & Observability

# View logs (compose-based deployment)
sudo make logs
# Or directly via docker compose
sudo docker compose -f deploy/default/compose.yaml logs -f

# Check container status/ports
sudo docker ps
ss -tulpen | grep 8000 || sudo lsof -i:8000

Common Issues (Backend)

• .env parsing error (python-dotenv could not parse) APP_CONFIGS must be single-line valid JSON with no trailing commas or comments.
• “Unknown application” page The TC_SECRET_ID/KEY used lack permission for the app; grant access on the platform side or use credentials with the required permissions.
• Voice input unavailable Tencent Cloud ASR real-time recognition is not enabled, or the browser is not using HTTPS.

Makefile Quick Reference