Refactoring

Author: olesho

CLAUDE.md

@@ -53,6 +53,28 @@ supervisord
 web-agent/
 ├── browser-operator-core/      # Submodule: DevTools frontend source
 ├── kernel-images/              # Submodule: Base browser environment
+├── deployment/                 # Deployment configurations
+│   ├── cloudrun/               # Google Cloud Run deployment
+│   │   ├── deploy.sh           # Cloud deployment script
+│   │   ├── cloudbuild.yaml     # CI/CD pipeline config
+│   │   ├── service.yaml        # Cloud Run service definition
+│   │   ├── service-secrets.yaml # Service with Secret Manager
+│   │   ├── cloudrun-wrapper.sh # Cloud Run entrypoint
+│   │   ├── cloudrun-kernel-wrapper.sh # Alternative wrapper
+│   │   ├── supervisord-cloudrun.conf # Supervisor for Cloud Run
+│   │   └── nginx.conf          # Reverse proxy config
+│   └── local/                  # Local deployment
+│       └── run-local.sh        # Interactive Docker run script
+├── nginx/                      # Nginx configurations
+│   └── nginx-devtools.conf     # DevTools nginx config
+├── scripts/                    # Utility scripts
+│   ├── init-container.sh       # Auto-cleanup of lock files
+│   └── test-eval-server.sh     # Eval server build test
+├── supervisor/services/        # Service configs (override defaults)
+│   ├── chromium.conf           # Auto-open DevTools
+│   ├── eval-server.conf        # Eval server with CDP_PORT=9223
+│   ├── neko.conf
+│   └── nginx-devtools.conf
 ├── eval-server/
 │   └── nodejs/                 # Eval server source (use this, NOT submodule)
 │       ├── src/
@@ -65,20 +87,13 @@ web-agent/
 │   ├── run.py                  # Python evaluation runner
 │   ├── lib/judge.py            # LLMJudge, VisionJudge, SimpleJudge
 │   └── data/                   # Evaluation YAML files
-├── scripts/
-│   ├── init-container.sh       # Auto-cleanup of lock files
-│   └── cleanup-chromium-locks.sh
-├── supervisor/services/        # Service configs (override defaults)
-│   ├── chromium.conf           # Auto-open DevTools
-│   ├── eval-server.conf        # Eval server with CDP_PORT=9223
-│   ├── neko.conf
-│   └── nginx-devtools.conf
-├── Dockerfile.local            # Main Docker build
+├── Dockerfile.local            # Main Docker build (local dev)
 ├── Dockerfile.devtools         # DevTools frontend build
+├── Dockerfile.cloudrun         # Cloud Run build
 ├── docker-compose.yml          # Local deployment config
-├── run-local.sh                # Interactive mode startup
 ├── Makefile                    # Build/deployment commands
