DEPLOY.md

Deployment Guide

This guide explains how to deploy the Protein Tracker app to web, Android, and iOS platforms.

Table of Contents

• Prerequisites
• Web Deployment (GitHub Pages)
• Android Deployment
• iOS Deployment
• Environment Variables
• Build Profiles Explained
• Common Commands Summary
• EAS Updates (Over-the-Air Updates)
• Troubleshooting
• Additional Resources
• Support

Prerequisites

Before deploying the app, ensure you have:

1. Node.js (v20 or higher) and npm installed
2. Expo CLI (optional, npx can be used instead):

   npm install -g @expo/cli
   # Or use npx expo for commands without global installation

3. EAS CLI installed globally (for mobile builds):

   npm install -g eas-cli

4. Expo Account: Create a free account at expo.dev
5. All dependencies installed:

   npm install

Web Deployment (GitHub Pages)

The app is configured to automatically deploy to GitHub Pages when code is pushed to the main branch.

Automatic Deployment

The deployment is handled by the GitHub Actions workflow (.github/workflows/deploy.yml):

1. Push to main branch:

   git push origin main

2. GitHub Actions will automatically:

   • Install dependencies
   • Build the web version using npx expo export --platform web
   • Deploy the generated dist folder to GitHub Pages

3. Access your app at:

   https://reivaxmar.github.io/protein-tracker
   

Manual Web Deployment

If you need to deploy manually:

1. Build the web version:

   npx expo export --platform web

2. Deploy the dist folder to your web hosting service

Web Deployment Configuration

The web deployment is configured in app.config.js:

web: {
  favicon: "./assets/favicon.png",
  bundler: "metro",
  output: "static"
},
experiments: {
  baseUrl: "/protein-tracker"
}

And in package.json:

{
  "homepage": "https://reivaxmar.github.io/protein-tracker"
}

Android Deployment

To deploy the app to Android devices and the Google Play Store, use Expo Application Services (EAS Build).

Setup for Android

1. Login to Expo:

   eas login

2. Configure your project:

   eas build:configure

   This creates an eas.json file. For Android, use this configuration:

   {
     "build": {
       "production": {
         "android": {
           "buildType": "aab"
         }
       },
       "preview": {
         "android": {
           "buildType": "apk"
         }
       },
       "development": {
         "developmentClient": true,
         "distribution": "internal"
       }
     }
   }

Building for Android

