basjoo

System requirements

Basjoo runs as a set of Docker containers. All LLM inference and embedding calls are made to external APIs (OpenAI, DeepSeek, Anthropic, Gemini, Jina, SiliconFlow), so no GPU is required.

Automatic deployment

For a blank Ubuntu or Debian server, run:

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

If you already have this repository checked out locally, you can also run:

sudo sh install-deploy.sh

Manual deployment

Option 1: Docker Compose

Development stack:

docker compose --profile dev up -d

Production-style stack:

docker compose --profile prod up -d

Useful Docker commands:

docker compose logs -f backend-dev frontend-dev nginx
docker compose --profile dev up -d --build backend-dev frontend-dev
bash scripts/prod_stability_check.sh

Default dev ports:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• R2R: http://localhost:7272
• PostgreSQL: 127.0.0.1:5432
• Redis: 127.0.0.1:6379

The dev frontend and backend ports are bound as 3000:3000 and 8000:8000, so they are reachable from other devices that can access the host.

Docker Compose watch mode (dev)

docker compose --profile dev up --watch

Deployment notes

• docker-compose.yml is the main orchestration entrypoint.
• install-deploy.sh is the one-command production installer/deployer for Ubuntu and Debian. It can auto-install Docker/Compose, clone the repo, and force-sync an existing clone to the chosen remote branch before deploying.
• The active frontend service is frontend-nextjs, not the legacy frontend/ directory.
• nginx is configured with client_max_body_size 12m so oversized requests can reach the backend and return JSON errors instead of nginx HTML errors.
• Optional HTTPS is enabled only when readable certificate and key files exist in ./ssl.
• When certificates are present, nginx serves HTTPS on port 443 and redirects HTTP requests on port 80 to HTTPS automatically.
• SERVER_DOMAIN can be set for the nginx service to enforce a canonical hostname. When set, nginx serves only that host, rejects direct IP or unexpected Host access with nginx 444, and keeps /health available for load balancer probes.
• If SERVER_DOMAIN is not set, nginx keeps accepting requests by the incoming host as before.
• Backend responses that bypass standard middleware should still apply CORS headers so embedded widget requests do not fail cross-origin.
• The backend persists the default widget agent ID to /app/data/.agent_id. As long as the backend data volume is preserved, existing widget embed codes keep working after redeployments.
• If you know an older widget agent ID that must keep working, set DEFAULT_AGENT_ID=agt_xxxxxxxxxxxx before first boot of the new deployment.
• Avoid docker compose down -v or deleting the backend data volume unless you are intentionally rotating widget/embed identity.
• The one-command installer only force-resets repository files; it does not delete Docker named volumes, so /app/data persistence remains intact across redeployments.

Preserving existing widget embeds across redeployments

Recommended production workflow:

1. Preserve the backend data volume mounted at /app/data.
2. Redeploy with docker compose --profile prod up -d --build.
3. If you are migrating to a new server and know the old widget agentId, set DEFAULT_AGENT_ID before starting the backend.
4. Back up at least /app/data/basjoo.db and /app/data/.agent_id.

Example .env snippet for migration:

SECRET_KEY=
DEFAULT_AGENT_ID=agt_123456789abc

If the old data volume is lost and the old agentId is unknown, old widget embeds cannot be recovered automatically because the embed code references the previous agent ID directly.

Playground and AI configuration

The Playground lets admins test replies, inspect retrieval behavior, and adjust model/provider settings from the same workflow.

System settings and widget appearance

System Settings covers language/theme preferences, widget appearance, embed behavior, and other operational controls.

Option 2: Run services locally

Backend

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

Backend health check:

curl http://localhost:8000/health

Frontend

cd frontend-nextjs
npm install
npm run dev

Widget

cd widget
npm install
npm run dev

Environment and configuration

The backend reads settings from environment variables and .env via pydantic-settings.

Important runtime settings used in the current codebase include:

• DATABASE_URL
• REDIS_URL
• R2R_API_URL
• SECRET_KEY
• SECRET_KEY_FILE
• DEFAULT_AGENT_ID
• JINA_API_KEY
• DEEPSEEK_API_KEY
• ALLOWED_ORIGINS
• ALLOWED_METHODS
• ALLOWED_HEADERS
• RATE_LIMIT_PER_MINUTE
• RATE_LIMIT_BURST_SIZE
• LOG_LEVEL
• SERVER_DOMAIN
• ENCRYPTION_KEY (optional; auto-generated and persisted if missing)
• ENCRYPTION_KEY_FILE (default /app/data/.encryption_key)
• REQUIRE_SECRET_KEY (set true in production to reject insecure secret keys)

Notes:

• If SECRET_KEY is missing or insecure, the backend generates one and persists it to SECRET_KEY_FILE.
• DEFAULT_AGENT_ID can be used to restore or pin a known widget agent ID during migrations; see the deployment section below for the preservation workflow.
• If ENCRYPTION_KEY is not set, the backend auto-generates a Fernet key and persists it to ENCRYPTION_KEY_FILE; stored provider API keys are encrypted with this key.
• cors_allow_null_origin (boolean, default false) controls whether Origin: null (e.g., file:// widget preview) receives wildcard CORS headers. Off by default for security.
• SERVER_DOMAIN is consumed by the nginx service in the production compose profile to enforce a canonical host and block direct IP/other-host access.
• The dev compose profile sets permissive CORS and local API URLs by default.
• The production compose profile expects mounted persistent backend data under /app/data.

API surface at a glance

Examples of backend endpoints present in the codebase:

• /health
• /api/admin/login
• /api/admin/register
• /api/v1/chat
• /api/v1/chat/stream
• /api/v1/agent:default
• /api/v1/urls:create
• /api/v1/urls:list
• /api/v1/urls:refetch
• /api/v1/index:rebuild
• /api/v1/index:status