nano-pro/INSTALL.md

Nano Banana Pro - Server Installation Guide

Complete instructions for deploying Nano Banana Pro from git clone to production.

---

Prerequisites

• PHP 7.4+ (PHP 8.0+ recommended)
• Composer (PHP dependency manager)
• Git
• Web server (Apache/Nginx with PHP support)
• HTTPS (required for production with SSO)
• Google Gemini API Key (Get here)
• Azure AD Tenant (optional, for SSO)

---

Installation Steps

1. Clone Repository

# Clone from Bitbucket
git clone git@bitbucket.org:zlalani/nano-pro.git

# Navigate to directory
cd nano-pro

2. Install PHP Dependencies

# Install Composer dependencies (Firebase JWT library)
composer install

# Verify vendor directory created
ls -la vendor/

Expected output:

vendor/
├── autoload.php
├── composer/
└── firebase/
    └── php-jwt/

3. Configure Application

# Copy example config files
cp config.example.php config.php
cp .env.example .env

4. Add Google Gemini API Key

Edit config.php:

// Line 13: Add your Gemini API key
define('GEMINI_API_KEY', 'YOUR_ACTUAL_GEMINI_API_KEY_HERE');

Get API key from: https://aistudio.google.com/app/apikey

5. Configure Authentication (Optional)

Edit .env:

For Testing (No Authentication):

SSO_ENABLED=false
SSO_TENANT_ID=
SSO_CLIENT_ID=

For Production (With Azure AD SSO):

SSO_ENABLED=true
SSO_TENANT_ID=your-azure-tenant-id
SSO_CLIENT_ID=your-azure-app-client-id

See AUTH_README.md for complete Azure AD setup instructions.

6. Set Directory Permissions

# Create uploads directory if not exists
mkdir -p uploads/sessions

# Set proper permissions
chmod 755 uploads
chmod 755 uploads/sessions

# Ensure web server can write to uploads
chown -R www-data:www-data uploads/  # Ubuntu/Debian
# OR
chown -R apache:apache uploads/       # CentOS/RHEL
# OR
chown -R _www:_www uploads/           # macOS

7. Configure Web Server

Apache (.htaccess already included)

Ensure mod_rewrite is enabled:

sudo a2enmod rewrite
sudo systemctl restart apache2

Set document root to the application directory in your virtual host config.

Nginx

Add to your server block:

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

location ~ \.php$ {
    include snippets/fastcgi-php.conf;
    fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
}

# Protect uploads directory
location /uploads/ {
    deny all;
    return 403;
}

8. Test Installation

Visit these URLs to verify:

1. Main App: https://your-server.com/nano-pro/

   • Should load the image generator
   • If SSO enabled: Shows login page
   • If SSO disabled: Loads directly

2. Auth Test: https://your-server.com/nano-pro/auth-test.php

   • Shows SSO configuration
   • Shows authentication status
   • Shows user info (if authenticated)

3. Debug Info: Click "Toggle Debug Panel" in app

   • Shows session ID
   • Shows current image status
   • Shows conversation history count

10. Verify Everything Works

Test Checklist:

• Main page loads without errors
• Prompt Studio section displays
• Can select cameras/lenses/applications
• "Enhance Prompt with AI" button works
• Can generate images
• Images display correctly
• Image history shows recent generations
• Can download images
• Lightbox modal works (click main image)
• Conversation history displays
• Quick action buttons populate prompt
• If SSO enabled: Login/logout works

---

Directory Structure

After installation:

nano-pro/
├── .env                          # Environment config (gitignored)
├── .env.example                  # Environment template
├── .gitignore                    # Git ignore rules
├── .htaccess                     # Apache configuration
├── api.php                       # Image generation API
├── auth.php                      # Authentication API
├── auth-test.php                 # Auth debugging page
├── AuthMiddleware.php            # Auth orchestrator
├── AUTH_README.md                # Auth setup guide
├── cleanup.php                   # Image cleanup script
├── clear_session.php             # Clear session utility
├── composer.json                 # PHP dependencies
├── composer.lock                 # Dependency lock file
├── config.example.php            # Config template
├── config.php                    # Main config (gitignored)
├── debug.php                     # Debug utilities
├── debug_request.php             # Request debugging
├── enhance_prompt.php            # Prompt enhancement API
├── env_loader.php                # Environment loader
├── get_logs.php                  # Server logs API
├── index.php                     # Main application
├── INSTALL.md                    # This file
├── JWTValidator.php              # JWT token validator
├── README.md                     # Project readme
├── session_manager.php           # Session management
├── uploads/                      # User image storage
│   ├── .htaccess                 # Protect uploads
│   └── sessions/                 # Session directories
│       └── {session_id}/         # Per-user storage
│           └── images/           # User images
└── vendor/                       # Composer dependencies
    ├── autoload.php
    └── firebase/
        └── php-jwt/