1. Build APK for testing (doesn't require Google Play account):

   eas build --platform android --profile preview

2. Build AAB for Google Play Store:

   eas build --platform android --profile production

3. Download the build when complete:

   • The EAS CLI will provide a download link
   • Or visit https://expo.dev and navigate to your project builds

Submitting to Google Play Store

1. Create a Google Play Developer account ($25 one-time fee)

2. Create an app in the Google Play Console

3. Use EAS Submit:

   eas submit --platform android

   Or manually upload the AAB file to Google Play Console.

4. Complete the store listing:

   • App name, description, screenshots
   • Privacy policy
   • Content rating
   • Pricing and distribution

Installing APK on Android Device

For testing without Google Play:

1. Transfer the APK to your Android device
2. Enable "Install from Unknown Sources" in device settings
3. Open and install the APK file

iOS Deployment

To deploy the app to iOS devices and the App Store, use EAS Build with an Apple Developer account.

Prerequisites for iOS

1. Apple Developer Account ($99/year)
2. Enrolled in the Apple Developer Program

Setup for iOS

1. Login to Expo:

   eas login

2. Configure your project (if not done already):

   eas build:configure

3. Update app.config.js with your bundle identifier:

   ios: {
     supportsTablet: true,
     bundleIdentifier: "com.yourcompany.proteintracker"
   }

Building for iOS

1. Build for internal testing (iOS Simulator):

   eas build --platform ios --profile development

2. Build for TestFlight/App Store:

   eas build --platform ios --profile production

3. EAS will handle:

   • Creating necessary provisioning profiles
   • Signing the app with your Apple Developer credentials
   • Building the IPA file

Submitting to App Store

1. Use EAS Submit:

   eas submit --platform ios

2. Or manually via Xcode:

   • Download the IPA file
   • Use Xcode's Application Loader or Transporter app
   • Upload to App Store Connect

3. Complete the App Store listing:

   • App name, description, keywords
   • Screenshots (multiple sizes required)
   • Privacy policy
   • App Store categories
   • Pricing and availability

4. Submit for review:

   • Apple typically reviews apps within 24-48 hours
   • Address any feedback from the review team

Testing on iOS Device

For internal testing before App Store submission:

1. Use TestFlight:

   eas build --platform ios --profile preview
   eas submit --platform ios --profile preview

2. Invite testers through App Store Connect

3. Testers install via TestFlight app on their iOS devices

Environment Variables

If your app requires environment variables (API keys, etc.):

1. Create a .env file (don't commit to git):

   API_KEY=your_api_key_here
   

2. Use eas.json to set environment variables:

   {
     "build": {
       "production": {
         "env": {
           "API_KEY": "production_key"
         }
       }
     }
   }

3. Or use EAS Secrets:

   eas secret:create --name API_KEY --value your_api_key

Build Profiles Explained

• development: For development builds with debugging enabled
• preview: For testing builds (APK for Android, TestFlight for iOS)
• production: For store submissions (AAB for Google Play, IPA for App Store)

Common Commands Summary

Web

# Build web
npx expo export --platform web

# Run web locally
npm run web

Android

# Build APK
eas build --platform android --profile preview

# Build for Play Store
eas build --platform android --profile production

# Submit to Play Store
eas submit --platform android

iOS

# Build for iOS
eas build --platform ios --profile production

# Submit to App Store
eas submit --platform ios

Both Platforms

# Build for both
eas build --platform all --profile production

# Submit to both stores
eas submit --platform all

Troubleshooting

Camera Permissions on Mobile

The app requires camera permissions for barcode scanning. Ensure the permissions are properly configured in app.config.js:

plugins: [
  [
    "expo-camera",
    {
      cameraPermission: "Allow Protein Tracker to access camera to scan barcodes."
    }
  ]
]

Build Failures

• Check logs: EAS provides detailed build logs
• Dependencies: Ensure all dependencies are compatible with the Expo SDK version
• Clear cache: Try eas build --platform [platform] --clear-cache

Web Routing Issues

If the app doesn't work correctly on GitHub Pages:

• Verify experiments.baseUrl in app.config.js matches your repository name
• Verify the workflow uploads and deploys the generated dist folder

EAS Updates (Over-the-Air Updates)

EAS Update allows you to publish over-the-air (OTA) updates to your app without going through the app stores.

Prerequisites for OTA Updates

Before you can publish OTA updates:

1. EAS CLI must be installed (see Prerequisites section above)

2. Login to EAS CLI:

   eas login

3. Update the Project ID in app.config.js:

   • Run eas project:init to create/link your project
   • Find your project ID in the Expo dashboard or by running eas project:info
   • Update app.config.js:

     updates: {
       url: "https://u.expo.dev/YOUR_PROJECT_ID"  // Replace with actual project ID
     }

   • Alternatively, you can remove the updates.url field and let EAS automatically configure it during the build process.

4. Build Your App with EAS Update support:

   # For both platforms
   eas build --platform all --profile production

Publishing Updates

Once your app is built and distributed, you can publish OTA updates:

Production Updates

eas update --branch production --message "Fix for login bug"

Preview Updates (for testing)

eas update --branch preview --message "Testing new feature"

How OTA Updates Work

1. On App Launch: The app checks for updates when it starts (only in production builds)
2. Download: If an update is available, it's downloaded in the background
3. Apply: The update is applied automatically, and the app reloads
4. Seamless: Users get the latest version without going to the app store

Update Behavior

• Development Mode: Updates are NOT checked in development mode (expo start)
• Production Builds: Updates are checked every time the app launches
• Silent Updates: The update process happens silently without user interaction
• Error Handling: If update check fails, the app continues to work normally

What Can Be Updated OTA

✅ Can be updated OTA:

• JavaScript code changes
• React components
• Business logic
• Styles and layouts
• Assets (images, fonts)
• Configuration that doesn't affect native code

❌ Cannot be updated OTA (requires new build):

• Native code changes
• New native modules or packages
• Changes to app.config.js that affect native configuration
• Permission changes
• Plugin configuration changes
• Expo SDK version updates
• App icon or splash screen

Rollback

If you need to rollback to a previous version:

eas update --branch production --message "Rollback to previous version" --republish

Monitoring Updates

You can monitor your updates in the Expo dashboard:

1. Go to https://expo.dev
2. Select your project
3. Navigate to "Updates" section
4. View deployment history, adoption rates, and errors

Best Practices for OTA Updates

1. Test Before Publishing: Always test updates in preview channel before production
2. Meaningful Messages: Use descriptive messages when publishing updates
3. Monitor Adoption: Check the Expo dashboard to see how many users have the update
4. Gradual Rollout: Consider using branches to gradually roll out updates
5. Version Tracking: Keep track of which features require new builds vs OTA updates

Troubleshooting OTA Updates

Updates Not Appearing

1. Verify the app is a production build (not development)
2. Check that the runtimeVersion in app.config.js matches your build
3. Ensure the project ID in updates.url is correct
4. Check the Expo dashboard for update status

Runtime Errors After Update

1. Check the Expo dashboard for error reports
2. Roll back to the previous version if necessary
3. Test the update locally before publishing

Additional Resources

• Expo Documentation
• EAS Build Documentation
• EAS Submit Documentation
• EAS Update Documentation
• Expo Updates SDK Documentation
• Runtime Version Policies
• App Store Connect
• Google Play Console
• Expo Application Services

Support

For issues or questions:

• Check the Expo Forums
• Review the GitHub Issues
• Consult the React Native documentation