Basjoo AI Customer Support Platform

Basjoo is composed of three main layers: a FastAPI backend, a Next.js admin dashboard, and an embeddable widget.

Backend

Built with FastAPI, the backend manages:

• Auth: Admin routes under /api/admin.
• V1 APIs: Public endpoints for chat (/api/v1/chat), agent configuration, sessions, and quotas.
• Admin Routers: Protected endpoints for URL ingestion, file uploads, and index rebuilding.
• Core Domains: Agent configuration, knowledge sources (URLs/Files), indexing (via Qdrant), chat sessions, and scheduling.

Frontend

A Next.js application located in frontend-nextjs/ providing the admin dashboard and management interfaces.

Widget

A self-contained component (BasjooWidget.tsx) that can be embedded in any website. It automatically detects the apiBase, fetches public configuration, and handles streaming chat replies via SSE.

For a fresh Ubuntu or Debian server, you can perform an automatic deployment using a single command. This script handles the setup of the necessary Docker containers.

Automatic deployment on a blank server:

curl -fsSL https://raw.githubusercontent.com/haoyiyin/basjoo/main/install-deploy.sh | sudo sh

Deployment from a local repository checkout: If you have already cloned the repository locally, run the script from the root directory:

sudo sh install-deploy.sh

After completion, the script will provide the Admin Dashboard URL. The first user to register an account on the new deployment will be designated as the workspace super administrator.

To ensure existing widget embeds continue working after a redeployment or server migration, you must preserve the backend data volume (mounted at /app/data) and the specific agent ID.

Recommended Workflow

1. Back up /app/data/basjoo.db and /app/data/.agent_id.
2. Preserve the volume mounted at /app/data.
3. If migrating to a new server and you know the old agentId, set the DEFAULT_AGENT_ID environment variable before the first boot.

Migration Configuration

Use the following environment variable pattern in your .env file:

SECRET_KEY=
DEFAULT_AGENT_ID=agt_123456789abc

Warning: If the data volume is lost and the agentId is unknown, existing widget embeds cannot be recovered automatically.

# Example .env snippet for migration
SECRET_KEY=
DEFAULT_AGENT_ID=agt_123456789abc

If you prefer to run the components directly on your host machine, follow these steps for each service.

Backend (FastAPI):

cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python3 main.py

Check backend health with: curl http://localhost:8000/health

Frontend (Next.js):

cd frontend-nextjs
npm install
npm run dev

Widget:

cd widget
npm install
npm run dev

Default Dev Ports:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• Qdrant: http://localhost:6333
• PostgreSQL: 127.0.0.1:5432
• Redis: 127.0.0.1:6379

You can run the backend, frontend, and widget components separately in a local development environment.

# 1. Backend setup
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python3 main.py

# Check health: curl http://localhost:8000/health

# 2. Frontend setup
cd frontend-nextjs
npm install
npm run dev

# 3. Widget setup
cd widget
npm install
npm run dev

Backend tests are located in backend/tests/. The test environment uses BASJOO_TEST_MODE=1 and an isolated SQLite database in backend/.pytest_dbs/.

Commands:

Run all tests:

cd backend
pytest

Run a specific test file:

pytest tests/test_api.py

Run a specific test case:

pytest tests/test_api.py::test_name

Basjoo can be deployed using Docker Compose profiles depending on your environment.

Development stack: Use this for local development with permissive CORS and local API URLs.

docker compose --profile dev up -d

Production-style stack: Use this for stable, production-like environments. The production profile expects persistent backend data to be mounted under /app/data and uses SERVER_DOMAIN to enforce canonical host access via nginx.

docker compose --profile prod up -d

Useful Docker commands:

• View logs: docker compose logs -f backend-dev frontend-dev nginx
• Rebuild specific services: docker compose --profile dev up -d --build backend-dev frontend-dev
• Run stability check: bash scripts/prod_stability_check.sh

Basjoo can be deployed using Docker Compose or a specialized deployment script.

One-click Deployment (Ubuntu/Debian): Use the install-deploy.sh script to automatically install Docker/Compose, clone the repository, sync branches, and initialize .env files.

Docker Compose: Use docker-compose.yml as the primary orchestration entry point.

Nginx Configuration Notes:

• client_max_body_size is set to 12m to allow large requests to reach the backend for proper JSON error handling.
• HTTPS is enabled automatically if readable certificates/keys exist in the ./ssl directory. When enabled, HTTP requests on port 80 are redirected to 443.
• You can set SERVER_DOMAIN to restrict Nginx to respond only to a specific domain; other hosts will receive a 444 response (except for /health).

For Ubuntu and Debian systems, you can use the install-deploy.sh script to perform a production installation. This script automates:

• Installing Docker and Docker Compose.
• Cloning the repository.
• Syncing the repository to the chosen remote branch.
• Deploying the application via Docker Compose.

./install-deploy.sh

Basjoo uses pytest for backend testing. When running tests, BASJOO_TEST_MODE=1 is set, and isolated SQLite databases are used under backend/.pytest_dbs/ to prevent interference with production data.

# Run all tests
cd backend
pytest

# Run a specific file
pytest tests/test_api.py

# Run a single test case
pytest tests/test_api.py::test_name