This repository contains the necessary scripts and configurations to deploy the Instavibe application and its associated agents and services.
Before deploying any components, you need to configure your environment. This project uses a central .env file in the project root to manage all necessary configurations, such as your Google Cloud Project ID, region, Spanner instance details, API keys, etc.
-
Create the
.envfile:- In the root directory of the project, make a copy of the example environment file:
cp .env.example .env
- In the root directory of the project, make a copy of the example environment file:
-
Populate
.env:- Open the newly created
.envfile with a text editor. - Fill in the values for each variable. Pay close attention to key variables like
COMMON_GOOGLE_CLOUD_PROJECT,COMMON_GOOGLE_CLOUD_LOCATION,COMMON_VERTEX_STAGING_BUCKET, Spanner IDs, and any necessary API keys or secrets as outlined in.env.example. - For detailed guidance on how to obtain or define each of these values, please refer to the Environment Variable Setup Guide.
- Important: Do not commit the
.envfile to version control. It should be listed in your.gitignorefile.
- Open the newly created
-
Source Environment Variables and Configure
gcloud:- A script
set_env.shis provided to source the variables from your.envfile into your current shell session and configure thegcloudCLI to use your specified project. - Run this script by sourcing it:
source ./set_env.sh - This script will:
- Load variables from your
.envfile, making them available in your shell. - Check your
gcloudauthentication status. - Set your active
gcloudproject to theCOMMON_GOOGLE_CLOUD_PROJECTdefined in your.envfile.
- Load variables from your
- A script
With these steps completed, your environment is ready for deploying the application components.
A central Python script deploy_all.py is provided in the root directory to orchestrate the deployment of all components.
The script deploys:
- Google Cloud Spanner instance and database (if they don't already exist, using
COMMON_SPANNER_INSTANCE_IDandCOMMON_SPANNER_DATABASE_IDfrom your.envfile). Subsequently, it runsinstavibe/setup.pyto initialize the schema and populate data. - Planner Agent (Vertex AI Agent Engine)
- Social Agent (Vertex AI Agent Engine)
- Orchestrate Agent (Vertex AI Agent Engine)
- Platform MCP Client Agent (Vertex AI Agent Engine)
- Instavibe App (Cloud Run, built via Google Cloud Build)
- MCP Tool Server (Cloud Run, built via Google Cloud Build)
Before running the central deployment script, ensure you have the following:
- Completed Initial Environment Setup: You must have created and populated the
.envfile and sourced it usingsource ./set_env.shas described in the "Initial Environment Setup" section. This step loads necessary configurations like project ID, region, and staging bucket into your environment. - Google Cloud SDK (
gcloud): Installed. Ensure you have authenticated at least once viagcloud auth login. Theset_env.shscript handles setting the active project. - Enabled APIs: The Cloud Build API (
cloudbuild.googleapis.com), Vertex AI API (aiplatform.googleapis.com), and the Cloud Spanner API (spanner.googleapis.com) must be enabled in your GCP project. You can enable them by visiting the Google Cloud Console or by runninggcloud services enable cloudbuild.googleapis.com aiplatform.googleapis.com spanner.googleapis.com. - Python 3: Installed on your system.
Note on Docker: While Docker was previously required for local image builds for some services, deploy_all.py now uses Google Cloud Build for containerized services, which builds your images in the cloud. Therefore, a local Docker installation is generally not required to run the script. However, Docker might still be useful for local development and testing of containerized components.
Navigate to the root directory of this repository and run the script as follows:
python deploy_all.pyThe script utilizes configurations (like Project ID, Region, Staging Bucket) defined in your root .env file, which should have been sourced via set_env.sh.
Optional Flags:
You can skip deploying certain parts of the application using the following flags:
--skip_agents: Skips the deployment of the Planner, Social, Orchestrate, and Platform MCP Client agents.--skip_app: Skips the deployment of the Instavibe App.--skip_platform_mcp_client: Skips the deployment of the Platform MCP Client Agent. (Note: If--skip_agentsis used, this agent is also skipped).--skip_mcp_tool_server: Skips the deployment of the MCP Tool Server.
Example:
To deploy only the Instavibe App and the MCP Tool Server:
# Example: To deploy only the Instavibe App and the MCP Tool Server:
python deploy_all.py --skip_agentsIf you prefer to deploy components individually, follow the instructions below.
When deploying manually, it's crucial to first complete the "Initial Environment Setup" and source the set_env.sh script. This ensures that necessary environment variables (like COMMON_GOOGLE_CLOUD_PROJECT, COMMON_GOOGLE_CLOUD_LOCATION) are loaded into your shell and are available for the individual deployment scripts and gcloud commands.
These agents are designed for deployment to Google Cloud Vertex AI Agent Engine. Each uses a deploy.py script and a requirements.txt file located in its respective directory.
-
Planner Agent:
- Navigate to the agent's directory:
cd agents/planner - Run the deployment script:
python deploy.py - This script uses configurations from your sourced
.envfile. - Requirements:
agents/planner/requirements.txt
- Navigate to the agent's directory:
-
Social Agent:
- Navigate to the agent's directory:
cd agents/social - Run the deployment script:
python deploy.py - This script uses configurations from your sourced
.envfile. - Requirements:
agents/social/requirements.txt
- Navigate to the agent's directory:
-
Orchestrate Agent:
- Navigate to the agent's directory:
cd agents/orchestrate - Run the deployment script:
python deploy.py - This script uses configurations from your sourced
.envfile. - Requirements:
agents/orchestrate/requirements.txt
- Navigate to the agent's directory:
-
Platform MCP Client Agent:
- Navigate to the agent's directory:
cd agents/platform_mcp_client - Run the deployment script:
python deploy.py - This script uses configurations from your sourced
.envfile. - Requirements:
agents/platform_mcp_client/requirements.txt
- Navigate to the agent's directory:
These services are deployed as Docker containers to Google Cloud Run using Google Cloud Build.
General Steps:
For each service:
-
Build and push the Docker image using Google Cloud Build: Navigate to the service's directory (e.g.,
cd instavibe/) and run:gcloud builds submit --tag gcr.io/$COMMON_GOOGLE_CLOUD_PROJECT/[SERVICE_NAME] . --project $COMMON_GOOGLE_CLOUD_PROJECT
(Ensure
COMMON_GOOGLE_CLOUD_PROJECTis set in your shell by sourcingset_env.sh.) Replace[SERVICE_NAME]with the specific service name (e.g.,instavibe-app). The.indicates that the build context (including the Dockerfile) is the current directory. -
Deploy the image to Cloud Run:
gcloud run deploy [SERVICE_NAME] \ --image gcr.io/$COMMON_GOOGLE_CLOUD_PROJECT/[SERVICE_NAME] \ --platform managed \ --region $COMMON_GOOGLE_CLOUD_LOCATION \ --project $COMMON_GOOGLE_CLOUD_PROJECT \ --allow-unauthenticated
(Ensure
COMMON_GOOGLE_CLOUD_PROJECTandCOMMON_GOOGLE_CLOUD_LOCATIONare set in your shell by sourcingset_env.sh.) Replace[SERVICE_NAME]accordingly. The--allow-unauthenticatedflag makes the service publicly accessible; adjust as needed for your security requirements. Key environment variables required by the application (as defined in.env.example) must be available to the Cloud Run service. Thedeploy_all.pyscript handles this by passing them during deployment. If deploying manually, you will need to ensure these are set, for example, using the--set-env-varsflag withgcloud run deploy(e.g.,--set-env-vars "KEY1=VALUE1,KEY2=VALUE2") or by configuring them in the Cloud Console.
Service-Specific Information:
-
Instavibe App:
- Service Name:
instavibe-app(or your preferred name) - Directory for
gcloud builds submit:instavibe/ - Dockerfile Location:
instavibe/Dockerfile
- Service Name:
-
MCP Tool Server:
- Service Name:
mcp-tool-server(or your preferred name) - Directory for
gcloud builds submit:tools/instavibe/ - Dockerfile Location:
tools/instavibe/Dockerfile
- Service Name:
This project includes unit tests for the central deployment script (deploy_all.py). These tests verify the script's logic, such as command-line argument parsing and conditional dispatch to deployment functions, without performing actual deployments (as external calls are mocked).
- Python 3.x (the same version used for
deploy_all.py)
To run the unit tests, navigate to the root directory of the repository and execute one of the following commands:
python -m unittest test_deploy_all.pyOr, since the test script test_deploy_all.py includes the standard if __name__ == '__main__': unittest.main() guard, you can also run it directly:
python test_deploy_all.pyThe tests will run, and you should see output indicating the number of tests run and their status (e.g., "OK" if all pass, or details of failures).