Prerequisites
Nanahoshi requires Bun as its runtime and package manager.
Install Bun
Install Bun 1.3.1 or later:curl -fsSL https://bun.sh/install | bash
bun --version
# Should be 1.3.1 or higher
Clone the repository
git clone <repository-url>
cd nanahoshi-v2
Install dependencies
Bun will install all workspace dependencies from the monorepo: Configure environment variables
Create apps/server/.env with the required variables:# Database
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/nanahoshi
# Server
CORS_ORIGIN=http://localhost:3001
# UUIDs and secrets
NAMESPACE_UUID=<your-uuid-v4>
DOWNLOAD_SECRET=<random-secret>
# Authentication
BETTER_AUTH_SECRET=<random-secret>
BETTER_AUTH_URL=http://localhost:3000
# Email (SMTP)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=[email protected]
SMTP_PASSWORD=password
SMTP_FROM=[email protected]
# Optional: Elasticsearch
ELASTICSEARCH_NODE=http://localhost:9200
ELASTICSEARCH_INDEX_PREFIX=nanahoshi
# Optional: Redis
REDIS_HOST=localhost
REDIS_PORT=6379
See packages/env/src/server.ts for the full list of environment variables and validation schema.
Infrastructure
Nanahoshi uses Docker Compose to run PostgreSQL, Redis, Elasticsearch, and Kibana during development.
Start infrastructure
The infra:up command reads environment variables from apps/server/.env:
This starts:
- PostgreSQL (port 5432) — groonga/pgroonga image for full-text search
- Redis (port 6379) — BullMQ job queue backend
- Elasticsearch (port 9200) — book indexing with Sudachi analyzer
- Kibana (port 5601) — Elasticsearch management UI
View logs
Stop infrastructure
Database setup
Nanahoshi uses Drizzle ORM with SQL migrations.
Generate migrations
After editing schema files in packages/db/src/schema/, generate a new migration:
This creates a new SQL file in packages/db/src/migrations/.
Migrations run automatically when the server starts via runMigrations(). You don’t need to apply them manually.
Open Drizzle Studio
Inspect and edit database records in the browser:
Database-only commands
If you need to manage the database container separately:
# Start database only
bun run db:start
# Watch database logs
bun run db:watch
# Stop database
bun run db:stop
# Remove database container
bun run db:down
Running the dev servers
All services
Run the entire stack (server + web frontend) with Turborepo:
This starts:
- Server at
http://localhost:3000 (Hono API)
- Web at
http://localhost:3001 (TanStack Start frontend)
Individual services
Run services separately for faster iteration:
# Server only
bun run dev:server
# Web frontend only
bun run dev:web
# Native app (React Native/Expo)
bun run dev:native
Check and fix issues
This runs biome check --write . which:
- Fixes auto-fixable lint issues
- Formats all code (tabs for indentation, double quotes for JS strings)
- Organizes imports
Biome configuration is in biome.json at the repository root.
Type checking
Run TypeScript type checks across all workspaces:
Building for production
Build all apps and packages:
For production deployment, use Docker Compose:
docker compose up -d --build
