How to self-host Jemah

For in-app help, see Study self-hosted setup.

Jemah is a self-hosted research studio — Writer, Study, Learner, and Notes on infrastructure you control. This guide walks through a first-time operator setup on a fresh clone.

What you need

Writer runs with Postgres alone — Qdrant and the embedder are optional for papers and notes.

1. Base environment

1. Clone the repo and copy .env.example to .env.

2. Set Postgres credentials, Weblate secrets, and LLM keys in .env.

3. Bootstrap services:

   ./scripts/bootstrap-env.sh --live-tm
   

   For the full stack including ML and the operator portal:

   ./scripts/setup-all.sh --ml --portal --live-tm
   

4. Confirm health endpoints:

   • Weblate: /healthz/
   • Suggester: :8001/health
   • Embedder: :8002/health
   • Writer API: :8003/health

2. Writer UI + API

Production uses one public hostname for the Next.js shell and FastAPI backend. Before building writer-web:

NEXT_PUBLIC_WRITER_URL=https://jemah.example.net

The Next.js app serves the hub at /, Writer at /papers, Learner at /learn, and Notes at /notes.

3. Sign-in and access

Library, notes, and operations require a signed-in account. Set WRITER_AUTH_REQUIRED=1 in production. Edge HTTP basic auth is optional — app-layer auth still protects API routes.

Optional: configure Google OAuth for household sign-in (see operator docs for UNIFIED_LOGIN).

4. Optional profiles

Start with Writer + Postgres; add profiles when you need translation or semantic search.

5. Verify the deployment

1. Open / — home page loads with product cards.
2. Create a paper at /papers — Writer workspace opens.
3. Upload a PDF to Library — source status reaches ready.
4. Check GET /health — Postgres up; llm_configured reflects your keys.

Next steps

• Run a literature review with real references
• Choose the right learning surface: Study vs Learner
• Compare Jemah to tools you already use: Notion · Obsidian · NotebookLM
• Subscribe to the blog RSS feed or Atom feed for updates