Installation Guide

This guide covers everything you need to set up the Rodando Driver application for development and production deployment.

Prerequisites

Before you begin, ensure you have the following installed on your system:

Node.js

Version: 18.x or higherDownload Node.js

npm

Version: 9.x or higherComes bundled with Node.js

Angular CLI

Version: 18.2.0

npm install -g @angular/[email protected]

Ionic CLI

Version: Latest

npm install -g @ionic/angular-toolkit

Mobile Development Prerequisites

For building mobile apps, you’ll also need:

Android
iOS

Android Studio (latest stable version)
Java Development Kit (JDK) 17 or higher
Android SDK (API level 33 or higher)
Gradle (comes with Android Studio)

Environment Variables:

export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools

macOS (required for iOS development)
Xcode (latest stable version from App Store)
CocoaPods (for dependency management)

sudo gem install cocoapods

iOS development requires a Mac with Xcode. You cannot build iOS apps on Windows or Linux.

Step 1: Clone or Download the Project

git clone <repository-url> rodando-driver
cd rodando-driver

The project structure:

rodando-driver/
├── src/
│   ├── app/
│   │   ├── core/
│   │   │   ├── services/      # API services, WebSocket, storage
│   │   │   ├── guards/        # Auth guards
│   │   │   └── models/        # TypeScript interfaces
│   │   ├── features/
│   │   │   ├── auth/          # Login, signup flows
│   │   │   ├── tabs/          # Home, map, trips, earnings
│   │   │   └── sidebar/       # Profile, settings, wallet
│   │   ├── store/             # NgRx state management
│   │   └── components/        # Reusable UI components
│   ├── environments/          # Environment configurations
│   └── assets/                # Images, icons, fonts
├── capacitor.config.ts        # Capacitor configuration
├── angular.json               # Angular workspace config
├── package.json               # Dependencies
└── tsconfig.json              # TypeScript configuration

Step 2: Install Dependencies

Install all required npm packages:

npm install

This will install:

Core Framework Dependencies

{
  "@angular/core": "^18.2.0",
  "@angular/common": "^18.2.0",
  "@angular/router": "^18.2.0",
  "@ionic/angular": "^8.4.3",
  "@capacitor/core": "7.4.2"
}

Mobile Platform Packages

{
  "@capacitor/android": "7.4.2",
  "@capacitor/app": "7.0.1",
  "@capacitor/haptics": "7.0.1",
  "@capacitor/keyboard": "7.0.1",
  "@capacitor/preferences": "^7.0.2",
  "@capacitor/status-bar": "7.0.1"
}

State Management

{
  "@ngrx/store": "^18.1.1",
  "@ngrx/effects": "^18.1.1",
  "@ngrx/signals": "^18.1.1"
}

Maps and Geolocation

{
  "@angular/google-maps": "^18.2.14",
  "mapbox-gl": "^3.15.0",
  "@turf/turf": "^7.2.0"
}

Real-time Communication

{
  "socket.io-client": "^4.8.1"
}

Security

{
  "capacitor-secure-storage-plugin": "^0.11.0"
}

Step 3: Environment Configuration

Configure your environment variables for development and production.

Development Environment

Edit src/environments/environment.ts:

export const environment = {
  production: false,
  
  // API Configuration
  apiUrl: 'http://localhost:3000/api',
  wsBase: 'ws://localhost:3000',
  
  // App Identity
  appAudience: 'driver_app',
  expectedUserType: 'driver',
  
  // Maps Configuration
  googleMapsApiKey: 'YOUR_GOOGLE_MAPS_API_KEY',
  mapbox: {
    accessToken: 'YOUR_MAPBOX_ACCESS_TOKEN'
  },
  
  // Debugging
  debug: true,
  debugTags: ['DA', 'HTTP', 'LOC']
};

Production Environment

Edit src/environments/environment.prod.ts:

export const environment = {
  production: true,
  
  apiUrl: 'https://api.rodando.app/api',
  wsBase: 'wss://api.rodando.app',
  
  appAudience: 'driver_app',
  expectedUserType: 'driver',
  
  googleMapsApiKey: 'YOUR_PRODUCTION_GOOGLE_MAPS_API_KEY',
  mapbox: {
    accessToken: 'YOUR_PRODUCTION_MAPBOX_TOKEN'
  },
  
  debug: false,
  debugTags: []
};

Never commit API keys to version control! Use environment variables or a secrets management service in production.

Required API Keys

Get a Mapbox Access Token