---

Configuration Files

config.php (Main Configuration)

<?php
require_once __DIR__ . '/env_loader.php';

// Google Gemini API Key
define('GEMINI_API_KEY', 'YOUR_KEY_HERE');

// MSAL / Azure AD SSO
define('SSO_ENABLED', getenv('SSO_ENABLED') === 'true');
define('SSO_TENANT_ID', getenv('SSO_TENANT_ID') ?: '');
define('SSO_CLIENT_ID', getenv('SSO_CLIENT_ID') ?: '');

// Session configuration
ini_set('session.gc_maxlifetime', 3600);
ini_set('session.cookie_lifetime', 3600);

// Error reporting
error_reporting(E_ALL);
ini_set('display_errors', 1);
ini_set('log_errors', 1);

.env (Environment Variables)

# Authentication toggle
SSO_ENABLED=false

# Azure AD credentials (when SSO enabled)
SSO_TENANT_ID=
SSO_CLIENT_ID=

---

Troubleshooting

"Composer not found"

# Install Composer
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

"Permission denied" errors

# Fix uploads directory permissions
sudo chown -R www-data:www-data uploads/
sudo chmod -R 755 uploads/

"Class 'Firebase\JWT\JWT' not found"

# Re-run composer install
composer install

# Verify autoload file exists
ls -la vendor/autoload.php

Images not saving

# Check uploads directory exists and is writable
ls -la uploads/
ls -la uploads/sessions/

# Create if missing
mkdir -p uploads/sessions
chmod 755 uploads/sessions

"API key not configured" error

# Verify config.php has valid API key
grep GEMINI_API_KEY config.php

# Should show:
# define('GEMINI_API_KEY', 'AIzaSy...');

Authentication not working

# Check SSO configuration
php auth-test.php

# Verify .env file loaded
cat .env

# Check error logs
tail -f error_log

Cleanup script not running

# Test manually first
php cleanup.php

# Should show:
# === Image Cleanup Report ===
# Timestamp: 2025-12-16 ...
# Images cleaned: X

---

Production Deployment Checklist

Before going live:

Required:

• PHP 7.4+ installed on server
• Composer dependencies installed (vendor/ exists)
• config.php created with valid Gemini API key
• .env file created and configured
• uploads/sessions/ directory created with write permissions
• .htaccess protecting uploads directory
• Web server configured (Apache/Nginx)
• Cron job set up for cleanup.php

If Using SSO:

• HTTPS enabled on server
• Azure AD app registration created
• Redirect URI matches server URL exactly
• .env has correct SSO_TENANT_ID and SSO_CLIENT_ID
• SSO_ENABLED=true in .env
• Tested login/logout flow

Security:

• config.php is gitignored (contains API key)
• .env is gitignored (contains credentials)
• vendor/ is gitignored
• uploads/sessions/ is gitignored
• Error display disabled in production (display_errors = 0)
• HTTPS enforced for production

Testing:

• Visit main app - loads without errors
• Generate a test image - works
• Enhance prompt feature - works
• Image history displays - works
• Download images - works
• Lightbox modal - works
• Visit auth-test.php - shows correct config

---

Quick Start (TL;DR)

# 1. Clone
git clone git@bitbucket.org:zlalani/nano-pro.git
cd nano-pro

# 2. Install dependencies
composer install

# 3. Configure
cp config.example.php config.php
cp .env.example .env

# Edit config.php - add your Gemini API key
nano config.php

# 4. Set permissions
mkdir -p uploads/sessions
chmod 755 uploads/sessions

# 5. Test
# Visit: https://your-server.com/nano-pro/
# Visit: https://your-server.com/nano-pro/auth-test.php

# 6. Done!
# Note: Images auto-cleanup on app launch (no cron needed)

