Self-hosting bhasha-js

The whole BhashaJS stack — backend API, management dashboard, MongoDB — is open source and ships with a docker-compose.yml. You can run it on any server with Docker installed.

What you'll need

  • A VPS with Docker + Docker Compose installed (any cheap droplet: Hetzner, DigitalOcean, Linode work).
  • A domain name pointing at the server's IP.
  • A Google Gemini API key (for AI translation features). Get one free here.

1. Clone the repo

git clone https://github.com/santoshpant23/bhashajs.git
cd bhashajs

2. Configure environment

cp .env.example .env
nano .env

Fill in the required values:

  • DOMAIN — the domain you'll serve on, e.g. app.example.com (its DNS must point at this server). Caddy provisions HTTPS for it automatically. Leave it unset to serve on localhost for local testing — note that localhost uses Caddy's own self-signed certificate, so your browser shows a one-time security warning (expected; click through, or run caddy trust to install the local CA on the host).
  • JWT_SECRET — generate with openssl rand -hex 32
  • APP_URL — the public URL of your dashboard, e.g. https://app.yourdomain.com. Used to build invite-email links. Required in production — if left as the example.com placeholder the server refuses to boot.
  • GEMINI_API_KEY — your Gemini API key
  • MONGO_ROOT_PASSWORD — strong random password (used by the bundled MongoDB)
  • CORS_ORIGIN — comma-separated list of frontend origins, e.g. https://bhashajs.com,https://app.bhashajs.com

3. Deploy

chmod +x deploy.sh
./deploy.sh

That's the whole deploy. It brings up the stack (bundled MongoDB + the API + Caddy) and Caddy obtains a Let's Encrypt certificate for your DOMAIN automatically — and renews it on its own. No certbot, no cert paths, no config to edit. Give it a few seconds on first boot while the certificate is issued.

Note: the hosted service at api.bhashajs.com runs the same Caddy auto-HTTPS approach, via a slimmer server-only stack (docker-compose.prod.yml) you don't need when self-hosting.

4. Verify

  • https://your-domain.com/api/health returns {"success": true}
  • https://your-domain.com shows the dashboard. Register an account.

5. Point the SDK at your URL

<I18nProvider
  projectKey="bjs_..."
  apiUrl="https://your-domain.com/api"
  defaultLang="en">
  <App />
</I18nProvider>

What's running

  • Backend API (Express + MongoDB) — at :5000 behind Caddy
  • Dashboard (React + Vite SPA) — static files served by Caddy
  • MongoDB 7 — local container with persistent volume
  • Caddy — automatic TLS (Let's Encrypt) + reverse proxy, certs persisted in a volume

Backups

MongoDB data lives in the named Docker volume mongo_data. Dump it with mongodump:

docker compose exec mongo mongodump --archive=/data/db/backup.archive
docker cp bhashajs-mongo-1:/data/db/backup.archive ./backups/

Updates

git pull
docker compose down
docker compose up --build -d