docs: Add OS-specific instructions and troubleshooting guide

Author: stuagano

contributing/samples/security_agent/README.md

@@ -130,20 +130,59 @@ VERTEX_AI_PROJECT_ID="your-project-id"
 VERTEX_AI_LOCATION="us-central1"
 ```
 
-## 🚀 Deployment Options
+## 🚀 Getting Started
 
-### Local Development
+### Prerequisites
+- **Docker:** Make sure Docker is installed and running on your system. You can download it from [the Docker website](https://www.docker.com/get-started).
+
+### 1. Clone the Repository
+```bash
+git clone https://github.com/google/adk-python.git
+cd adk-python/contributing/samples/security_agent
+```
+
+### 2. Configure Environment Variables
+Create a file named `.env` and add the following, replacing the placeholder values with your own:
+```bash
+# Google Cloud Configuration
+GOOGLE_CLOUD_PROJECT="your-project-id"
+GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account.json"
+
+# ADK Configuration
+ADK_EVALUATION_ENABLED="true"
+
+# Vertex AI Configuration (for enterprise features)
+VERTEX_AI_PROJECT_ID="your-project-id"
+VERTEX_AI_LOCATION="us-central1"
+```
+
+### 3. Run the Agent
 ```bash
 ./run.sh
 ```
+This script will build the Docker image and start the agent.
+
+### 4. Access the Agent
+-   **Frontend:** [http://localhost:8501](http://localhost:8501)
+-   **Backend API Docs:** [http://localhost:8000/docs](http://localhost:8000/docs)
 
-### Google Cloud Run
+##  troubleshooting
+
+### Docker Daemon Not Running
+If you see an error message like "Cannot connect to the Docker daemon", make sure the Docker daemon is running.
+
+-   **macOS:** Open the Docker Desktop application.
+-   **Windows:** Open the Docker Desktop application.
+-   **Linux:** Run `sudo systemctl start docker`.
+
+### Port Conflicts
+If you see an error message like "Port is already allocated", it means that another application is using port 8000 or 8501. You can either stop the other application or change the ports in the `docker-compose.yml` file.
+
+### Issues with `gcloud`
+If you have issues with `gcloud` commands, make sure you have the [Google Cloud SDK](https://cloud.google.com/sdk/docs/install) installed and authenticated:
 ```bash
-# Deploy to Cloud Run
-gcloud run deploy security-agent \
-  --source . \
-  --platform managed \
-  --region us-central1 \
-  --allow-unauthenticated
+gcloud auth login
+gcloud auth application-default login
 ```
 
+

contributing/samples/security_agent/run.sh

@@ -45,9 +45,16 @@ check_docker() {
         print_status "Please install Docker from https://www.docker.com/get-started"
         exit 1
     fi
-    print_success "Docker is available"
+
+    if ! docker info > /dev/null 2>&1; then
+        print_error "Docker daemon is not running"
+        print_status "Please start the Docker daemon and try again"
+        exit 1
+    fi
+    print_success "Docker is available and running"
 }
 
+
 # Function to build the Docker image
 build_docker_image() {
     print_status "Building Docker image..."