-└── README.md
+├── CLAUDE.md                   # This file
+└── README.md                   # User documentation
 ```
 
 ## Key Files and What They Do
@@ -144,7 +159,7 @@ Key targets:
 - `make stop` - Stop all containers
 - `make clean` - Clean up everything
 
-### run-local.sh
+### deployment/local/run-local.sh
 Interactive Docker run script that:
 - Sources kernel-images common build variables
 - Creates local recordings directory
@@ -161,6 +176,24 @@ Interactive Docker run script that:
 - More flexible for custom configurations via environment variables
 - Better for seeing startup issues and debugging
 
+### deployment/cloudrun/
+Contains all Google Cloud Run deployment files:
+- `deploy.sh` - Automated deployment script with Twilio TURN setup
+- `cloudbuild.yaml` - CI/CD pipeline for Cloud Build
+- `service.yaml` / `service-secrets.yaml` - Cloud Run service definitions
+- `cloudrun-wrapper.sh` - Cloud Run container entrypoint
+- `supervisord-cloudrun.conf` - Supervisor configuration for Cloud Run
+- `nginx.conf` - Reverse proxy for Cloud Run port requirements
+
+### nginx/
+Nginx configuration files:
+- `nginx-devtools.conf` - DevTools UI server config (used by Dockerfile.local)
+
+### scripts/
+Utility scripts:
+- `init-container.sh` - Automatic lock file cleanup on container start
+- `test-eval-server.sh` - Test eval-server Docker build stage
+
 ## Common Issues and Solutions
 
 ### 1. Chromium Profile Lock Errors

Dockerfile.cloudrun

@@ -259,7 +259,7 @@ COPY kernel-images/images/chromium-headful/image-chromium/ /
 COPY kernel-images/images/chromium-headful/start-chromium.sh /images/chromium-headful/start-chromium.sh
 RUN chmod +x /images/chromium-headful/start-chromium.sh
 COPY kernel-images/images/chromium-headful/supervisord.conf /etc/supervisor/supervisord.conf
-COPY supervisord-cloudrun.conf /etc/supervisor/supervisord-cloudrun.conf
+COPY deployment/cloudrun/supervisord-cloudrun.conf /etc/supervisor/supervisord-cloudrun.conf
 COPY kernel-images/images/chromium-headful/supervisor/services/ /etc/supervisor/conf.d/services/
 
 # Copy the kernel-images API binary
@@ -291,7 +291,7 @@ RUN chown -R kernel:kernel /opt/eval-server
 
 # Cloud Run specific: wrapper scripts (nginx config is inline)
 # DO NOT copy nginx.conf to avoid auto-start conflicts
-COPY cloudrun-wrapper.sh /cloudrun-wrapper.sh
+COPY deployment/cloudrun/cloudrun-wrapper.sh /cloudrun-wrapper.sh
 COPY twilio/twilio-credential-updater.sh /twilio-credential-updater.sh
 RUN chmod +x /cloudrun-wrapper.sh /twilio-credential-updater.sh
 

Dockerfile.kernel-cloud

@@ -208,7 +208,7 @@ RUN mkdir -p /chromium && \
     chown -R kernel:kernel /chromium
 
 # Cloud Run wrapper that starts kernel-images services + nginx proxy
-COPY cloudrun-kernel-wrapper.sh /cloudrun-kernel-wrapper.sh
+COPY deployment/cloudrun/cloudrun-kernel-wrapper.sh /cloudrun-kernel-wrapper.sh
 RUN chmod +x /cloudrun-kernel-wrapper.sh
 
 # Cloud Run requires non-root execution

Dockerfile.local

@@ -221,7 +221,7 @@ COPY --from=server-builder /out/kernel-images-api /usr/local/bin/kernel-images-a
 COPY --from=devtools-source /usr/share/nginx/html /usr/share/nginx/devtools
 
 # Create DevTools nginx configuration
-COPY nginx-devtools.conf /etc/nginx/sites-available/devtools
+COPY nginx/nginx-devtools.conf /etc/nginx/sites-available/devtools
 RUN ln -s /etc/nginx/sites-available/devtools /etc/nginx/sites-enabled/devtools && \
     rm /etc/nginx/sites-enabled/default
 

Makefile

@@ -78,7 +78,7 @@ rebuild: init ## Force complete rebuild (including DevTools)
 run: ## Run extended container with DevTools (interactive)
 	@echo "🚀 Starting extended kernel-browser with DevTools..."
 	@if [ -n "$(URLS)" ]; then echo "📄 Opening URLs: $(URLS)"; fi
-	@./run-local.sh
+	@./deployment/local/run-local.sh
 
 compose-up: build ## Start with docker-compose (background)
 	@echo "🚀 Starting with docker-compose..."

Readme.md

@@ -318,10 +318,10 @@ gcloud auth application-default login
 
 ```bash
 # Automated deployment (recommended)
-./deploy.sh
+./deployment/cloudrun/deploy.sh
 
 # Or with custom settings
