Skip to main content
This guide will help you get App Courier running on your local machine in just a few minutes.

​
Prerequisites

Before you begin, ensure you have:
  • Flutter SDK 3.7.2 or higher installed
  • Dart SDK (comes with Flutter)
  • Android Studio or Xcode (for mobile development)
  • Git installed
  • A code editor (VS Code, Android Studio, or IntelliJ recommended)
If you don’t have Flutter installed, follow the official Flutter installation guide for your operating system.

​
Step 1: Verify Flutter Installation

First, verify that Flutter is properly installed: 
flutter --version
You should see output showing Flutter 3.7.2 or higher. Run the doctor command to check for any issues: 
flutter doctor
Resolve any issues indicated by red ❌ marks before proceeding.

​
Step 2: Clone the Repository

Clone the App Courier repository to your local machine: 
git clone <repository-url>
cd courier
Replace <repository-url> with the actual repository URL provided by your team.

​
Step 3: Install Dependencies

Install all required Flutter packages: 
flutter pub get
This will download and install all dependencies defined in pubspec.yaml, including:
  • dio for HTTP requests
  • provider for state management
  • shared_preferences for local storage
  • image_picker, fl_chart, pdf, and more

​
Step 4: Configure API Endpoint (Optional)

The app is pre-configured to connect to the production API. If you need to use a different API endpoint:
1

Open the API client file

# Open in your editor
lib/core/api/api_client.dart
2

Update the base URL

Locate line 10 and update the baseUrl:
ApiClient() {
  _dio = Dio(
    BaseOptions(
      baseUrl: 'https://your-api-endpoint.com', // Change this
      validateStatus: (status) {
        return status != null && status >= 200 && status < 300;
      },
      connectTimeout: const Duration(seconds: 20),
      receiveTimeout: const Duration(seconds: 20),
      headers: {
        'Content-Type': 'application/json',
      },
    ),
  );
}
The default API endpoint is https://api.eisegmi.facturador.es. Only change this if you’re using a custom backend.

​
Step 5: Set Up Device/Emulator

You need either a physical device or an emulator to run the app.

​
Using Android Emulator

  1. Open Android Studio
  2. Go to Tools > Device Manager
  3. Create a new virtual device (or start an existing one)
  4. Verify the emulator is running:
flutter devices

​
Using Physical Android Device

  1. Enable Developer Options on your Android device
  2. Enable USB Debugging
  3. Connect your device via USB
  4. Verify the device is detected:
flutter devices

​
Step 6: Run the Application

Now you’re ready to launch the app! 
flutter run
This command will:
  1. Build the application
  2. Install it on your connected device/emulator
  3. Launch the app
  4. Enable hot reload for development
The first build may take several minutes. Subsequent builds will be much faster thanks to Flutter’s caching.

​
Run Specific Platform

To run on a specific device when multiple devices are connected: 
# List all devices
flutter devices

# Run on specific device
flutter run -d <device-id>

# Example: Run on Chrome (for testing UI)
flutter run -d chrome

​
Step 7: Test the Application

Once the app launches, you should see the Font Page (landing screen):
1

Landing Screen

The app opens to a landing page where users can choose their login type:
  • Admin/Staff Login: For administrators and staff members
  • Customer Login: For customers to track their shipments
2

Admin Login

Try logging in with admin credentials:
  • Navigate to Admin Login
  • Enter your admin username and password
  • Access the admin dashboard
3

Customer Registration (Optional)

Test the customer flow:
  • Navigate to Customer Login
  • Click “Register” to create a new customer account
  • Complete the verification process
  • Access the customer portal
You’ll need valid credentials from your backend system to fully test the application. Contact your system administrator for test accounts.

​
Development Tools

While the app is running, you have access to powerful development tools:

​
Hot Reload

Make changes to your code and press r in the terminal to hot reload: 
r - Hot reload (fast)
R - Hot restart (slower, full restart)
q - Quit

​
Flutter DevTools

Launch DevTools for debugging: 
flutter pub global activate devtools
flutter pub global run devtools
Then press v in the terminal running flutter run to open DevTools.

​
Logging

View detailed logs: 
flutter run --verbose

​
Common Issues

Solution: Update Gradle and dependencies
cd android
./gradlew clean
cd ..
flutter clean
flutter pub get
Solution: Update and reinstall pods
cd ios
rm -rf Pods Podfile.lock
pod install
cd ..
flutter clean
flutter pub get
Solution: The app requires camera and storage permissions
  • Grant permissions when prompted on first launch
  • On Android: Go to Settings > Apps > App Courier > Permissions
  • On iOS: Go to Settings > App Courier > Enable required permissions
Solution: Check your API configuration
  • Verify the API endpoint in lib/core/api/api_client.dart:10
  • Ensure your device has internet connectivity
  • Check that the backend server is running and accessible
  • Verify there are no firewall or network restrictions
Solution: Clear cache and rebuild
flutter clean
flutter pub get
flutter run

​
Next Steps

Now that you have the app running, explore these resources:

Installation Guide

Learn about detailed setup and configuration options

Architecture

Understand the app’s architecture and design patterns

API Reference

Explore the backend API endpoints

Configuration

Configure API connection

​
Running in Production

To build a release version of the app: 
# Build Android APK
flutter build apk --release

# Build Android App Bundle (recommended for Play Store)
flutter build appbundle --release

# APK location: build/app/outputs/flutter-apk/app-release.apk
Before building for production, ensure you’ve:
  • Updated version numbers in pubspec.yaml
  • Configured signing certificates
  • Set production API endpoints
  • Tested thoroughly on multiple devices

Build docs developers (and LLMs) love

Get started for freeTalk to us