Getting Started

Prerequisites (All Platforms)

  • Git
  • Firebase CLI
  • Docker

Backend

Prerequisites

  • Go (1.21 or higher)
  • PostgreSQL (14 or higher)
  • Docker (for containerization)

Setup

  1. Clone the repository:

git clone https://github.com/global-health-informatics-institute/bme-konza-api cd bme-konza-api


2. Install dependencies:
```bash
go mod download
  1. Set up environment variables:
cp .env.example .env
  1. Run database migrations:

go run main.go migrate


5. Start the development server:

```bash
go run main.go server

The backend will be available at port specified in .env

Mobile App

Development Environment Setup

Prerequisites

  • Xcode (for iOS development)
  • Android Studio with Android SDK
  • Git
  • Firebase CLI

Clone the Repository

git clone https://github.com/global-health-informatics-institute/oxygen-alliance-app
cd oxygen-alliance-app
flutter pub get

Build Flavors

BME KONZA app supports two build flavors for different deployment environments:

Configuration

Each flavor has its own configuration:

  • Staging: Uses staging Firebase project and staging backend API
  • Production: Uses production Firebase project and production backend API

Flavor setup

For ios follow this documentation to setup the staging and production flavor

Firebase CLI

Login in firebase cli

firebase login

And select proper authorized account for the project

Flutterfire

Make sure flutterfire is enabled on your machine if not run

dart pub global activate flutterfire_cli

For staging firebase setup run

flutterfire configure --project=bme-konza-staging --out=lib/firebase_options_staging.dart --ios-bundle-id=org.oxygenalliance.bmekonza.stg --ios-out=ios/flavors/dev/GoogleService-Info.plist --android-package-name=org.bmekonza.app.stg --android-out=android/app/src/dev/google-services.json

For production run

flutterfire configure --project=oa-helpdesk-app

[!NOTE] Add your app sha-1 and sha-265 debug fingerprint to the staging

Running app

When running in debug mode or any other mode on a physical or emulator for both ios and android For staging run

flutter run --flavor staging --dart-define=API_URL=https://staging.bme-konza.org

For prod

flutter run --flavor production --dart-define=API_URL=https://api.bme-konza.org

Build APK:

flutter build apk --flavor staging --dart-define=API_URL=https://staging.bme-konza.org

Build iOS:

flutter build ios --flavor staging -t lib/main_staging.dart

Publishing

Android (Google Play Store)

Make sure the version number is updated

flutter build appbundle --flavor production --dart-define=API_URL=https://api.bme-konza.org

iOS (App Store)

flutter build ipa --flavor production --dart-define=API_URL=https://api.bme-konza.org

Troubleshooting

If you encounter build issues:

  1. Run flutter clean
  2. Run flutter pub get
  3. Rebuild with your desired flavor

iOS — Common Problems

When preparing the iOS app for development or release you may hit environment and build issues on macOS/Xcode. The most common problems and solutions are:

  • Incompatible Ruby version on macOS
  • Problem: The system Ruby that ships with macOS is often too old for CocoaPods or some Ruby gems, causing install/build errors.
  • Solution: Do not use the preinstalled system Ruby. Install a Ruby version manager such as rbenv or rvm, install a newer Ruby, and then install CocoaPods under that Ruby. Example using Homebrew + rbenv:
brew install rbenv
rbenv install desired_ruby_version
rbenv global desired_ruby_version
gem install cocoapods
  • Minimum iOS deployment target too low
  • Problem: Some pods or packages require a newer iOS deployment target than your project currently uses, which causes build errors.
  • Solution: Increase the iOS deployment target in ios/Podfile or in Xcode. Example Podfile change:
platform :ios, '13.0'

After changing the platform, run from the ios/ directory:

rm -rf Pods Podfile.lock
pod install --repo-update
  • CocoaPods errors (often Ruby/toolchain related)
  • Problem: pod install or pod update fails with native extension or gem build errors.
  • Solution: Ensure CocoaPods is installed with the Ruby from your version manager (not system Ruby). Also install Xcode command line tools and reinstall pods:
xcode-select --install
cd ios
rm -rf Pods Podfile.lock
pod install --repo-update

These steps resolve the majority of environment-related iOS build issues. If you still see errors, copy the exact error message and search for it—most CocoaPods/Xcode issues have documented fixes.

Web App

To be added