Skip to content

DEPLOY.md

Latest commit

 

History

History
96 lines (79 loc) · 8.41 KB

DEPLOY.md

File metadata and controls

96 lines (79 loc) · 8.41 KB

Tanzu GenAI Showcase: On-Demand Cloud Foundry Deployment Workflow

This GitHub Actions workflow allows you to deploy any of the showcase applications from this repository to a specified Cloud Foundry environment on demand.

Purpose

The workflow automates the following steps:

  1. Checks out the application code.
  2. Installs the necessary Cloud Foundry CLI (v8).
  3. Authenticates to the target Cloud Foundry environment using provided credentials.
  4. Checks if the target Organization and Space exist, creating them if necessary.
  5. Targets the specified Organization and Space.
  6. Sets up the required build environment (e.g., .NET SDK, Java, Node.js, Python, PHP, Ruby) based on the selected project.
  7. Builds the application if required (e.g., dotnet publish, mvn package, npm run build).
  8. Creates necessary Cloud Foundry services (like GenAI LLM instances or databases) if they don't already exist.
  9. Pushes the application using its manifest.yml file (without starting).
  10. Sets required environment variables using GitHub Secrets.
  11. Starts the application.

Prerequisites

  1. Cloud Foundry Credentials: You need valid username/password credentials for the target Cloud Foundry foundation.
  2. GitHub Secret CF_PASSWORD: You must create a repository secret named CF_PASSWORD containing the password for your Cloud Foundry user. Go to Settings -> Secrets and variables -> Actions -> New repository secret.
  3. Other API Keys/Secrets: Each application may require specific API keys (e.g., for TMDb, NewsAPI, AviationStack). These must be pre-configured as GitHub repository secrets with the exact names listed in the table below.
  4. Target CF Environment: Know the API endpoint, Organization name, and Space name for your deployment target.
  5. Service Plan Names: If the application requires services (like GenAI or a database), you need to know the correct service plan names available in your Cloud Foundry marketplace for those services. The workflow uses defaults, but you might need to override them.

Required GitHub Secrets

You must configure the following secrets in your repository for the applications you intend to deploy. For a complete list of required secrets and detailed instructions on how to set them up, please refer to the SECRETS.md file.

Tip

We provide a convenient script (create-gh-secrets.sh) and a template file (.env.example) to help you set up all required GitHub secrets. See SECRETS.md for details.

GitHub Secret Name Used By Project(s) App Environment Variable Set
CF_PASSWORD Workflow (Used for cf auth)
GOOGLEMAPS_API_KEY dotnet-extensions-ai GOOGLEMAPS__APIKEY
CONGRESS_API_KEY go-fiber-langchaingo CONGRESS_API_KEY
AVIATION_STACK_ACCESS_KEY java-spring-ai-mcp/server (Used for UPS)
OPENAI_API_KEY java-spring-ai-mcp/client, java-spring-langgraph-mcp-angular, php-symfony-neuron, py-django-crewai SPRING_AI_OPENAI_API_KEY (Java), OPENAI_API_KEY (PHP/Python)
TICKETMASTER_API_KEY java-spring-langgraph-mcp-angular TICKETMASTER_API_KEY
CITIES_API_KEY java-spring-langgraph-mcp-angular CITIES_API_KEY
NEWS_API_KEY js-langchain-react, php-symfony-neuron NEWS_API_KEY
LLM_API_KEY js-langchain-react API_KEY
STOCK_API_KEY php-symfony-neuron STOCK_API_KEY
EDGAR_API_KEY php-symfony-neuron EDGAR_API_KEY
LINKEDIN_CLIENT_ID php-symfony-neuron LINKEDIN_CLIENT_ID
LINKEDIN_CLIENT_SECRET php-symfony-neuron LINKEDIN_CLIENT_SECRET
DJANGO_SECRET_KEY py-django-crewai DJANGO_SECRET_KEY
TMDB_API_KEY py-django-crewai TMDB_API_KEY
SERPAPI_API_KEY py-django-crewai SERPAPI_API_KEY
AVIATIONSTACK_API_KEY ruby-sinatra-fastmcp AVIATIONSTACK_API_KEY

Note

If an application uses service binding for LLM or Database credentials, the corresponding API key secret might not be strictly required for deployment if the service binding provides all necessary credentials. However, it's good practice to configure them for consistency or potential fallback.

How to Use

  1. Navigate to the Actions tab in your GitHub repository.
  2. Find the "On-Demand CF Deploy" workflow in the list on the left.
  3. Click the "Run workflow" dropdown button on the right.
  4. Fill in the required inputs:
    • Application to deploy: Select the specific project directory (e.g., dotnet-extensions-ai, java-spring-ai-mcp/client).
    • Cloud Foundry API Endpoint: The URL of your CF API (e.g., https://api.cf.example.com).
    • Cloud Foundry Username: Your CF username.
    • Cloud Foundry Target Organization: The name of the CF organization to deploy into.
    • Cloud Foundry Target Space: The name of the CF space within the organization.
    • GenAI Service Plan Name (Optional): The plan name for the genai service type. Only needed if the selected app requires a GenAI service.
    • Database Service Type (Optional): The type of database service (e.g., postgresql, mysql). Only needed if the selected app requires a database.
    • Database Service Plan Name (Optional): The plan name for the database service. Only needed if the selected app requires a database.
  5. Click the "Run workflow" button.
  6. Monitor the workflow progress in the Actions tab.

Workflow Breakdown

  1. Setup: Installs CF CLI v8.
  2. Authentication: Logs into the target CF API using the provided username and the CF_PASSWORD secret.
  3. Org/Space Management: Checks if the target org and space exist. If not, it attempts to create them. Note: The user running the workflow needs permissions to create orgs/spaces if they don't exist.
  4. Targeting: Sets the CLI context to the specified org and space.
  5. Project Setup: Conditionally runs setup steps based on the selected project (installing SDKs/runtimes, building the app).
  6. Service Creation: Conditionally creates required services (GenAI, Database, User-Provided) if they don't already exist, using specified or default plan names.
  7. Deployment: Pushes the application using cf push -f manifest.yml --no-start. It relies on the manifest.yml within the selected project's directory.
  8. Secret Injection: Sets necessary environment variables using the pre-configured GitHub secrets.
  9. Start Application: Starts the application using cf start.

Troubleshooting

  • Authentication Failed: Double-check your CF username and ensure the CF_PASSWORD secret is correct. Verify your user has access to the target CF API.
  • Org/Space Creation Failed: Ensure the CF user has permissions to create organizations or spaces if they don't exist. If they should exist, verify the names are spelled correctly.
  • Build Failed: Check the logs for the specific build step (e.g., "Build .NET App"). Ensure the correct SDK/runtime versions are installed and dependencies are correct.
  • Service Creation Failed: Verify the service type (e.g., genai, postgresql) and plan name (e.g., standard) are valid in your CF marketplace (cf marketplace).
  • Push Failed: Examine the cf push logs. Common issues include incorrect paths in the manifest.yml, insufficient memory/disk quota, or buildpack errors.
  • App Fails to Start: Check cf logs APP_NAME --recent. Common causes include missing environment variables (secrets), incorrect database connection strings (if using DB service), or application errors. Ensure all required secrets were set in GitHub.
  • Secret Not Set: Verify the GitHub secret exists with the exact name specified in the "Required GitHub Secrets" table. Secrets are case-sensitive.