Development Setup

Prerequisites

• Python 3.12+
• Node.js 22+
• Docker and Docker Compose (optional)
• uv (Python package manager)

Initial Setup

1. Clone the repository

   git clone https://github.com/bookcard-io/bookcard.git
   cd bookcard
   

2. Install dependencies

   # Install uv if not already installed
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Create virtual environment and install dependencies
   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   uv sync --group dev
   

3. Set up frontend

   cd web
   npm install
   cd ..
   

4. Configure environment

   Create a .env file:

   BOOKCARD_JWT_SECRET=dev-secret-key
   ADMIN_USERNAME=admin
   ADMIN_EMAIL=admin@example.com
   ADMIN_PASSWORD=admin123
   

5. Start development servers

   make dev
   

This starts both the FastAPI backend (port 8000) and Next.js frontend (port 3000).