Shared notebooks and reusable utilities for the BookPath project.
- Frontend: Next.js in
Nextjs_kanon/book-insight-ui, currently hosted on Vercel fromkanon-dayo/book-insight(main). - Backend: FastAPI in
api, currently hosted on Render fromsidmirpuri/bookpath(add-book-recommender-app). - Recommendations:
all-MiniLM-L6-v2compares the user's goal with the precomputed book embeddings inapi/data/book_embeddings.npy. - Data:
api/data/exercise_data.csvis the current book catalog. There is no external database; the CSV and NumPy embeddings are packaged with the API.
The current Vercel and Render deployments are connected to the repositories
and branches listed above. Merging another branch into sidmirpuri/bookpath
main will not update those deployments until their Git settings are changed
to deploy from this repository and branch.
Docker runs the Next.js frontend and FastAPI recommendation service without requiring Node.js or Python dependencies to be installed on the host machine. Install and start Docker Desktop before continuing, then verify that its engine is available:
docker psRun all commands below from the repository root.
| Service | Address |
|---|---|
| Next.js frontend | http://localhost:3000 |
| FastAPI service | http://localhost:8000 |
| FastAPI health check | http://localhost:8000/health |
Start the frontend and API together with one command:
docker compose up --buildThe first run downloads the container images, Python dependencies, and embedding model, so it can take a few minutes. Compose waits for the API health check before starting Next.js. When both services are ready, open http://localhost:3000.
Keep the terminal open while using the application. Press Ctrl+C to stop the
services, then remove the stopped containers and network:
docker compose downThe web_node_modules Docker volume keeps frontend dependencies outside the
host filesystem. To remove that volume and force a completely fresh dependency
installation, run docker compose down --volumes.
If ports 3000 or 8000 are already in use, choose different host ports:
WEB_PORT=3001 API_PORT=8001 docker compose up --buildThe commands below run the same services separately when individual container logs or lifecycle control are useful. Keep two terminal windows open.
In the first terminal:
docker build -t book-insight-api ./api
docker run --rm \
--name book-insight-api \
-p 8000:8000 \
-e ALLOWED_ORIGINS=http://localhost:3000 \
book-insight-apiThe first build downloads the Python dependencies and embedding model, so it
can take a few minutes. Wait for Application startup complete, then verify
the service from another terminal:
curl -sS http://localhost:8000/healthThe expected response is:
{"status":"ok"}An optional recommendation request can be tested with:
curl -sS \
-X POST http://localhost:8000/recommend \
-H 'Content-Type: application/json' \
-d '{"goal":"Learn startup finance","readingLevel":"beginner"}'Keep the API running. In the second terminal, from the repository root:
docker run --rm -it \
--name book-insight-web \
-p 3000:3000 \
-v "$PWD/Nextjs_kanon/book-insight-ui:/app" \
-v /app/node_modules \
-w /app \
node:24-bookworm-slim \
sh -lc 'npm ci && npm run dev -- --hostname 0.0.0.0'Wait for Next.js to report that it is ready, then open http://localhost:3000. The browser will send recommendation requests to the API running on port 8000.
To run linting, TypeScript checks, and the production build without installing Node.js locally:
docker run --rm \
-v "$PWD/Nextjs_kanon/book-insight-ui:/app" \
-v /app/node_modules \
-w /app \
node:24-bookworm-slim \
sh -lc 'npm ci && npm run lint && npm run build'Docker does not require Node.js to be installed on the host. Teammates who prefer to run the frontend directly on macOS can install the Node.js 24 LTS release with Homebrew:
brew install node@24
export PATH="$(brew --prefix node@24)/bin:$PATH"
node --version
npm --versionTo make Node.js available in future zsh sessions, add the following line to
~/.zshrc, then restart the terminal or run source ~/.zshrc:
export PATH="$(brew --prefix node@24)/bin:$PATH"From the repository root, enter the frontend directory, then install and run the frontend directly:
cd Nextjs_kanon/book-insight-ui
npm ci
npm run devPress Ctrl+C in each terminal. The --rm option removes each container after
it stops. If either container is still running, stop it explicitly:
docker stop book-insight-web book-insight-apiIf Docker reports that it cannot connect to docker.sock, start Docker Desktop
and wait for the engine to become ready. On macOS, allow Terminal to communicate
with Docker Desktop if the operating system asks for permission.
- clone the repository
- create the virtual environment
pyenv virtualenv 3.10.6 bookpath
pyenv local bookpath
- install the project in editable mode with its dependencies
python -m pip install -e .
Editable installation is the workflow taught in Day 28 MLOps: edits to the
bookpath/ package are immediately available to notebooks and scripts in the
same environment.
NLTK is required for the optional lemmatization experiment. Its WordNet data is a separate, one-time download. Run this in the same notebook kernel:
from bookpath.nltk_resources import download_wordnet_resources
download_wordnet_resources()Keep raw data unchanged. Optional NLP variants must be created in separate columns and never overwrite the original text.