256 lines
6.5 KiB
Markdown
256 lines
6.5 KiB
Markdown
# Environment Configuration Guide
|
|
|
|
This guide explains how to easily switch between local development and the dev server when developing the MyCrib iOS and Android apps.
|
|
|
|
## Quick Start
|
|
|
|
**To switch environments, change ONE line in `ApiConfig.kt`:**
|
|
|
|
```kotlin
|
|
// File: composeApp/src/commonMain/kotlin/com/mycrib/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:**
|
|
```kotlin
|
|
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://mycrib.treytartt.com/api`
|
|
|
|
**Setup:**
|
|
```kotlin
|
|
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:**
|
|
```bash
|
|
cd myCribAPI
|
|
./dev.sh
|
|
```
|
|
|
|
2. **Update `ApiConfig.kt`:**
|
|
```kotlin
|
|
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`:**
|
|
```kotlin
|
|
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 (mycrib.treytartt.com)
|
|
🔗 Base URL: https://mycrib.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:**
|
|
```bash
|
|
# macOS/Linux
|
|
ifconfig | grep "inet "
|
|
|
|
# Look for something like: 192.168.1.xxx
|
|
```
|
|
|
|
2. **Update platform-specific file:**
|
|
|
|
**Android** (`ApiClient.android.kt`):
|
|
```kotlin
|
|
actual fun getLocalhostAddress(): String = "192.168.1.xxx"
|
|
```
|
|
|
|
**iOS** (`ApiClient.ios.kt`):
|
|
```kotlin
|
|
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`:**
|
|
```python
|
|
# myCribAPI/myCrib/settings.py
|
|
ALLOWED_HOSTS = ['localhost', '127.0.0.1', '192.168.1.xxx']
|
|
```
|
|
|
|
## File Structure
|
|
|
|
```
|
|
MyCribKMM/composeApp/src/
|
|
├── commonMain/kotlin/com/mycrib/shared/network/
|
|
│ ├── ApiConfig.kt # ⭐ TOGGLE ENVIRONMENT HERE
|
|
│ └── ApiClient.kt # Uses ApiConfig
|
|
├── androidMain/kotlin/com/mycrib/shared/network/
|
|
│ └── ApiClient.android.kt # Android localhost: 10.0.2.2
|
|
└── iosMain/kotlin/com/mycrib/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://mycrib.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 myCribAPI && ./dev.sh` |
|
|
| Android localhost | `10.0.2.2:8000` |
|
|
| iOS localhost | `127.0.0.1:8000` |
|
|
| Dev server | `https://mycrib.treytartt.com` |
|
|
| View current env | Check app logs for `🌐` emoji |
|
|
|
|
## Example Workflow
|
|
|
|
**Morning: Start work**
|
|
```kotlin
|
|
// ApiConfig.kt
|
|
val CURRENT_ENV = Environment.LOCAL // ✅ Use local API
|
|
```
|
|
```bash
|
|
cd myCribAPI
|
|
./dev.sh # Start local server
|
|
# Work on features...
|
|
```
|
|
|
|
**Testing: Check remote data**
|
|
```kotlin
|
|
// ApiConfig.kt
|
|
val CURRENT_ENV = Environment.DEV // ✅ Use dev server
|
|
# Rebuild app and test
|
|
```
|
|
|
|
**Before commit**
|
|
```kotlin
|
|
// 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!
|