Installation - Rodando Passenger

This comprehensive guide covers everything you need to set up Rodando Passenger for development, including prerequisites, dependency installation, environment configuration, and platform-specific setup for Android and iOS.

Prerequisites

Before installing Rodando Passenger, ensure you have the following tools installed on your development machine.

Required Tools

Node.js

Version 16+ required (Node 18 or 20 recommended)Download from nodejs.org

npm or Yarn

Package manager (npm comes with Node.js)Or install Yarn: npm install -g yarn

Ionic CLI

Version 7+

npm install -g @ionic/cli

Git

Version controlDownload from git-scm.com

Platform-Specific Prerequisites

These are only needed if you plan to build and run the app on native mobile platforms.

For Android Development

Android Studio (latest stable version)
- Download from developer.android.com/studio
- Install Android SDK (API level 33 or higher recommended)
- Configure ANDROID_HOME environment variable
- Install Android SDK Build-Tools and Platform-Tools
Java Development Kit (JDK) 11 or 17
- JDK 17 is recommended for Android development
- Verify with: java -version

For iOS Development (macOS only)

Xcode 14+ (latest stable version)
- Download from Mac App Store
- Install Xcode Command Line Tools: xcode-select --install
- Open Xcode and accept license agreements
CocoaPods
```
sudo gem install cocoapods
```

Installation Steps

Clone the Repository

Clone the project repository to your local machine:

git clone <your-repository-url>
cd rodandoApp-frontend

Verify you’re in the correct directory:

ls -la
# Should show: package.json, angular.json, capacitor.config.ts, etc.

Install Dependencies

Install all npm dependencies defined in package.json:

npm install

This will install:

Core Framework Dependencies

@angular/core@^18.2.0 - Angular framework
@ionic/angular@^8.4.3 - Ionic UI components
@capacitor/core@^7.4.2 - Native device APIs
@capacitor/[email protected] - Android platform support

State Management

@ngrx/store@^18.1.1 - State management
@ngrx/signals@^18.1.1 - Signal-based reactive state
@ngrx/effects@^18.1.1 - Side effect management

Mapping & Location

mapbox-gl@^3.15.0 - Interactive maps
@angular/google-maps@^18.2.14 - Google Maps integration (fallback)
@turf/turf@^7.2.0 - Geospatial calculations
@capacitor/geolocation@^7.1.5 - Native GPS access

Real-time Communication

socket.io-client@^4.8.1 - WebSocket connections for live tracking

Native Device Features

@aparajita/capacitor-secure-storage@^7.1.6 - Encrypted token storage
@capacitor/preferences@^7.0.2 - Local data persistence
@capacitor/[email protected] - Vibration feedback
@capacitor/[email protected] - Keyboard appearance control
@capacitor/[email protected] - Status bar styling

UI & Utilities

ionicons@^8.0.9 - Icon library
ngx-toastr@^18.0.0 - Toast notifications
rxjs@~7.8.0 - Reactive programming

The installation may take several minutes depending on your internet connection and machine performance.

Configure Environment Variables

Set up your environment configuration files. The app uses Angular’s environment replacement system.

Development Environment

Edit src/environments/environment.ts:

src/environments/environment.ts

export const environment = {
  production: false,
  
  // Backend API endpoints
  apiUrl: 'http://10.0.2.2:3000/api',  // REST API
  wsBase: 'ws://10.0.2.2:3000',        // WebSocket
  
  // App identification
  appAudience: 'passenger_app',
  expectedUserType: 'passenger',
  
  // Mapbox configuration
  mapbox: {
    accessToken: 'YOUR_MAPBOX_ACCESS_TOKEN'
  },
  
  // Debug settings
  debug: true,
  debugTags: ['DA', 'HTTP', 'LOC', 'PL', 'PAX']
};

Production Environment

Edit src/environments/environment.prod.ts for production builds:

src/environments/environment.prod.ts

export const environment = {
  production: true,
  apiUrl: 'https://your-api.com/api',
  wsBase: 'wss://your-api.com',
  appAudience: 'passenger_app',
  expectedUserType: 'passenger',
  mapbox: {
    accessToken: 'YOUR_PRODUCTION_MAPBOX_TOKEN'
  },
  debug: false,
  debugTags: []
};

Configuration Details

Variable	Description	Required
`apiUrl`	Backend REST API base URL	Yes
`wsBase`	WebSocket server URL for real-time updates	Yes
`appAudience`	JWT audience claim (must be `passenger_app`)	Yes
`expectedUserType`	User type validation (must be `passenger`)	Yes
`mapbox.accessToken`	Mapbox API token for maps and geocoding	Yes
`debug`	Enable debug logging	No
`debugTags`	Filter debug logs by tag	No