Sign up at mapbox.com
Navigate to Account → Access Tokens
Create a new token with styles:read and fonts:read scopes
Copy the token to environment.mapbox.accessToken

Get a Google Maps API Key

Go to Google Cloud Console
Enable Maps JavaScript API and Places API
Create credentials → API Key
Add the key with &libraries=places suffix

googleMapsApiKey: 'AIzaSyB...&libraries=places'

Step 4: Run the Application

Development Server

Start the development server with live reload:

ng serve

Or using Ionic CLI for device preview:

ionic serve

The app will be available at:

Angular: http://localhost:4200
Ionic: http://localhost:8100

The Ionic server provides additional features like device emulation and live reload for mobile testing.

Build for Production

Create an optimized production build:

ng build --configuration production

Output will be in the www/ directory. The build process:

Minifies JavaScript and CSS
Optimizes images and assets
Applies tree-shaking to remove unused code
Uses environment.prod.ts configuration

Build configuration from angular.json:

"production": {
  "budgets": [
    {
      "type": "initial",
      "maximumWarning": "2mb",
      "maximumError": "5mb"
    }
  ],
  "fileReplacements": [
    {
      "replace": "src/environments/environment.ts",
      "with": "src/environments/environment.prod.ts"
    }
  ],
  "outputHashing": "all"
}

Step 5: Capacitor Setup for Mobile

Capacitor bridges your web app to native mobile platforms.

Initialize Capacitor

Capacitor is pre-configured in this project. Verify the configuration in capacitor.config.ts:

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

const config: CapacitorConfig = {
  appId: 'io.ionic.starter',  // Change this to your app ID
  appName: 'rodandoApp-frontend',
  webDir: 'www'
};

export default config;

Update appId to your unique bundle identifier before building for production:

Android: com.rodando.driver
iOS: com.rodando.driver

Add Mobile Platforms

Android
iOS

# Build the web assets first
npm run build

# Add Android platform
npx cap add android

# Sync web assets to Android
npx cap sync android

# Open in Android Studio
npx cap open android

Android-specific configuration:In android/app/src/main/AndroidManifest.xml, ensure these permissions:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

# Build the web assets first
npm run build

# Add iOS platform
npx cap add ios

# Install CocoaPods dependencies
cd ios/App
pod install
cd ../..

# Sync web assets to iOS
npx cap sync ios

# Open in Xcode
npx cap open ios

iOS-specific configuration:In ios/App/App/Info.plist, add location usage descriptions:

<key>NSLocationWhenInUseUsageDescription</key>
<string>Rodando Driver needs your location to show nearby trips and navigate to passengers.</string>

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Rodando Driver needs your location in the background to track trip progress.</string>

Sync Changes to Mobile

Whenever you update the web app, sync changes:

# Rebuild web assets
npm run build

# Sync to all platforms
npx cap sync

# Or sync to specific platform
npx cap sync android
npx cap sync ios

Step 6: Run on Mobile Device

Using Android Studio

Open the project

npx cap open android

Connect device or start emulator

Physical device: Enable USB debugging in Developer Options
Emulator: Create an AVD (Android Virtual Device) in AVD Manager

Run the app

Click the Run button (green play icon) in Android Studio toolbar.

Using Xcode

Open the project

npx cap open ios

Select target device

Choose a simulator or connected iOS device from the device menu.

Configure signing

Select the App target
Go to Signing & Capabilities
Select your development team
Xcode will automatically manage provisioning profiles

Run the app

Click the Play button or press Cmd + R.

Live Reload on Device

For faster development, use live reload:

# Start dev server with network access
ionic serve --host=0.0.0.0

# Note your local IP (e.g., 192.168.1.100)

# Update capacitor.config.ts
const config: CapacitorConfig = {
  appId: 'com.rodando.driver',
  appName: 'Rodando Driver',
  webDir: 'www',
  server: {
    url: 'http://192.168.1.100:8100',  // Your dev server
    cleartext: true
  }
};

Then sync and run:

npx cap sync
npx cap run android  # or ios

Remove the server configuration before building for production! This is only for development.

Testing

Unit Tests

Run unit tests with Karma:

npm test

Test configuration in karma.conf.js:

module.exports = function (config) {
  config.set({
    frameworks: ['jasmine', '@angular-devkit/build-angular'],
    plugins: [
      require('karma-jasmine'),
      require('karma-chrome-launcher'),
      require('karma-jasmine-html-reporter'),
      require('karma-coverage'),
      require('@angular-devkit/build-angular/plugins/karma')
    ],
    browsers: ['Chrome']
  });
};

