Prerequisites¶

Before self-hosting Jinbocho, ensure your server meets the following requirements.

Operating System¶

Jinbocho runs on: - Linux (Ubuntu 22.04 LTS or later, Debian 12+) — recommended for a VPS or home server/NAS - 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

Git¶

Required to clone the installation repository.

macOS:

brew install git

Linux/WSL2:

sudo apt install git

Verify:

git --version

PostgreSQL Client (psql)¶

Optional but recommended for inspecting your database.

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: Pass it as --google-books-key to the install script, or set GOOGLE_BOOKS_API_KEY in envs/catalog-service.env

Clone the Installation Repository¶

Self-hosting only requires one repository — it contains the Docker Compose files, env templates, and install scripts, and it clones the frontend for you:

git clone https://github.com/jinbocho/jinbocho-install-community-v1.git
cd jinbocho-install-community-v1

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 "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, go to Production Deployment to install Jinbocho.