Quickstart

Get ReadRealm running in minutes with step-by-step setup instructions.

Get ReadRealm up and running in minutes. The backend API must be running before the mobile apps and admin dashboard can connect to it.

Prerequisites

Backend (API)

• Node.js 20+
• MongoDB 5+ (local install or Docker)
• npm or pnpm (comes with Node.js)

If you don’t have MongoDB installed locally, use Docker to start it: docker-compose up -d mongodb

Android

• Android SDK 24+ (API level 24 = Android 7.0)
• Gradle 8+
• Kotlin 1.9+
• Android Studio (recommended) or any IDE with Android support

iOS

• Xcode 15+ (macOS only)
• CocoaPods (dependency manager)

iOS development requires macOS. You cannot build the iOS client on Windows or Linux.

Admin Dashboard

• Flutter SDK 3.20+
• Dart SDK 3.4+

Install Flutter from flutter.dev.

30-second setup

1. Clone the repository

   git clone https://github.com/aliammari1/readrealm.git
   cd readrealm
   
2. Install all dependencies

   Using Task (recommended):

   task setup
   

   Or manually:

   cd apps/api && npm ci && cd ../..
   cd apps/dashboard && flutter pub get && cd ../..
   
3. Configure environment variables

   cp apps/api/.env.example apps/api/.env
   

   Then edit apps/api/.env with your values. The minimum required variables are:

   apps/api/.env

   MONGO_URL=mongodb://localhost:27017/readrealm
   JWT_SECRET=your_jwt_secret_key_min_32_characters_long
   GEMINI_API_KEY=your_google_ai_api_key
   AZURE_API_TTS_KEY=your_azure_tts_key
   AZURE_API_TTS_ENDPOINT=https://your-region.openai.azure.com/
   

   See the Environment Configuration guide for all available variables.

4. Start the backend

   task api:dev
   

   Or manually:

   cd apps/api && npm run start:dev
   

   The API server starts at http://localhost:3000.

   MongoDB must be running before you start the API. If you see a connection error, start MongoDB first or use task docker:up to run MongoDB in Docker.

5. Start the admin dashboard (optional)

   In a new terminal:

   task dashboard:run
   

   Or manually:

   cd apps/dashboard && flutter run -d chrome
   

Run applications

Layer	App	Command	Purpose
Backend	API	task api:dev	Core server at http://localhost:3000
Client	Android	task android:build	Build debug APK
Client	iOS	Open apps/ios/Runner.xcworkspace in Xcode	Build in Xcode
Admin	Dashboard	task dashboard:run	Admin dashboard (web/desktop)

Task command reference

Backend

task api:dev          # Start development server (hot reload)
task api:build        # Build for production
task api:test         # Run unit tests
task api:test:e2e     # Run end-to-end tests

Android

task android:build    # Build debug APK
task android:test     # Run unit tests

iOS

task ios:build        # Build for iOS
task ios:test         # Run unit tests

Dashboard

task dashboard:run    # Run on Chrome (web)
task dashboard:test   # Run tests
task dashboard:build:web  # Build for production

Docker

task docker:up        # Start API + MongoDB in Docker
task docker:down      # Stop services

All

task test             # Run all tests
task lint             # Run all linters
task format           # Format all code

Troubleshooting

"Command not found: task"

Install the Task CLI:

# macOS
brew install go-task/tap/go-task

# Linux
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin

# Windows (via Scoop)
scoop install task

Alternatively, run commands manually without Task:

cd apps/api && npm run start:dev
cd apps/dashboard && flutter run -d chrome

MongoDB connection error

If the API fails to start with a MongoDB connection error:

# Check if MongoDB is running locally
mongosh localhost:27017

# Or start MongoDB via Docker
docker-compose up -d mongodb

# Check MongoDB logs
docker-compose logs -f mongodb

Make sure MONGO_URL in your apps/api/.env matches where MongoDB is running.

Port 3000 already in use

# Find what's using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

# Or start the API on a different port
PORT=3001 npm run start:dev

Flutter issues

# Check Flutter installation
flutter doctor

# Clean and reinstall dependencies
flutter clean
flutter pub get

# Run again
flutter run -d chrome

Next steps

Environment Configuration

Configure all API keys and service integrations.

Docker Deployment

Run the full stack with Docker Compose.

Architecture

Understand how all the components connect.

API Reference

Explore the REST API and WebSocket interface.