honeyDueKMP/ENVIRONMENT_SETUP.md

Environment Configuration Guide

This guide explains how to easily switch between local development and the dev server when developing the HoneyDue iOS and Android apps.

Quick Start

To switch environments, change ONE line in ApiConfig.kt:

// File: composeApp/src/commonMain/kotlin/com/honeydue/shared/network/ApiConfig.kt

object ApiConfig {
    // ⚠️ CHANGE THIS LINE ⚠️
    val CURRENT_ENV = Environment.LOCAL  // or Environment.DEV
}

Environment Options

1. Local Development (Environment.LOCAL)

Use this when:

• Running the Django API on your local machine
• Debugging API changes
• Working offline

Connects to:

• Android: http://10.0.2.2:8000/api (Android emulator localhost alias)
• iOS: http://127.0.0.1:8000/api (iOS simulator localhost)

Setup:

val CURRENT_ENV = Environment.LOCAL

Requirements:

• Django API running on http://localhost:8000
• Use ./dev.sh to start the API with auto-reload

2. Dev Server (Environment.DEV)

Use this when:

• Testing against the deployed server
• You don't have the API running locally
• Testing with real data

Connects to:

• Both platforms: https://honeyDue.treytartt.com/api

Setup:

val CURRENT_ENV = Environment.DEV

Requirements:

• Internet connection
• Dev server must be running and accessible

Step-by-Step Instructions

Switching to Local Development

1. Start your local API:

   cd honeyDueAPI
   ./dev.sh
   

2. Update ApiConfig.kt:

   val CURRENT_ENV = Environment.LOCAL
   

3. Rebuild the app:

   • Android: Sync Gradle and run
   • iOS: Clean build folder (⇧⌘K) and run

4. Verify in logs:

   🌐 API Client initialized
   📍 Environment: Local (10.0.2.2:8000)
   🔗 Base URL: http://10.0.2.2:8000/api
   

Switching to Dev Server

1. Update ApiConfig.kt:

   val CURRENT_ENV = Environment.DEV
   

2. Rebuild the app:

   • Android: Sync Gradle and run
   • iOS: Clean build folder (⇧⌘K) and run

3. Verify in logs:

   🌐 API Client initialized
   📍 Environment: Dev Server (honeyDue.treytartt.com)
   🔗 Base URL: https://honeyDue.treytartt.com/api
   

Platform-Specific Localhost Addresses

The localhost addresses are automatically determined by platform:

Platform	Localhost Address	Reason
Android Emulator	10.0.2.2	Special alias for host machine's localhost
iOS Simulator	127.0.0.1	Standard localhost (simulator shares network with host)
Android Device	Your machine's IP	Must manually set in ApiClient.android.kt
iOS Device	Your machine's IP	Must manually set in ApiClient.ios.kt

Testing on Physical Devices

If you need to test on a physical device with local API:

1. Find your machine's IP address:

   # macOS/Linux
   ifconfig | grep "inet "
   
   # Look for something like: 192.168.1.xxx
   

2. Update platform-specific file:

   Android (ApiClient.android.kt):

   actual fun getLocalhostAddress(): String = "192.168.1.xxx"
   

   iOS (ApiClient.ios.kt):

   actual fun getLocalhostAddress(): String = "192.168.1.xxx"
   

3. Ensure your device is on the same WiFi network as your machine

4. Update Django's ALLOWED_HOSTS:

   # honeyDueAPI/honeyDue/settings.py
   ALLOWED_HOSTS = ['localhost', '127.0.0.1', '192.168.1.xxx']
   

File Structure

HoneyDueKMM/composeApp/src/
├── commonMain/kotlin/com/honeydue/shared/network/
│   ├── ApiConfig.kt              # ⭐ TOGGLE ENVIRONMENT HERE
│   └── ApiClient.kt              # Uses ApiConfig
├── androidMain/kotlin/com/honeydue/shared/network/
│   └── ApiClient.android.kt      # Android localhost: 10.0.2.2
└── iosMain/kotlin/com/honeydue/shared/network/
    └── ApiClient.ios.kt          # iOS localhost: 127.0.0.1

Troubleshooting

Android: "Unable to connect to server"

Problem: Android can't reach localhost

Solutions:

1. Use 10.0.2.2 instead of localhost or 127.0.0.1
2. Make sure API is running on 0.0.0.0:8000, not just 127.0.0.1:8000
3. Check that CURRENT_ENV = Environment.LOCAL

iOS: "Connection refused"

Problem: iOS simulator can't connect

Solutions:

1. Use 127.0.0.1 for iOS simulator
2. Make sure Django is running
3. Try accessing http://127.0.0.1:8000/api in Safari on your Mac
4. Check firewall settings

Dev Server: SSL/Certificate errors

Problem: HTTPS connection issues

Solutions:

1. Verify server is accessible: curl https://honeyDue.treytartt.com/api
2. Check that SSL certificate is valid
3. Make sure you're using https:// not http://

Changes not taking effect

Problem: Environment change not working

Solutions:

1. Clean and rebuild:
   • Android: Build → Clean Project, then rebuild
   • iOS: Product → Clean Build Folder (⇧⌘K)
2. Invalidate caches:
   • Android Studio: File → Invalidate Caches
3. Check logs for current environment:
   • Look for 🌐 API Client initialized log message

Best Practices

1. Commit with LOCAL: Always commit code with Environment.LOCAL so teammates use their local API by default

2. Document API changes: If you change the API, update both local and dev server

3. Test both environments: Before deploying, test with both LOCAL and DEV

4. Use dev server for demos: Switch to DEV when showing the app to others

5. Keep localhost addresses: Don't commit IP addresses, use the platform-specific aliases

Quick Reference

Action	Command/File
Toggle environment	Edit ApiConfig.kt → CURRENT_ENV
Start local API	cd honeyDueAPI && ./dev.sh
Android localhost	10.0.2.2:8000
iOS localhost	127.0.0.1:8000
Dev server	https://honeyDue.treytartt.com
View current env	Check app logs for 🌐 emoji

Example Workflow

Morning: Start work

// ApiConfig.kt
val CURRENT_ENV = Environment.LOCAL  // ✅ Use local API

cd honeyDueAPI
./dev.sh  # Start local server
# Work on features...

Testing: Check remote data

// ApiConfig.kt
val CURRENT_ENV = Environment.DEV  // ✅ Use dev server
# Rebuild app and test

Before commit

// ApiConfig.kt
val CURRENT_ENV = Environment.LOCAL  // ✅ Reset to LOCAL
git add .
git commit -m "Add new feature"

---

Need help? Check the logs when the app starts - they'll tell you exactly which environment and URL is being used!