Skip to content

Development Quick Start

Purpose

Set up a Readur development environment in 10 minutes. This guide helps developers contribute to Readur or build custom integrations.

Prerequisites

  • Python 3.10+ installed
  • Node.js 18+ and npm installed
  • PostgreSQL 14+ running locally
  • Redis server installed
  • Git configured with GitHub access
  • 8GB RAM recommended for development

Step 1: Clone and Setup

Clone the repository and create a virtual environment:

# Clone repository
git clone https://github.com/readur/readur.git
cd readur

# Create Python virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install Python dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

Step 2: Database Setup

Create and initialize the database:

# Create database
createdb readur_dev

# Set environment variables
export DATABASE_URL=postgresql://localhost/readur_dev
export REDIS_URL=redis://localhost:6379

# Run migrations
alembic upgrade head

# Create test user
python scripts/create_user.py --username dev --password dev123 --admin

Step 3: Frontend Setup

Install and build frontend assets:

# Navigate to frontend directory
cd frontend

# Install dependencies
npm install

# Start development server
npm run dev

Keep this terminal running - the frontend will auto-reload on changes.

Step 4: Backend Development Server

In a new terminal, start the backend:

# Activate virtual environment
source venv/bin/activate

# Set development environment
export FLASK_ENV=development
export FLASK_DEBUG=1

# Start backend server
python run.py

Step 5: Start Background Workers

In another terminal, start the OCR worker:

# Activate virtual environment
source venv/bin/activate

# Start Celery worker
celery -A readur.worker worker --loglevel=info --concurrency=2

Step 6: Access Development Instance

Your development environment is now running:

  • Frontend: http://localhost:3000 (with hot reload)
  • Backend API: http://localhost:5000
  • API Documentation: http://localhost:5000/api/docs

Login with: - Username: dev - Password: dev123

Development Workflow

Code Structure

readur/
├── backend/          # Python Flask application
│   ├── api/         # REST API endpoints
│   ├── models/      # Database models
│   ├── services/    # Business logic
│   └── workers/     # Background tasks
├── frontend/        # React application
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   └── services/
│   └── public/
├── tests/           # Test suites
└── scripts/         # Development utilities

Making Changes

  1. Create feature branch: 

    git checkout -b feature/your-feature

  2. Backend changes:

  3. Edit Python files
  4. Backend auto-reloads with Flask debug mode

  5. Run tests: pytest tests/

  6. Frontend changes:

  7. Edit React components
  8. Frontend auto-reloads with webpack dev server

  9. Run tests: npm test

  10. Database changes: 

    # Create migration
alembic revision --autogenerate -m "Description"

# Apply migration
alembic upgrade head

Testing

Run All Tests

# Backend tests
pytest tests/ -v

# Frontend tests
cd frontend && npm test

# End-to-end tests
pytest tests/e2e/ --browser chromium

Test Coverage

# Generate coverage report
pytest --cov=readur --cov-report=html
open htmlcov/index.html

Linting

# Python linting
flake8 readur/
black readur/ --check
mypy readur/

# JavaScript linting
cd frontend
npm run lint
npm run format:check

Debugging

Backend Debugging

Using VS Code:

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Flask",
      "type": "python",
      "request": "launch",
      "module": "flask",
      "env": {
        "FLASK_APP": "readur:create_app",
        "FLASK_ENV": "development"
      },
      "args": ["run", "--no-debugger", "--no-reload"],
      "jinja": true
    }
  ]
}

Using pdb:

# Add breakpoint in code
import pdb; pdb.set_trace()

Frontend Debugging

React Developer Tools: 1. Install browser extension 2. Open Developer Tools → Components tab 3. Inspect component state and props

Redux DevTools: 1. Install browser extension 2. View action history and state changes

Database Debugging

# Connect to database
psql readur_dev

# View query logs
export DATABASE_ECHO=true

Local Development Tools

Mock Data

Generate test documents:

python scripts/generate_test_data.py --documents 100

Performance Profiling

# Profile API endpoint
python -m cProfile -o profile.stats run.py

# Analyze results
python -m pstats profile.stats

API Testing

Using httpie:

# Login
http POST localhost:5000/api/auth/login username=dev password=dev123

# Upload document
http POST localhost:5000/api/documents [email protected] \
  "Authorization: Bearer $TOKEN"

Common Development Tasks

Add New API Endpoint

  1. Create route in backend/api/
  2. Add service logic in backend/services/
  3. Write tests in tests/api/
  4. Update OpenAPI schema

Add Frontend Feature

  1. Create component in frontend/src/components/
  2. Add route in frontend/src/routes.js
  3. Create API service in frontend/src/services/
  4. Write component tests

Add Background Task

  1. Define task in backend/workers/tasks.py
  2. Add to task queue in service layer
  3. Write worker tests
  4. Update worker documentation

Troubleshooting

Dependencies Won't Install

# Update pip and setuptools
pip install --upgrade pip setuptools wheel

# Clear pip cache
pip cache purge

# Use specific Python version
python3.10 -m venv venv

Database Connection Failed

# Check PostgreSQL is running
pg_isready

# Check connection
psql -U postgres -c "SELECT 1"

# Reset database
dropdb readur_dev
createdb readur_dev
alembic upgrade head

Frontend Build Errors

# Clear node modules
rm -rf node_modules package-lock.json
npm install

# Clear build cache
npm run clean
npm run build

OCR Worker Not Processing

# Check Redis connection
redis-cli ping

# Monitor worker logs
celery -A readur.worker worker --loglevel=debug

# Purge task queue
celery -A readur.worker purge

Contributing

Before Submitting PR

  1. Run all tests: Ensure all tests pass
  2. Check linting: Fix any style issues
  3. Update documentation: Document new features
  4. Add tests: Cover new functionality
  5. Test migrations: Verify database changes

Code Style

Follow project conventions: - Python: PEP 8 with Black formatting - JavaScript: ESLint + Prettier - Commits: Conventional commits format - Documentation: Markdown with proper headings