wip
This commit is contained in:
Trey t
255
ENVIRONMENT_SETUP.md
Normal file
255
ENVIRONMENT_SETUP.md
Normal file
@@ -0,0 +1,255 @@
|
||||
# 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!
|
||||
Reference in New Issue
Block a user