# 📱 Flutter Frontend Deployment Guide - LuckyChit

Complete guide to deploy and update your Flutter app UI changes in production.

---

## 📋 Deployment Options

Your Flutter app can be deployed as:
1. **Web App** (accessible via browser)
2. **Android App** (APK/AAB for Play Store)
3. **iOS App** (IPA for App Store)

---

## 🌐 Option 1: Web Deployment (Recommended for Quick Updates)

### Initial Setup

#### Step 1: Build Flutter for Web

```bash
cd luckychit

# Clean previous builds
flutter clean

# Get dependencies
flutter pub get

# Build for production
flutter build web --release
```

This creates optimized files in `luckychit/build/web/`

#### Step 2: Deploy Web Files

**Method A: Using nginx (Recommended)**

```bash
# Copy built files to web server directory
sudo mkdir -p /var/www/luckychit
sudo cp -r build/web/* /var/www/luckychit/

# Set permissions
sudo chown -R www-data:www-data /var/www/luckychit
sudo chmod -R 755 /var/www/luckychit
```

**Configure nginx:**

Create/edit `/etc/nginx/sites-available/luckychit`:

```nginx
server {
    listen 80;
    server_name your-domain.com;  # or your-server-ip

    # Flutter Web App
    location / {
        root /var/www/luckychit;
        index index.html;
        try_files $uri $uri/ /index.html;
        
        # Disable cache for index.html (always get latest)
        location = /index.html {
            add_header Cache-Control "no-cache, no-store, must-revalidate";
            add_header Pragma "no-cache";
            add_header Expires 0;
        }
        
        # Cache static assets for 1 year
        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
            expires 1y;
            add_header Cache-Control "public, immutable";
        }
    }

    # Backend API (if on same server)
    location /api {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}
```

Enable and restart nginx:

```bash
sudo ln -s /etc/nginx/sites-available/luckychit /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
```

**Method B: Using PM2 + http-server**

```bash
# Install http-server globally
npm install -g http-server

# Start with PM2
cd luckychit
pm2 start http-server --name "luckychit-web" -- -p 8080 -c-1 -d false build/web

# Save
pm2 save
```

**Method C: Using PM2 + Express (Custom Server)**

Create `luckychit/web-server.js`:

```javascript
const express = require('express');
const path = require('path');
const app = express();
const PORT = process.env.PORT || 8080;

// Serve static files with proper cache headers
app.use(express.static(path.join(__dirname, 'build/web'), {
  maxAge: '1y',
  immutable: true,
  setHeaders: (res, filePath) => {
    // Don't cache index.html
    if (filePath.endsWith('index.html')) {
      res.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate');
    }
  }
}));

// Handle Flutter routes (SPA)
app.get('*', (req, res) => {
  res.sendFile(path.join(__dirname, 'build/web', 'index.html'));
});

app.listen(PORT, '0.0.0.0', () => {
  console.log(`✅ Flutter web app running on port ${PORT}`);
});
```

Then:

```bash
cd luckychit
npm install express
pm2 start web-server.js --name "luckychit-web"
pm2 save
```

---

## 🔄 Updating Web App (How to Push Changes)

### Quick Update Script

Create `luckychit/deploy-web.sh`:

```bash
#!/bin/bash

echo "🚀 Deploying Flutter Web Updates"
echo "================================="
echo ""

# Clean and build
echo "🧹 Cleaning previous build..."
flutter clean

echo "📦 Getting dependencies..."
flutter pub get

echo "🔨 Building for web (production)..."
flutter build web --release

if [ $? -eq 0 ]; then
    echo ""
    echo "✅ Build successful!"
    echo ""
    
    # Copy to nginx directory
    echo "📤 Deploying to web server..."
    sudo cp -r build/web/* /var/www/luckychit/
    
    # Or restart PM2 if using PM2
    # pm2 restart luckychit-web
    
    echo ""
    echo "✅ Deployment complete!"
    echo "🌐 Your app is now live with the latest changes!"
else
    echo ""
    echo "❌ Build failed. Please check errors above."
    exit 1
fi
```

**Use it:**

```bash
cd luckychit
chmod +x deploy-web.sh
./deploy-web.sh
```

---

## 📱 Option 2: Android Deployment

### Build Android APK

**For Testing:**

