Skip to content

Prerequisites

Before deploying Jinbocho locally or to production, ensure your system meets the following requirements.

Operating System

Jinbocho runs on: - Linux (Ubuntu 22.04 LTS or later, Debian 12+) - macOS (12.0 or later, Intel or Apple Silicon) - Windows 11 (WSL2 with Ubuntu 22.04)

Windows Users: WSL2 Setup

If you're on Windows, use Windows Subsystem for Linux 2:

# Install WSL2 and Ubuntu 22.04
wsl --install -d Ubuntu-22.04

# Inside WSL terminal, verify you have at least 4GB RAM available
free -h

Docker & Docker Compose

Docker Desktop or Docker Engine v20.10+ with Docker Compose v2.20+

Installation

macOS (Homebrew): 

brew install docker docker-compose

Linux (Ubuntu/Debian): 

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
newgrp docker

Verify: 

docker --version      # v20.10.0 or later
docker compose version  # v2.20.0 or later

Python 3.12

All backend services require Python 3.12 or later.

Installation

macOS (Homebrew): 

brew install python@3.12
python3.12 --version

Linux (Ubuntu/Debian): 

sudo apt update
sudo apt install python3.12 python3.12-venv python3.12-dev
python3.12 --version

Windows (WSL2): 

sudo apt update
sudo apt install python3.12 python3.12-venv python3.12-dev

Node.js 18+

Frontend development requires Node.js 18.0.0 or later with npm 9.0.0 or later.

Installation

macOS (Homebrew): 

brew install node@18
node --version   # v18.x.x
npm --version    # 9.x.x or later

Linux/WSL2: 

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
node --version
npm --version

Git

Required for cloning repositories.

macOS: 

brew install git

Linux/WSL2: 

sudo apt install git

Verify: 

git --version

PostgreSQL Client (psql)

Optional but recommended for local database inspection.

macOS: 

brew install postgresql

Linux/Ubuntu: 

sudo apt install postgresql-client

External API Keys (Optional)

For enhanced ISBN lookup functionality, consider obtaining:

Google Books API Key

  • Why: Fallback for ISBN metadata when Open Library is slow
  • Cost: Free tier (100 queries/day)
  • How to get: https://developers.google.com/books/docs/v1/using#APIKey
  • When needed: Set GOOGLE_BOOKS_API_KEY in .env

OpenAI API Key

  • Why: For AI service (tagging suggestions, deduplication)
  • Cost: Pay-as-you-go (optional feature)
  • How to get: https://platform.openai.com/api-keys
  • When needed: Set OPENAI_API_KEY if deploying ai-service

Cloud Accounts (Production Only)

For production deployment on Render + Neon:

Neon.tech Account

  • Purpose: Managed PostgreSQL databases
  • Cost: Free tier (0.5GB, auto-suspend after 30 days inactivity)
  • Sign up: https://neon.tech
  • Why: Better than Render Postgres (which is ephemeral)

Render.com Account

  • Purpose: Hosting backend services + frontend
  • Cost: Free tier (cold starts OK), Starter $7/mo per service
  • Sign up: https://render.com
  • Why: Easy Docker deployment, GitHub integration, built-in SSL

Repositories Checkout

Create a workspace folder and clone all Jinbocho repositories from the GitHub organization:

mkdir -p ~/workspace/jinbocho && cd ~/workspace/jinbocho

# Clone all Jinbocho repositories
git clone https://github.com/jinbocho/jinbocho-infrastructure-v1.git
git clone https://github.com/jinbocho/jinbocho-auth-v1.git
git clone https://github.com/jinbocho/jinbocho-catalog-v1.git
git clone https://github.com/jinbocho/jinbocho-api-gateway-v1.git
git clone https://github.com/jinbocho/jinbocho-ai-v1.git
git clone https://github.com/jinbocho/jinbocho-fe.git

# Verify all services are present
ls | grep jinbocho
# Expected: jinbocho-auth-v1  jinbocho-catalog-v1  jinbocho-api-gateway-v1
#           jinbocho-ai-v1  jinbocho-fe  jinbocho-infrastructure-v1

All repositories live under the jinbocho GitHub organization: https://github.com/jinbocho

System Check Script

Run this to verify all prerequisites are installed:

#!/bin/bash
echo "=== Jinbocho Prerequisites Check ==="
echo "OS: $(uname -s)"
echo "Docker: $(docker --version)"
echo "Docker Compose: $(docker compose version)"
echo "Python: $(python3.12 --version)"
echo "Node.js: $(node --version)"
echo "npm: $(npm --version)"
echo "Git: $(git --version)"
echo "psql: $(psql --version 2>/dev/null || echo 'Not installed')"
echo "✅ All prerequisites installed!"

Next Steps

Once you've verified all prerequisites: 1. Go to Local Development to set up your development environment 2. For production deployment, see Production Deployment