diff --git a/.env.example b/.env.example index 53af9d90d..02d1fc6b4 100644 --- a/.env.example +++ b/.env.example @@ -1,30 +1,23 @@ # ComfyUI Environment Variables -# Copy this file to .env and fill in your actual values -# =========================== -# Nano Banana API Configuration -# =========================== - -# Google AI API Key (Primary Method - Simpler) -# Get your API key from: https://makersuite.google.com/app/apikey -# This is the recommended approach for both local and RunPod deployments +# Google AI API Key for Nano Banana nodes +# Get your API key from: https://aistudio.google.com/app/apikey GOOGLE_API_KEY=your_google_api_key_here -# Vertex AI Configuration (Alternative Method - Optional) -# Only needed if using Vertex AI instead of the Google AI API -# PROJECT_ID=your_gcp_project_id +# Optional: Vertex AI configuration (alternative to GOOGLE_API_KEY) +# If using Vertex AI with Application Default Credentials (ADC) +# PROJECT_ID=your-gcp-project-id # LOCATION=us-central1 -# =========================== -# Other Environment Variables -# =========================== +# Timezone +TZ=America/Chicago -# OpenTelemetry (Optional - for tracing/monitoring) -# Uncomment and configure if you want to enable OTEL instrumentation +# User/Group IDs (for file permissions) +PUID=1000 +PGID=1000 + +# Optional: OpenTelemetry configuration (for observability) +# Uncomment and configure these if you want to enable OpenTelemetry instrumentation # OTEL_EXPORTER_OTLP_ENDPOINT=http://your-otel-collector:4317 # OTEL_SERVICE_NAME=comfyui # OTEL_RESOURCE_ATTRIBUTES=service.name=comfyui - -# Install curated custom nodes on startup (Optional) -# Set to "true" to automatically install a curated list of custom nodes -# INSTALL_CURATED_NODES=false diff --git a/PLAN.md b/PLAN.md index b4b9db1ec..6c4492bfe 100644 --- a/PLAN.md +++ b/PLAN.md @@ -1,26 +1,60 @@ # Nano Banana Environment Configuration ## Issues Identified + 1. **ComfyUI-Manager Security Alert**: ComfyUI version outdated; Manager in frozen mode (installations blocked). Defer to separate branch. 2. **API Key Missing**: `GOOGLE_API_KEY` not configured; Nano Banana fails with "No valid credentials found." ## Design Decisions + - **Local Docker**: Use `.env` file loaded via `docker-compose.yml` `env_file` directive - **RunPod Serverless**: Environment variables set in template interface (per [RunPod docs](https://docs.runpod.io/serverless/development/environment-variables)); code reads `os.environ` - **Nano Banana Auth**: Supports two methods: - API approach: `GOOGLE_API_KEY` env var (simpler, primary) - Vertex AI: `PROJECT_ID` + `LOCATION` + ADC (optional, document only) +- **Container Rebuild Strategy**: Clean and rebuild containers before testing to ensure fresh state ## Implementation Steps -### Step 1: Create PLAN.md and .env.example +### Pre-Hook: Clean and Rebuild Container (Before Testing) + **IMPLEMENTATION:** + +- Stop and remove existing containers: `docker compose down` or `docker stop comfy && docker rm comfy` +- Remove old images (optional, for clean rebuild): `docker compose build --no-cache` or `docker rmi [image-name]` +- Rebuild Docker image from root `Dockerfile`: `docker compose build` +- Expected outcome: Fresh container image built from latest Dockerfile +- Success criteria: Build completes without errors; image ready for testing + +**WHEN TO RUN:** + +- Before Step 4 (Local validation) - critical +- Before any testing/validation steps +- When Dockerfile or entrypoint scripts change + +**GIT TRACKING:** + +- No commit needed (pre-hook step) +- Document in PR description as testing prerequisite + +**CHECKPOINT:** + +- Natural stopping point: After successful build +- Rollback: Use previous image if build fails + +--- + +### Step 1: Create PLAN.md and .env.example + +**IMPLEMENTATION:** + - Create `PLAN.md` at repo root with this plan (living document) - Create `.env.example` with `GOOGLE_API_KEY` placeholder and commented Vertex AI vars - Expected outcome: Planning artifact tracked; env template ready - Success criteria: Both files committed; `.env.example` has clear comments **GIT TRACKING:** + - Commit after both files created - Message: `[ENV-1] Add plan and env example for Nano Banana API keys` - Branch: `feature/comfy-nano-banana-setup` (existing) @@ -28,25 +62,30 @@ - PR: Update draft PR description with checklist **USER FEEDBACK TOUCHPOINT:** + - Who: {users} - What to show: PR diff showing `.env.example` content - Feedback needed: "Does `.env.example` cover your needs? Any additional vars?" - Blocking: Non-blocking (proceed if no response) **CHECKPOINT:** + - Natural stopping point: After commit - Rollback: Delete files and revert commit --- ### Step 2: Wire .env into docker-compose.yml + **IMPLEMENTATION:** + - Add `env_file: .env` to `comfyui` service - Add `GOOGLE_API_KEY` to `environment` section (passes through from `.env`) - Expected outcome: Container receives env vars from `.env` file -- Success criteria: `docker-compose config` shows env_file and environment vars +- Success criteria: `docker compose config` shows env_file and environment vars **GIT TRACKING:** + - Commit after docker-compose.yml change - Message: `[ENV-2] Wire .env file into docker-compose for Nano Banana` - Branch: Same feature branch @@ -54,25 +93,30 @@ - PR: Update checklist, add compose snippet to PR description **USER FEEDBACK TOUCHPOINT:** + - Who: {users} - What to show: Diff of docker-compose.yml changes - Feedback needed: "Confirm env_file approach works for your local setup" - Blocking: Non-blocking **CHECKPOINT:** + - Natural stopping point: After commit - Rollback: Revert docker-compose.yml change --- ### Step 3: Protect secrets in Git + **IMPLEMENTATION:** + - Add `.env` to `.gitignore` - Ensure `.env.example` remains tracked (not ignored) - Expected outcome: Secrets never committed - Success criteria: `git status` shows `.env` ignored; `.env.example` tracked **GIT TRACKING:** + - Commit after .gitignore update - Message: `[ENV-3] Ignore .env file, keep example tracked` - Branch: Same feature branch @@ -80,27 +124,35 @@ - PR: Update checklist **USER FEEDBACK TOUCHPOINT:** + - Who: {users} - What to show: .gitignore diff - Feedback needed: "Confirm .env should be ignored" - Blocking: Non-blocking **CHECKPOINT:** + - Natural stopping point: After commit - Rollback: Revert .gitignore change --- ### Step 4: Local validation with real API key + +**PREREQUISITE: Run Pre-Hook (Clean and Rebuild Container)** + **IMPLEMENTATION:** + +- Run pre-hook: Clean containers and rebuild image - Create local `.env` file (not committed) with user's `GOOGLE_API_KEY` -- Restart container: `docker restart comfy` +- Start container: `docker compose up -d` (or `docker compose up` for logs) - Verify in logs: No "No valid credentials found" error - Test in UI: Nano Banana nodes visible and functional - Expected outcome: Node authenticates successfully - Success criteria: Logs show successful auth; nodes work in ComfyUI UI **GIT TRACKING:** + - Commit (empty or documentation) after validation - Message: `[ENV-4] Validate Nano Banana with env-based API key - validates auth` - Branch: Same feature branch @@ -108,19 +160,23 @@ - PR: Update checklist, attach log snippet showing successful auth **USER FEEDBACK TOUCHPOINT:** + - Who: {users} - What to show: Log snippet showing successful auth; screenshot of nodes in UI - Feedback needed: "Confirm API key authentication works; nodes functional?" - Blocking: Non-blocking (preferred before merge) **CHECKPOINT:** + - Natural stopping point: After validation commit - Rollback: Remove `.env`, restart container, verify error returns --- ### Step 5: Document RunPod configuration + **IMPLEMENTATION:** + - Update PR description with RunPod env var setup instructions - Add note: Set `GOOGLE_API_KEY` in RunPod template env vars (no `.env` file needed) - RunPod specific configuration instructions: @@ -133,6 +189,7 @@ - Success criteria: PR description has RunPod section with env var guidance **GIT TRACKING:** + - Commit (empty or documentation) - Message: `[ENV-5] Document RunPod env configuration for Nano Banana` - Branch: Same feature branch @@ -140,25 +197,30 @@ - PR: Update PR description with RunPod section **USER FEEDBACK TOUCHPOINT:** + - Who: {users} - What to show: PR description RunPod section - Feedback needed: "Does RunPod env var guidance match your setup?" - Blocking: Non-blocking **CHECKPOINT:** + - Natural stopping point: After commit - Rollback: Edit PR description --- ### Step 6: Cleanup planning artifact (pre-merge) + **IMPLEMENTATION:** + - Copy final `PLAN.md` content to PR description - Delete `PLAN.md` file - Expected outcome: Clean main branch; plan preserved in PR - Success criteria: `PLAN.md` removed; PR description has complete plan **GIT TRACKING:** + - Final commit before merge - Message: `[ENV-6] Cleanup planning artifact - plan moved to PR description` - Branch: Same feature branch @@ -166,12 +228,14 @@ - PR: Final PR description update **USER FEEDBACK TOUCHPOINT:** + - Who: {users} - What to show: Final PR ready for review - Feedback needed: "Ready for final review and merge?" - Blocking: Non-blocking **CHECKPOINT:** + - Natural stopping point: Before merge - Rollback: Restore `PLAN.md` if needed @@ -180,7 +244,9 @@ ## Communication Templates ### After Step 1 (Initial Setup) + **Notify {users} via PR comment:** + ``` ✅ Step 1 Complete: Plan and .env.example created @@ -200,11 +266,14 @@ What's next: ``` ### After Step 4 (Validation) + **Notify {users} via PR comment:** + ``` ✅ Step 4 Complete: Local validation successful What's done: +- Cleaned and rebuilt container (pre-hook) - Wired .env into docker-compose.yml - Validated with real API key - Nano Banana nodes authenticating successfully @@ -227,16 +296,20 @@ What's next: ## Rollback Strategy **If env config breaks container:** + ```bash # Remove .env rm .env -# Restart without env file -docker restart comfy +# Stop and remove container +docker compose down +# Rebuild and restart +docker compose build && docker compose up -d # Revert docker-compose.yml if needed git revert [commit-hash] ``` **If validation fails:** + - Keep error logs in commit message - Document in PR description - Branch from last good commit if major changes needed @@ -244,6 +317,22 @@ git revert [commit-hash] --- ## Backlog Items (Separate Branch) + - [ ] ComfyUI version update to resolve Manager frozen mode - [ ] OpenTelemetry tracing for Nano Banana errors +## Potential Blockers & Constraints + +### Identified Blockers + +1. **Container State**: Existing `comfy` container may have stale state - addressed by pre-hook cleanup +2. **GPU Driver Issues**: Previous `docker compose up` failure due to GPU driver problems - needs investigation +3. **Nano Banana Installation Status**: Unclear if node is already installed or needs installation +4. **Container Strategy**: Two containers mentioned (`comfy` vs `comfyui`) - need to standardize approach + +### Questions Requiring Clarification + +1. **Container Management**: Should we always use `docker compose` commands, or handle standalone `comfy` container? +2. **GPU Configuration**: What was the specific GPU driver error? May need nvidia-container-toolkit setup. +3. **Nano Banana Node**: Is ComfyUI_Nano_Banana already installed, or do we need to add installation step? +4. **Testing Environment**: Are there any constraints on when/how containers can be rebuilt (e.g., data persistence concerns)? diff --git a/scripts/docker-entrypoint.sh b/scripts/docker-entrypoint.sh old mode 100644 new mode 100755