iOS Physical Device Setup

This guide explains how to deploy the PepperCheck Flutter app to a physical iPhone for testing. It specifically covers the workflow using a Free Apple Developer Account (Personal Team) connected to the Production Backend.

For general iOS deployment information, refer to the Official Flutter Documentation.

1. Prerequisites

  • Xcode installed on your Mac

  • iPhone connected via USB cable

  • Apple ID (Free Personal Account is sufficient)

2. Xcode Signing Configuration (Project Specific)

The project requires specific signing settings to match the registered Bundle ID.

2.1. Open the iOS workspace

open ios/Runner.xcworkspace

2.2. Configure Signing in Xcode

  1. Select Runner (Project) → TARGETS Runner → Signing & Capabilities.

  2. Team: Select your Personal Team (e.g., Your Name (Personal Team)).

  3. Bundle Identifier: Verify it shows dev.cloveclove.peppercheck (this is pre-configured in project files).

3. iPhone Configuration

  1. Enable Developer Mode:

    1. Go to Settings > Privacy & Security > Developer Mode.

    2. Toggle ON and follow the restart prompts (Required for iOS 16+).

  2. Unlock Device: Ensure the device is unlocked and on the home screen.

  3. Trust Computer: If prompted, tap Trust on the "Trust This Computer?" dialog.

4. Running with Production Backend

To test on a physical device without complex local network configuration, we use the Production Backend (.env.production).

This build connects to the live production database. Be careful with data manipulation.

4.1. Identify Device ID

flutter devices

Copy the Device ID (e.g., 00008110-001234567890) from the output.

4.2. Run Release Build

flutter run --release -t lib/main_production.dart -d <Device ID>

  • --release: Installs an optimized build that runs without a debugger attached.

  • -t lib/main_production.dart: Point to the production entry point.

5. Troubleshooting "Untrusted Developer"

On the first install, the app will not launch immediately.

  1. On your iPhone, go to Settings > General > VPN & Device Management.

  2. Tap the Developer App entry (your email address).

  3. Tap Trust to allow the application to run.