Linting

Check code quality:

npm run lint

ESLint configuration in .eslintrc.json:

{
  "extends": [
    "plugin:@angular-eslint/recommended",
    "plugin:@typescript-eslint/recommended"
  ],
  "rules": {
    "@typescript-eslint/explicit-module-boundary-types": "off",
    "@angular-eslint/directive-selector": [
      "error",
      { "type": "attribute", "prefix": "app", "style": "camelCase" }
    ]
  }
}

Troubleshooting

npm install fails with dependency conflicts

Try using --legacy-peer-deps:

npm install --legacy-peer-deps

Or clear the cache:

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Capacitor sync fails

Ensure you’ve built the web app first:

ng build
npx cap sync

Check that www/ directory exists and contains built files.

Android build fails with Gradle errors

Update Gradle in android/build.gradle:

dependencies {
    classpath 'com.android.tools.build:gradle:8.1.0'
}

And in android/gradle/wrapper/gradle-wrapper.properties:

distributionUrl=https\://services.gradle.org/distributions/gradle-8.2-all.zip

iOS build fails with CocoaPods errors

cd ios/App
pod repo update
pod install --repo-update
cd ../..
npx cap sync ios

Map doesn't render

Verify:

Mapbox access token is valid in environment.ts
Internet connection is active
No browser console errors (check DevTools)

The map component initializes in src/app/features/tabs/map/map.component.ts:

mapboxgl.accessToken = environment.mapbox.accessToken;
this.map = new mapboxgl.Map({
  container: this.mapEl.nativeElement,
  style: 'mapbox://styles/mapbox/streets-v12',
  center: [-75.83, 20.02],
  zoom: 12
});

WebSocket connection fails

Check:

Backend server is running
environment.wsBase points to correct WebSocket URL
CORS is configured on backend to allow WebSocket connections

Connection logic in src/app/core/services/socket/driver-ws.service.ts:

this.socket = io(`${environment.wsBase}/drivers`, {
  transports: ['websocket'],
  auth: { token: this.auth.accessToken?.() || '' },
  reconnection: true
});

Build Scripts Reference

Available npm scripts from package.json:

{
  "scripts": {
    "ng": "ng",
    "start": "ng serve",
    "build": "ng build",
    "watch": "ng build --watch --configuration development",
    "test": "ng test",
    "lint": "ng lint"
  }
}

npm start

Start development server on http://localhost:4200

npm run build

Build production bundle to www/

npm test

Run unit tests with Karma

npm run lint

Check code quality with ESLint

Next Steps

Quickstart Guide

Learn how to use the app from a driver’s perspective

Authentication

Deep dive into auth flows and token management

State Management

Understand NgRx stores and facades

WebSocket Events

Real-time trip updates and messaging

API Reference

Complete API endpoint documentation

Deployment

Deploy to Google Play and App Store

Additional Resources

For project-specific questions or issues, please contact the development team or open an issue in the project repository.

Getting Started

Core Features

User Guides

Configuration

​Installation Guide

​Prerequisites

Node.js

npm

Angular CLI

Ionic CLI

​Mobile Development Prerequisites

​Step 1: Clone or Download the Project

​Step 2: Install Dependencies

​Step 3: Environment Configuration

​Development Environment

​Production Environment

​Required API Keys

​Step 4: Run the Application

​Development Server

​Build for Production

​Step 5: Capacitor Setup for Mobile

​Initialize Capacitor

​Add Mobile Platforms

​Sync Changes to Mobile

​Step 6: Run on Mobile Device

​Using Android Studio

​Using Xcode

​Live Reload on Device

​Testing

​Unit Tests

​Linting

​Troubleshooting

​Build Scripts Reference

npm start

npm run build

npm test

npm run lint

​Next Steps

Quickstart Guide

Authentication

State Management

WebSocket Events

API Reference

Deployment

​Additional Resources

Build docs developers (and LLMs) love

Installation Guide

Prerequisites

Mobile Development Prerequisites

Step 1: Clone or Download the Project

Step 2: Install Dependencies

Step 3: Environment Configuration

Development Environment

Production Environment

Required API Keys

Step 4: Run the Application

Development Server

Build for Production

Step 5: Capacitor Setup for Mobile

Initialize Capacitor

Add Mobile Platforms

Sync Changes to Mobile

Step 6: Run on Mobile Device

Using Android Studio

Using Xcode

Live Reload on Device

Testing

Unit Tests

Linting

Troubleshooting

Build Scripts Reference

Next Steps

Additional Resources