Build the iOS app from source

Use this path when you want to tweak the app, sign with your own Apple Developer account for a year-long install, or just don't want to trust a CI-built IPA. You need a Mac with Xcode 15 or newer, an Apple ID, and an iPhone running iOS 16+.

Prerequisites

• macOS with Xcode 15+ installed from the App Store.
• Command-line tools: xcode-select --install.
• Node.js 20+ (use nvm or brew).
• CocoaPods: sudo gem install cocoapods (or via brew).
• A free Apple ID (7-day signing) or a paid Apple Developer Program account (1-year signing).
• An iPhone with Developer Mode enabled: Settings -> Privacy & Security -> Developer Mode.

Step 1 - clone and install dependencies

git clone https://github.com/chartmann1590/family-guardian.git
cd family-guardian/ios-app
npm install

Step 2 - Expo prebuild

The repo keeps the Expo "managed" layout; the native ios/ folder is generated on demand. Run prebuild to materialise the Xcode project:

npx expo prebuild --platform ios --clean

This creates ios/FamilyGuardian.xcworkspace, the Podfile, and an Info.plist with the right background-modes / location-usage strings already filled in. Re-run with --clean any time you change app.json or add a native module.

Step 3 - install CocoaPods

cd ios
pod install
cd ..

Subsequent prebuilds run pod install automatically; the first one usually doesn't.

Step 4 - open in Xcode and sign

open ios/FamilyGuardian.xcworkspace

In Xcode:

1. Select the FamilyGuardian target.
2. Open Signing & Capabilities.
3. Tick Automatically manage signing.
4. Pick your Team. Free Apple IDs appear here once you add them under Xcode -> Settings -> Accounts.
5. If you see a "Failed to register bundle identifier" error, change Bundle Identifier to something unique to you (e.g. com.<yourname>.familyguardian). Free Apple IDs cannot reuse a bundle ID already claimed by someone else.

Step 5 - install on the iPhone

1. Plug your iPhone in over USB and tap Trust when prompted.
2. In Xcode's top toolbar, pick your phone from the device dropdown.
3. Hit the Run button (or Cmd+R). Xcode builds, signs, and installs the app.
4. The first launch fails with "Untrusted Developer". On the iPhone, go to Settings -> General -> VPN & Device Management, tap your developer profile, and tap Trust. Re-open the app.

Step 6 - first-run configuration

1. Open Family Guardian on the iPhone.
2. Enter the server URL: http://YOUR-LAN-IP:8080 (replace with the LAN IP of the box running docker compose).
3. Sign in with the credentials you bootstrapped on the server, or join with an invite code from the admin.
4. Grant location permissions. Pick Always if you want background reporting.
5. Grant notification permission so SOS / geofence alerts can wake the device.

Re-signing cadence

Updating to a new release

cd family-guardian
git pull
cd ios-app
npm install
npx expo prebuild --platform ios --clean
cd ios && pod install && cd ..
open ios/FamilyGuardian.xcworkspace
# Cmd+R in Xcode

Troubleshooting

• "Multiple commands produce..." - run npx expo prebuild --platform ios --clean to start from a clean ios/ folder.
• "Sandbox: rsync deny" - in Xcode, Build Settings -> User Script Sandboxing -> set to No.
• App won't connect to the LAN server - by default iOS allows cleartext HTTP for local networks, but check ios-app/app.json -> ios.infoPlist.NSAppTransportSecurity is preserved across prebuilds.
• Background GPS stops after a few hours - iOS aggressively suspends apps. Make sure Location -> Always is granted and Background App Refresh is on for Family Guardian.

What you get

The build-from-source path produces the same binary as the unsigned-IPA path (same Expo app, same React Native runtime, same features) but signed with your own identity. You get:

• Real background GPS via expo-location.
• Local notifications for SOS, geofence, speeding, low-battery, and offline alerts.
• Real-time WebSocket updates while the app is open.
• Map view, member list, chat, places, check-ins, and the SOS button.

← Back to overview