---

Updating the Application

# Pull latest changes
git pull origin master

# Update dependencies
composer install

# Clear PHP opcode cache if using OPcache
# (or restart PHP-FPM)
sudo systemctl restart php8.1-fpm

# No database migrations needed - uses file storage

---

Backup & Restore

Backup

# Backup user images (last 24 hours)
tar -czf backup-images-$(date +%Y%m%d).tar.gz uploads/sessions/

# Backup configuration
tar -czf backup-config-$(date +%Y%m%d).tar.gz config.php .env

Restore

# Restore images
tar -xzf backup-images-YYYYMMDD.tar.gz

# Restore configuration
tar -xzf backup-config-YYYYMMDD.tar.gz

# Set permissions
chmod 755 uploads/sessions/

---

Automatic Image Cleanup

No cron job required! The application automatically cleans up expired images:

• Cleanup runs automatically when users launch the app (~10% of sessions)
• Finds images older than 24 hours across all user sessions
• Deletes expired images and metadata files
• Removes empty session directories
• Logs cleanup activity to error_log

Manual cleanup (if needed):

php cleanup.php

---

Monitoring

Check Application Status

# Visit auth test page
curl https://your-server.com/nano-pro/auth-test.php

# Check PHP error logs
tail -f /var/log/apache2/error.log
# OR
tail -f /var/log/nginx/error.log

# Check cleanup logs
tail -f cleanup.log

Monitor Disk Usage

# Check uploads directory size
du -sh uploads/sessions/

# Count active sessions
ls -1 uploads/sessions/ | wc -l

# List sessions older than 24 hours
find uploads/sessions/ -type d -mtime +1

---

Support

• Application issues: Check error_log in application directory
• Authentication issues: Run auth-test.php
• Image storage issues: Check uploads/sessions/ permissions
• API errors: Check browser console and PHP error logs
• Cleanup issues: Run php cleanup.php manually

---

Security Notes

• Never commit config.php or .env to git (they're gitignored)
• Always use HTTPS in production for SSO
• httpOnly cookies protect against XSS
• Images auto-expire after 24 hours
• Upload directory protected by .htaccess
• Each user has isolated session storage

---

Performance Optimization

Enable OPcache (Recommended)

Add to php.ini:

opcache.enable=1
opcache.memory_consumption=128
opcache.max_accelerated_files=4000
opcache.revalidate_freq=60

Increase PHP Limits for Large Images

Add to php.ini:

upload_max_filesize = 20M
post_max_size = 20M
max_execution_time = 120
memory_limit = 256M

Adjust Session Lifetime

In config.php:

ini_set('session.gc_maxlifetime', 86400);  // 24 hours
ini_set('session.cookie_lifetime', 86400);

---

Maintenance

Weekly Tasks

• Check disk space: df -h
• Review error logs for issues
• Verify cleanup cron is running

Monthly Tasks

• Update Composer dependencies: composer update
• Review and rotate API keys if needed
• Check Azure AD token expiration policies

As Needed

• Clear old sessions: php cleanup.php
• Restart PHP-FPM after config changes
• Monitor API usage quotas (Gemini API)

---

Common Issues & Solutions

Issue: "No image data found in API response"

Solution:

• Check Gemini API key is valid
• Verify API quota not exceeded
• Check prompt doesn't violate content policies

Issue: Authentication keeps redirecting

Solution:

• Verify Azure AD redirect URI matches exactly
• Check HTTPS is enabled
• Clear browser cookies and try again

Issue: Images not displaying in history

Solution:

• Check file permissions on uploads/
• Verify cleanup script hasn't deleted images
• Check session_manager.php error logs

Issue: Composer install fails

Solution:

# Update Composer
composer self-update

# Clear cache
composer clear-cache

# Try again
composer install

---

Uninstallation

# Stop cron job
crontab -e
# Remove the cleanup.php line

# Remove application files
rm -rf /path/to/nano-pro

# Remove user data (optional)
# WARNING: This deletes all user images!
# rm -rf uploads/sessions/*

---

Getting Help

1. Check error_log file in application directory
2. Visit auth-test.php for authentication status
3. Click "Toggle Debug Panel" in app for session info
4. Review AUTH_README.md for SSO setup
5. Check server error logs (/var/log/apache2/ or /var/log/nginx/)