wehub-resource-sync
175 lines
10 KiB
Markdown
175 lines
10 KiB
Markdown
# Project Livewire - Google Cloud Run Deployment Guide
|
|
|
|
This guide provides step-by-step instructions for deploying the Project Livewire client and server components as containerized services on Google Cloud Run. This setup is recommended for a scalable and managed production-like environment.
|
|
|
|
## Prerequisites
|
|
|
|
1. **Google Cloud Project:** You need an active Google Cloud project.
|
|
2. **Google Cloud SDK (`gcloud`):** Installed and authenticated.
|
|
* [Install Guide](https://cloud.google.com/sdk/docs/install)
|
|
* Login: `gcloud auth login`
|
|
* Set your project: `gcloud config set project YOUR_GOOGLE_CLOUD_PROJECT` (Replace `YOUR_GOOGLE_CLOUD_PROJECT`)
|
|
3. **Enabled APIs:** Ensure the following APIs are enabled in your project:
|
|
* Cloud Build API (`cloudbuild.googleapis.com`)
|
|
* Cloud Run API (`run.googleapis.com`)
|
|
* Secret Manager API (`secretmanager.googleapis.com`)
|
|
* IAM API (`iam.googleapis.com`)
|
|
* Container Registry API (`containerregistry.googleapis.com`) or Artifact Registry API (`artifactregistry.googleapis.com`)
|
|
* (Optional) Vertex AI API (`aiplatform.googleapis.com`) - If using the Vertex AI endpoint.
|
|
* (Optional) Cloud Functions API (`cloudfunctions.googleapis.com`) - For deploying tools.
|
|
* (Optional) Google Calendar API (`calendar-json.googleapis.com`) - For the calendar tool function.
|
|
```bash
|
|
gcloud services enable run.googleapis.com cloudbuild.googleapis.com secretmanager.googleapis.com iam.googleapis.com containerregistry.googleapis.com aiplatform.googleapis.com cloudfunctions.googleapis.com calendar-json.googleapis.com
|
|
```
|
|
4. **Deployed Cloud Functions:** The backend server relies on Cloud Functions for tool integration (weather, calendar).
|
|
* Deploy these functions first by following the **[Cloud Functions Setup Guide](../cloud-functions/README.md)**.
|
|
* You do *not* need the function URLs in an `.env` file for Cloud Run deployment if you configure them via Secret Manager or pass them during backend deployment (though storing them in secrets is common).
|
|
5. **Git Repository:** You should have the Project Livewire code cloned locally.
|
|
|
|
## Setup Steps
|
|
|
|
### 1. Create Backend Service Account
|
|
|
|
The Cloud Run service for the backend needs an identity to securely access other Google Cloud services like Secret Manager.
|
|
|
|
```bash
|
|
# Define service account name (optional, adjust if needed)
|
|
export BACKEND_SA_NAME="livewire-backend"
|
|
export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)
|
|
|
|
# Create the service account
|
|
gcloud iam service-accounts create ${BACKEND_SA_NAME} \
|
|
--description="Service account for Project Livewire backend Cloud Run service" \
|
|
--display-name="Livewire Backend SA"
|
|
|
|
# Grant Secret Manager access to the service account
|
|
gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
|
|
--member="serviceAccount:${BACKEND_SA_NAME}@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com" \
|
|
--role="roles/secretmanager.secretAccessor"
|
|
|
|
# (Optional) Grant Vertex AI User role if using Vertex AI endpoint
|
|
# gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
|
|
# --member="serviceAccount:${BACKEND_SA_NAME}@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com" \
|
|
# --role="roles/aiplatform.user"
|
|
```
|
|
|
|
### 2. Store Secrets in Secret Manager
|
|
|
|
Securely store API keys and potentially other sensitive configuration. The backend service account will access these.
|
|
|
|
* **Google Gemini API Key:**
|
|
```bash
|
|
# Replace YOUR_GEMINI_API_KEY with your actual key
|
|
echo -n "YOUR_GEMINI_API_KEY" | \
|
|
gcloud secrets create GOOGLE_API_KEY --replication-policy="automatic" --data-file=-
|
|
```
|
|
* **OpenWeather API Key (for weather tool):**
|
|
```bash
|
|
# Replace YOUR_OPENWEATHER_API_KEY with your actual key
|
|
echo -n "YOUR_OPENWEATHER_API_KEY" | \
|
|
gcloud secrets create OPENWEATHER_API_KEY --replication-policy="automatic" --data-file=-
|
|
```
|
|
* **(Optional) Store Cloud Function URLs:** You can also store function URLs as secrets if preferred.
|
|
```bash
|
|
# Example for Weather Function URL
|
|
# echo -n "YOUR_WEATHER_FUNCTION_URL" | \
|
|
# gcloud secrets create WEATHER_FUNCTION_URL --replication-policy="automatic" --data-file=-
|
|
```
|
|
*(Note: The current `server/config/config.py` primarily expects URLs from environment variables, but could be adapted to read them from secrets if desired).*
|
|
|
|
### 3. Deploy the Backend Server to Cloud Run
|
|
|
|
This uses Cloud Build (`server/cloudbuild.yaml`) to build the Docker image and deploy it to Cloud Run.
|
|
|
|
```bash
|
|
# Navigate to the project root directory
|
|
cd /path/to/project-livewire
|
|
|
|
# Submit the build and deployment job
|
|
# This uses the configuration in server/cloudbuild.yaml
|
|
# It sets GOOGLE_CLOUD_PROJECT and the service account during deployment
|
|
gcloud builds submit --config server/cloudbuild.yaml
|
|
```
|
|
|
|
* **What `server/cloudbuild.yaml` does:**
|
|
* Builds a Docker image using `server/Dockerfile`.
|
|
* Pushes the image to Google Container Registry (or Artifact Registry).
|
|
* Deploys the image to Cloud Run as a service named `livewire-backend`.
|
|
* Sets the region (default `us-central1` - modify YAML if needed).
|
|
* Allows unauthenticated access (for easy client connection - **consider restricting access in production**).
|
|
* Sets the container port to `8081`.
|
|
* Sets environment variables (`GOOGLE_CLOUD_PROJECT`, `LOG_LEVEL`). You can add more here (like `GOOGLE_GENAI_USE_VERTEXAI=true`, `GOOGLE_CLOUD_LOCATION`, or Function URLs if not using secrets).
|
|
* Assigns the `livewire-backend` service account created earlier.
|
|
|
|
### 4. Get the Backend Service URL
|
|
|
|
After the deployment finishes, retrieve the URL of the backend service.
|
|
|
|
```bash
|
|
# Replace us-central1 if you deployed to a different region
|
|
export BACKEND_URL=$(gcloud run services describe livewire-backend --platform managed --region us-central1 --format 'value(status.url)')
|
|
|
|
# Verify the URL (should start with https://...)
|
|
echo "Backend URL: ${BACKEND_URL}"
|
|
```
|
|
**Important:** The client needs the **WebSocket** version of this URL (replace `https://` with `wss://`).
|
|
|
|
### 5. Deploy the Frontend Client to Cloud Run
|
|
|
|
This uses Cloud Build (`client/cloudbuild.yaml`) to build the client's Docker image (which uses nginx to serve static files) and deploy it. We pass the backend's WebSocket URL to the build process.
|
|
|
|
```bash
|
|
# Navigate to the project root directory (if not already there)
|
|
cd /path/to/project-livewire
|
|
|
|
# Construct the WebSocket URL for the backend
|
|
export WSS_BACKEND_URL=$(echo ${BACKEND_URL} | sed 's|https://|wss://|')
|
|
echo "WebSocket Backend URL: ${WSS_BACKEND_URL}"
|
|
|
|
# Submit the build and deployment job for the frontend
|
|
# Pass the WebSocket URL as a substitution variable
|
|
gcloud builds submit --config client/cloudbuild.yaml \
|
|
--substitutions=_BACKEND_URL="${WSS_BACKEND_URL}"
|
|
```
|
|
|
|
* **What `client/cloudbuild.yaml` does:**
|
|
* Builds a Docker image using `client/Dockerfile`.
|
|
* Pushes the image to Google Container Registry (or Artifact Registry).
|
|
* Deploys the image to Cloud Run as a service named `livewire-ui`.
|
|
* Sets the region (default `us-central1` - modify YAML if needed).
|
|
* Allows unauthenticated access.
|
|
* Sets the container port to `8080`.
|
|
* **Crucially:** It expects the `_BACKEND_URL` substitution. This URL is injected into the `nginx.conf` file *during the build process* so the client-side JavaScript can potentially fetch it or be configured accordingly. *(Self-correction: The current client JS hardcodes `ws://localhost:8081`. This needs adjustment for cloud deployment. A common pattern is to have the frontend fetch config from a `/config` endpoint served by nginx, which gets the URL via the build arg/env var, or embed it directly in the HTML/JS during build).*
|
|
* *Modification needed:* The client code (`client/src/api/gemini-api.js`) needs to be updated to dynamically use the backend URL provided during deployment, rather than hardcoding `ws://localhost:8081`. This could involve fetching a config file or having the build process replace a placeholder. The `cloudbuild.yaml` substitution provides the URL, but the client needs to *use* it. A simple approach for this setup might be to modify `client/cloudbuild.yaml` to directly replace the placeholder in `gemini-api.js` using `sed` before building the image.
|
|
|
|
### 6. Get the Frontend Service URL
|
|
|
|
Retrieve the URL for the deployed UI service.
|
|
|
|
```bash
|
|
# Replace us-central1 if you deployed to a different region
|
|
export FRONTEND_URL=$(gcloud run services describe livewire-ui --platform managed --region us-central1 --format 'value(status.url)')
|
|
|
|
# Print the URL
|
|
echo "Frontend URL: ${FRONTEND_URL}"
|
|
```
|
|
|
|
### 7. Access the Application
|
|
|
|
Open the `FRONTEND_URL` in your web browser to use the deployed Project Livewire application.
|
|
|
|
## Troubleshooting
|
|
|
|
* **Cloud Build Failures:**
|
|
* Check the Cloud Build logs in the Google Cloud Console for detailed error messages.
|
|
* Ensure the Cloud Build service account has necessary permissions (e.g., to push to Container Registry, deploy to Cloud Run).
|
|
* **Cloud Run Service Errors:**
|
|
* Check the "Logs" tab for your `livewire-backend` and `livewire-ui` services in the Cloud Run section of the Google Cloud Console.
|
|
* **Backend:** Look for errors related to Secret Manager access (check IAM roles), API key validity, connection issues to Gemini, or problems calling Cloud Functions. Ensure `GOOGLE_CLOUD_PROJECT` is correctly passed or available.
|
|
* **Frontend:** Look for nginx errors or issues serving files. Ensure the backend URL was correctly passed during the build and is accessible.
|
|
* **Connection Issues (Client <-> Server):**
|
|
* Verify the WebSocket URL used by the client correctly points to the `wss://` version of the `livewire-backend` service URL.
|
|
* Ensure both Cloud Run services allow ingress traffic (e.g., `--allow-unauthenticated` was used, or appropriate authentication is configured if restricted). Check firewall rules if applicable.
|
|
* **Secret Manager Access Denied:** Double-check that the `livewire-backend` service account has the `roles/secretmanager.secretAccessor` role assigned in IAM.
|
|
* **Quota Errors:** Monitor API usage (Gemini, Cloud Functions, etc.) in the Google Cloud Console. You might be hitting free tier limits or project quotas.
|