```bash
cd luckychit

# Debug APK
flutter build apk --debug

# Release APK
flutter build apk --release
```

APK location: `build/app/outputs/flutter-apk/app-release.apk`

### Build Android App Bundle (For Play Store)

```bash
cd luckychit

# Build release bundle
flutter build appbundle --release
```

Bundle location: `build/app/outputs/bundle/release/app-release.aab`

### Deploy to Users

**Method 1: Direct Distribution**

```bash
# Copy APK to server
scp build/app/outputs/flutter-apk/app-release.apk user@server:/var/www/downloads/

# Users download and install from:
# https://your-domain.com/downloads/app-release.apk
```

**Method 2: Google Play Store**

1. Sign in to [Google Play Console](https://play.google.com/console)
2. Create app (if first time)
3. Go to **Release** → **Production**
4. Click **Create new release**
5. Upload `app-release.aab`
6. Add release notes
7. Review and rollout

### Signing Android App (Required for Play Store)

**Create keystore (first time only):**

```bash
cd luckychit/android

keytool -genkey -v -keystore luckychit-key.jks \
  -keyalg RSA -keysize 2048 -validity 10000 \
  -alias luckychit
```

**Create `android/key.properties`:**

```properties
storePassword=your_keystore_password
keyPassword=your_key_password
keyAlias=luckychit
storeFile=/path/to/luckychit-key.jks
```

**Update `android/app/build.gradle`:**

```gradle
// Add before android block
def keystoreProperties = new Properties()
def keystorePropertiesFile = rootProject.file('key.properties')
if (keystorePropertiesFile.exists()) {
    keystoreProperties.load(new FileInputStream(keystorePropertiesFile))
}

android {
    // ... existing config ...
    
    signingConfigs {
        release {
            keyAlias keystoreProperties['keyAlias']
            keyPassword keystoreProperties['keyPassword']
            storeFile keystoreProperties['storeFile'] ? file(keystoreProperties['storeFile']) : null
            storePassword keystoreProperties['storePassword']
        }
    }
    
    buildTypes {
        release {
            signingConfig signingConfigs.release
        }
    }
}
```

Now build:

```bash
flutter build appbundle --release
```

---

## 🍎 Option 3: iOS Deployment

### Build iOS App

```bash
cd luckychit

# Build for iOS
flutter build ios --release
```

### Deploy to App Store

1. Open Xcode: `open ios/Runner.xcworkspace`
2. Select **Product** → **Archive**
3. Once archived, click **Distribute App**
4. Choose **App Store Connect**
5. Follow the upload wizard

**Or use command line:**

```bash
cd ios
fastlane deliver
```

---

## 🚀 Production Update Workflow

### For Web (Quickest)

```bash
# On your development machine
cd luckychit
flutter build web --release

# Upload to server
scp -r build/web/* user@server:/tmp/flutter-web/

# On server
ssh user@server
sudo cp -r /tmp/flutter-web/* /var/www/luckychit/
# Or if using PM2:
# pm2 restart luckychit-web
```

### For Mobile Apps

1. **Make changes** in your code
2. **Update version** in `pubspec.yaml`:
   ```yaml
   version: 1.0.1+2  # version+buildNumber
   ```
3. **Build:**
   ```bash
   # Android
   flutter build appbundle --release
   
   # iOS
   flutter build ios --release
   ```
4. **Upload to stores**

---

## 🔧 Common Issues & Solutions

### Web App Not Updating (Cache Issues)

**Problem:** Users still see old version

**Solution 1: Force reload**
- Chrome: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
- Clear browser cache

**Solution 2: Update index.html cache headers**

Edit `luckychit/web/index.html` - add to `<head>`:

```html
<meta http-equiv="Cache-Control" content="no-cache, no-store, must-revalidate">
<meta http-equiv="Pragma" content="no-cache">
<meta http-equiv="Expires" content="0">
```

**Solution 3: Version your assets**

Update `pubspec.yaml`:

```yaml
version: 1.0.1+2  # Increment this
```

Rebuild:

```bash
flutter clean
flutter pub get
flutter build web --release
```

### Android Build Fails

**Common issues:**

1. **Gradle version mismatch:**
   ```bash
   cd android
   ./gradlew clean
   cd ..
   flutter clean
   flutter build apk
   ```

2. **Signing issues:**
   - Check `key.properties` exists and paths are correct
   - Verify keystore password

3. **Memory issues:**
   ```bash
   export GRADLE_OPTS="-Xmx4096m"
   flutter build apk --release
   ```

### iOS Build Fails

1. **Pod issues:**
   ```bash
   cd ios
   rm Podfile.lock
   pod install
   cd ..
   flutter build ios
   ```

2. **Provisioning profile:**
   - Update in Xcode → Signing & Capabilities

---

## 📦 Automated Deployment Scripts

### Complete Web Deployment Script

Create `flutter-deploy-full.sh`:

```bash
#!/bin/bash

# LuckyChit Flutter Web Deployment Script
# Run from project root

SERVER_USER="your-user"
SERVER_HOST="your-server-ip"
WEB_DIR="/var/www/luckychit"

echo "🚀 LuckyChit Flutter Web Deployment"
echo "===================================="
echo ""

# Build
cd luckychit
echo "🧹 Cleaning..."
flutter clean

echo "📦 Getting dependencies..."
flutter pub get

echo "🔨 Building for web..."
flutter build web --release

if [ $? -ne 0 ]; then
    echo "❌ Build failed!"
    exit 1
fi

echo "✅ Build successful!"
echo ""

# Upload to server
echo "📤 Uploading to production server..."
rsync -avz --delete build/web/ $SERVER_USER@$SERVER_HOST:$WEB_DIR/

if [ $? -eq 0 ]; then
    echo ""
    echo "✅ Deployment complete!"
    echo "🌐 Your app is now live!"
    echo ""
    echo "Clear browser cache (Ctrl+Shift+R) to see changes"
else
    echo "❌ Upload failed!"
    exit 1
fi
```

### Android Auto-Build Script

Create `luckychit/build-android.sh`:

```bash
#!/bin/bash

echo "🤖 Building Android Release"
echo "============================"
echo ""

# Clean
echo "🧹 Cleaning..."
flutter clean

# Get dependencies
echo "📦 Getting dependencies..."
flutter pub get

# Build
echo "🔨 Building APK..."
flutter build apk --release

echo "🔨 Building App Bundle..."
flutter build appbundle --release

echo ""
echo "✅ Build complete!"
echo ""
echo "📦 APK: build/app/outputs/flutter-apk/app-release.apk"
echo "📦 AAB: build/app/outputs/bundle/release/app-release.aab"
echo ""
echo "Upload AAB to Google Play Console"
```

---

## 📊 Version Management

### Update Version in pubspec.yaml

```yaml
name: luckychit
description: Digital Chit Fund Management
version: 1.0.2+3  # Format: major.minor.patch+buildNumber

# Increment for each release:
# - major: Breaking changes (2.0.0)
# - minor: New features (1.1.0)
# - patch: Bug fixes (1.0.1)
# - buildNumber: Each build (1.0.0+5)
```

### Check Current Version

```bash
cd luckychit
grep "^version:" pubspec.yaml
```

---

## ✅ Deployment Checklist

### Before Deploying

- [ ] All changes tested locally
- [ ] Version incremented in `pubspec.yaml`
- [ ] Backend API URL updated (if changed)
- [ ] `flutter clean` executed
- [ ] `flutter pub get` executed
- [ ] Build completed successfully
- [ ] No errors in console

### After Deploying

- [ ] Web: Files copied to `/var/www/luckychit/`
- [ ] Web: nginx restarted (if needed)
- [ ] Test app in browser (hard refresh)
- [ ] Test on mobile device (if mobile build)
- [ ] Check all features work
- [ ] Monitor for errors

---

## 🎯 Quick Reference

```bash
# Clean build
flutter clean && flutter pub get

# Web (production)
flutter build web --release

# Android APK
flutter build apk --release

# Android Bundle (Play Store)
flutter build appbundle --release

# iOS
flutter build ios --release

# Check version
grep "^version:" pubspec.yaml
```

---

## 📱 Testing Builds

### Web
```bash
cd luckychit/build/web
python3 -m http.server 8000
# Visit: http://localhost:8000
```

### Android
```bash
# Install on connected device
flutter install

# Or manually install APK
adb install build/app/outputs/flutter-apk/app-release.apk
```

---

**Your Flutter frontend is now ready to deploy and update! 🎉**

For backend updates, see: `PM2_PRODUCTION_GUIDE.md`