-./deploy.sh --project your-project-id --region us-central1
+./deployment/cloudrun/deploy.sh --project your-project-id --region us-central1
 ```
 
 ### Access Cloud Run Service
@@ -435,6 +435,24 @@ For production WebRTC, configure a TURN server:
 web-agent/
 ├── browser-operator-core/      # Submodule: DevTools frontend source
 ├── kernel-images/              # Submodule: Base browser environment
+├── deployment/                 # Deployment configurations
+│   ├── cloudrun/               # Google Cloud Run deployment
+│   │   ├── deploy.sh           # Cloud deployment script
+│   │   ├── cloudbuild.yaml     # CI/CD pipeline config
+│   │   ├── service.yaml        # Cloud Run service definition
+│   │   ├── service-secrets.yaml # Service with Secret Manager
+│   │   ├── cloudrun-wrapper.sh # Cloud Run entrypoint
+│   │   ├── cloudrun-kernel-wrapper.sh # Alternative wrapper
+│   │   ├── supervisord-cloudrun.conf # Supervisor for Cloud Run
+│   │   └── nginx.conf          # Reverse proxy config
+│   └── local/                  # Local deployment
+│       └── run-local.sh        # Interactive Docker run script
+├── nginx/                      # Nginx configurations
+│   └── nginx-devtools.conf     # DevTools nginx config
+├── scripts/                    # Utility scripts
+│   ├── init-container.sh       # Auto-cleanup of lock files
+│   └── test-eval-server.sh     # Eval server build test
+├── supervisor/services/        # Service configs (overrides)
 ├── eval-server/
 │   └── nodejs/                 # Eval server (use this, NOT submodule)
 │       ├── src/                # API server, evaluation server, lib
@@ -444,19 +462,11 @@ web-agent/
 │   ├── run.py                  # Python evaluation runner
 │   ├── lib/judge.py            # Judge implementations
 │   └── data/                   # Evaluation YAML files
-├── scripts/
-│   └── init-container.sh       # Auto-cleanup of lock files
-├── supervisor/services/        # Service configs (overrides)
-├── Dockerfile.local            # Main Docker build
+├── Dockerfile.local            # Main Docker build (local dev)
 ├── Dockerfile.devtools         # DevTools frontend build
-├── docker-compose.yml          # Local deployment
-├── run-local.sh                # Interactive mode
-├── Makefile                    # Build commands
 ├── Dockerfile.cloudrun         # Cloud Run build
-├── nginx.conf                  # Reverse proxy config
-├── service.yaml                # Cloud Run service config
-├── cloudbuild.yaml             # CI/CD pipeline
-├── deploy.sh                   # Cloud deployment script
+├── docker-compose.yml          # Local deployment config
+├── Makefile                    # Build commands
 ├── CLAUDE.md                   # Technical documentation
 └── README.md                   # This file
 ```
@@ -541,13 +551,13 @@ The `cloudbuild.yaml` provides:
 
 ```bash
 # Normal build (with cache) - recommended for development
-gcloud builds submit --config cloudbuild.yaml
+gcloud builds submit --config deployment/cloudrun/cloudbuild.yaml
 
 # Force rebuild without cache - use when dependencies change
-gcloud builds submit --config cloudbuild.yaml --substitutions=_NO_CACHE=true
+gcloud builds submit --config deployment/cloudrun/cloudbuild.yaml --substitutions=_NO_CACHE=true
 
 # Automated deployment with Twilio TURN server setup
-./deploy.sh
+./deployment/cloudrun/deploy.sh
 ```
 
 ### Cache Control

cloudbuild.yaml renamed to deployment/cloudrun/cloudbuild.yaml

@@ -3,8 +3,16 @@
 set -euo pipefail
 
 # Kernel-Browser Cloud Run Deployment Script
+# NOTE: This script should be run from the project root directory
 echo "🚀 Starting kernel-browser deployment to Google Cloud Run..."
 
+# Verify we're in the project root
+if [ ! -f "docker-compose.yml" ]; then
+    echo "❌ Error: This script must be run from the project root directory"
+    echo "   Expected to find docker-compose.yml in current directory"
+    exit 1
+fi
+
 # Configuration
 PROJECT_ID="${PROJECT_ID:-}"
 REGION="${REGION:-us-central1}"
@@ -298,7 +306,7 @@ deploy_with_cloudbuild() {
 
     # Submit build
     gcloud builds submit \
-        --config=cloudbuild.yaml \
+        --config=deployment/cloudrun/cloudbuild.yaml \
         --project="$PROJECT_ID" \
         --timeout="2h" \
         --machine-type="e2-highcpu-32"
@@ -321,11 +329,11 @@ deploy_local() {
     info "Deploying to Cloud Run..."
 
     # Choose appropriate service.yaml based on secrets availability
-    local service_file="service.yaml"
+    local service_file="deployment/cloudrun/service.yaml"
     if [ "${USE_SECRETS:-false}" = "true" ]; then
         if gcloud secrets describe twilio-account-sid --project="$PROJECT_ID" &>/dev/null && \
            gcloud secrets describe twilio-auth-token --project="$PROJECT_ID" &>/dev/null; then
-            service_file="service-secrets.yaml"
+            service_file="deployment/cloudrun/service-secrets.yaml"
             info "Using service-secrets.yaml with Secret Manager references"
         else
             warning "Secrets not found, falling back to standard service.yaml"