Important URL Notes:

10.0.2.2 is the Android emulator’s alias for the host machine’s localhost
For iOS simulator, use http://localhost:3000/api instead
For physical devices, use your machine’s local network IP (e.g., http://192.168.1.100:3000/api)
WebSocket URLs use ws:// (not wss://) for local development

Obtain Mapbox Access Token

Rodando Passenger uses Mapbox for all mapping functionality. You need a valid Mapbox access token:

Create a Mapbox Account
- Go to mapbox.com and sign up (free tier available)
Get Your Access Token
- Navigate to your account dashboard
- Copy your default public token, or create a new one
Configure Scopes (for new tokens)
- Ensure these scopes are enabled:
  - styles:read - Map rendering
  - fonts:read - Map labels
  - datasets:read - Dataset access
  - geocoding:read - Geocoding API (place search, reverse geocode)
  - directions:read - Directions API (route calculation)

Add Token to Environment

mapbox: {
  accessToken: 'pk.eyJ1Ijoicm9kYW5kb2N1YmEiLCJhIjoiY21lYzZtMWF0MWJoaDJsb2YxNG56N2NmYiJ9.o5oPXGNXcut8PE0O7CG-VA'
}

The free tier includes 50,000 map loads and 100,000 geocoding requests per month, which is sufficient for development.

Verify Installation

Test that everything is installed correctly:

# Check Node.js version
node --version
# Should be v16+ (v18 or v20 recommended)

# Check npm version
npm --version

# Check Ionic CLI
ionic --version
# Should be 7.0.0 or higher

# Check Angular CLI (installed as dev dependency)
npx ng version
# Should show Angular CLI 18.2.0

# Verify TypeScript
npx tsc --version
# Should show 5.5.4

All commands should run without errors and display the appropriate version numbers.

Platform-Specific Setup

Android Configuration

Add Android Platform

If not already added, initialize Capacitor for Android:

ionic capacitor add android

This creates the android/ directory with the native Android project.

Configure Capacitor

The capacitor.config.ts file is pre-configured:

capacitor.config.ts

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'io.ionic.starter',
  appName: 'rodandoApp-frontend',
  webDir: 'www',
  server: {
    url: 'http://10.0.2.2:8100',  // For live reload on emulator
    cleartext: true
  }
};

export default config;

Before building for production, remove the server configuration or set it to your production URL.

Update Android App ID

Change the default app ID to your own:

Update capacitor.config.ts:

appId: 'com.yourcompany.rodandopassenger',
appName: 'Rodando Passenger',

Sync changes to Android:
```
ionic capacitor sync android
```

Build and Run on Android

Build the web assets and open in Android Studio:

# Build web assets
ionic build

# Sync with native project
ionic capacitor sync android

# Open in Android Studio
ionic capacitor open android

Or run directly on an emulator/device:

ionic capacitor run android

The first build may take several minutes as Gradle downloads dependencies.

iOS Configuration (macOS only)

Add iOS Platform

Initialize Capacitor for iOS:

ionic capacitor add ios

This creates the ios/ directory with the native iOS project.

Install Pod Dependencies

Navigate to the iOS directory and install CocoaPods dependencies:

cd ios/App
pod install
cd ../..

Update Bundle Identifier

Change the default bundle identifier:

Update capacitor.config.ts (same as Android step)
Sync changes:
```
ionic capacitor sync ios
```
Open Xcode and update the bundle identifier in the project settings

Build and Run on iOS

Build and open in Xcode:

# Build web assets
ionic build

# Sync with native project
ionic capacitor sync ios

# Open in Xcode
ionic capacitor open ios

In Xcode:

Select your target device or simulator
Click the Play button to build and run

For physical iOS devices, you need an Apple Developer account and proper code signing configured in Xcode.

Running the Application

Development Server (Browser)

For rapid development with live reload:

ionic serve

Or using Angular CLI directly:

ng serve
# or
npm start

The app will be available at http://localhost:8100.

Native Platforms

Android

# Run on connected device/emulator
ionic capacitor run android

# Run with live reload
ionic capacitor run android --livereload --external

# Build release APK
ionic capacitor build android --prod

iOS

# Open in Xcode (build from there)
ionic capacitor open ios

# Or run directly
ionic capacitor run ios

# With live reload
ionic capacitor run ios --livereload --external

Build Configuration

The angular.json file defines build configurations:

Development Build

ng build --configuration=development

Features:

Source maps enabled
No optimization
No file hashing
Fast build times

Production Build

ng build --configuration=production
# or
ionic build --prod

Features:

Code minification
Tree shaking
AOT compilation
File hashing for cache busting
Environment file replacement (environment.ts → environment.prod.ts)
Bundle size budgets:
- Initial bundle: max 5MB (warning at 2MB)
- Component styles: max 16KB (warning at 10KB)

Production builds are output to the www/ directory, which is used by Capacitor for native builds.

Troubleshooting

Common Installation Issues

Node Version Incompatibility

Error: “The engine ‘node’ is incompatible” Solution: Use Node.js 16, 18, or 20. Check with:

node --version

Consider using nvm to manage Node versions:

nvm install 20
nvm use 20

Capacitor Sync Failures

Error: “Capacitor could not sync” Solution:

Delete platform directories:
```
rm -rf android/ ios/
```

Rebuild:

ionic build
ionic capacitor add android
ionic capacitor add ios

Android Build Errors

Error: “Could not find com.android.tools.build:gradle” Solution:

Open Android Studio
Go to File > Settings > Appearance & Behavior > System Settings > Android SDK
Ensure Android SDK Build-Tools and Platform-Tools are installed

Set ANDROID_HOME environment variable:

export ANDROID_HOME=$HOME/Library/Android/sdk  # macOS/Linux
# or
set ANDROID_HOME=%LOCALAPPDATA%\Android\Sdk  # Windows

iOS Pod Install Failures

Error: “Unable to find a specification for…” Solution:

cd ios/App
rm -rf Pods Podfile.lock
pod repo update
pod install

Mapbox Not Rendering

Symptoms: Blank map area or “403 Unauthorized” errors Solutions:

Verify your Mapbox token is valid
Check token scopes include styles:read and fonts:read
Ensure no trailing spaces in the token string
Check browser console for CORS errors
Test token at mapbox.com/account/access-tokens

WebSocket Connection Failed

Symptoms: “WebSocket connection to ‘ws://…’ failed” Solutions:

Verify backend WebSocket server is running
Check wsBase URL in environment file
For Android emulator, use ws://10.0.2.2:3000
For iOS simulator, use ws://localhost:3000
For physical devices, use your local network IP: ws://192.168.1.x:3000
Ensure firewall allows WebSocket connections

Build Performance

If builds are slow:

Increase Node memory:

export NODE_OPTIONS="--max-old-space-size=8192"

Use development mode:

ionic serve --configuration=development

Disable source maps (in angular.json):
```
"sourceMap": false
```

Next Steps

With the installation complete, you’re ready to explore the app:

Core Features

Learn about authentication, trip booking, and tracking

Architecture

Understand the app’s structure and design patterns

State Management

Deep dive into NgRx Signals implementation

Development

Development workflow and best practices

Get Started

Core Features

Architecture

Development

​Prerequisites

​Required Tools

Node.js

npm or Yarn

Ionic CLI

Git

​Platform-Specific Prerequisites

​For Android Development

​For iOS Development (macOS only)

​Installation Steps

​Core Framework Dependencies

​State Management

​Mapping & Location

​Real-time Communication

​Native Device Features

​UI & Utilities

​Development Environment

​Production Environment

​Configuration Details

​Platform-Specific Setup

​Android Configuration

​iOS Configuration (macOS only)

​Running the Application

​Development Server (Browser)

​Native Platforms

​Android

​iOS

​Build Configuration

​Development Build

​Production Build

​Troubleshooting

​Common Installation Issues

​Node Version Incompatibility

​Capacitor Sync Failures

​Android Build Errors

​iOS Pod Install Failures

​Mapbox Not Rendering

​WebSocket Connection Failed

​Build Performance

​Next Steps

Core Features

Architecture

State Management

Development

​Additional Resources

Build docs developers (and LLMs) love

Prerequisites

Required Tools

Platform-Specific Prerequisites

For Android Development

For iOS Development (macOS only)

Installation Steps

Core Framework Dependencies

State Management

Mapping & Location

Real-time Communication

Native Device Features

UI & Utilities

Development Environment

Production Environment

Configuration Details

Platform-Specific Setup

Android Configuration

iOS Configuration (macOS only)

Running the Application

Development Server (Browser)

Native Platforms

Android

iOS

Build Configuration

Development Build

Production Build

Troubleshooting

Common Installation Issues

Node Version Incompatibility

Capacitor Sync Failures

Android Build Errors

iOS Pod Install Failures

Mapbox Not Rendering

WebSocket Connection Failed

Build Performance

Next Steps

Additional Resources