Add app-config.local.yaml template for simplified local development

kaviththiranga · Kavith Lokuhewage · commit 9453a77af401 · 2025-11-03T10:42:18.000+05:30
Introduces a pre-configured app-config.local.yaml.example file to simplify local Backstage development with Kind cluster. Developers can now start developing with a single copy command instead of managing multiple environment variables. Key changes: - Add app-config.local.yaml.example with hardcoded Kind cluster values - Frontend: http://localhost:3000 - Backend: http://localhost:7007 - OpenChoreo API: http://api.openchoreo.localhost - Thunder IDP: http://sts.openchoreo.localhost - OAuth credentials from Kind cluster helm values - Update README.md with simplified Quick Start guide - Add developer-friendly comments to app-config.yaml Benefits: - Zero configuration needed for local development - No manual environment variable management - Works out-of-box with Kind cluster (make -f make/kind.mk install) - Gitignored, won't affect Docker builds or production Usage: cp app-config.local.yaml.example app-config.local.yaml && yarn start
diff --git a/README.md b/README.md
@@ -31,181 +31,84 @@ Follow the setup [guide](https://openchoreo.dev/docs/getting-started/single-clus
 yarn install
 ```
 
-### 2. Environment Variables
+### 2. Local Development Setup with Kind Cluster
 
-The application requires several environment variables for configuration. These can be set in your shell or via a `.env` file.
+**Quick Start (Recommended):**
 
-#### Required Variables
+If you're running the OpenChoreo Kind cluster locally and want to connect Backstage (running at localhost:3000/7007) to it:
 
 ```bash
-# Backstage Base URL (used for both frontend and backend in production)
-# For local development, see "Local Development Considerations" below
-export BACKSTAGE_BASE_URL=http://localhost:3000
-
-# Backend session secret (required for authentication cookies)
-export BACKEND_SECRET=your-secret-key-here
-
-# OpenChoreo API configuration
-export OPENCHOREO_API_URL=http://localhost:8080/api/v1
-export OPENCHOREO_TOKEN=your-openchoreo-token  # Optional
-
-# Thunder IDP configuration (for authentication)
-export THUNDER_BASE_URL=http://localhost:8090
-# export THUNDER_TOKEN=your-thunder-token  # Optional: uncomment if needed
-
-# OAuth authentication credentials
-export OPENCHOREO_AUTH_CLIENT_ID=openchoreo-backstage-client
-export OPENCHOREO_AUTH_CLIENT_SECRET=your-client-secret
-export OPENCHOREO_AUTH_AUTHORIZATION_URL=http://localhost:8090/oauth2/authorize
-export OPENCHOREO_AUTH_TOKEN_URL=http://localhost:8090/oauth2/token
-```
-
-#### Optional Variables
+# Copy the pre-configured local development template
+cp app-config.local.yaml.example app-config.local.yaml
 
-```bash
-# GitHub integration (for catalog and templates)
-export GITHUB_TOKEN=your-github-personal-access-token
-```
-
-#### Complete .env.example
-
-Here's a complete example you can copy to create a `.env` file:
+# Start Backstage
+yarn start
 
-```bash
-# Backstage Configuration
-BACKSTAGE_BASE_URL=http://localhost:3000
-BACKEND_SECRET=change-me-in-production
-
-# OpenChoreo API
-OPENCHOREO_API_URL=http://localhost:8080/api/v1
-OPENCHOREO_TOKEN=
-
-# Thunder IDP
-THUNDER_BASE_URL=http://localhost:8090
-# THUNDER_TOKEN=
-
-# OAuth Authentication
-OPENCHOREO_AUTH_CLIENT_ID=openchoreo-backstage-client
-OPENCHOREO_AUTH_CLIENT_SECRET=backstage-portal-secret
-OPENCHOREO_AUTH_AUTHORIZATION_URL=http://localhost:8090/oauth2/authorize
-OPENCHOREO_AUTH_TOKEN_URL=http://localhost:8090/oauth2/token
-
-# GitHub Integration (Optional)
-GITHUB_TOKEN=
+# Access at http://localhost:3000
 ```
 
-#### Local Development Considerations
-
-**IMPORTANT:** The `BACKSTAGE_BASE_URL` variable is used for both `app.baseUrl` and `backend.baseUrl` in the configuration. This works well in production with ingress routing but requires special handling for local development:
-
-**Development Mode (`yarn start`):**
-
-- Frontend runs on **http://localhost:3000** (webpack dev server with hot reloading)
-- Backend runs on **http://localhost:7007** (API only)
-- These run as **separate processes on different ports**
-- The `@backstage/plugin-app-backend` is loaded but inactive (no built assets to serve)
-- Access the application at **http://localhost:3000**
+This is the **easiest way** to get started - all values are pre-configured to connect your local Backstage instance to the Kind cluster services (*.openchoreo.localhost).
 
-**Production/Build Mode:**
+#### What's in app-config.local.yaml?
 
-- Frontend must be built first: `yarn build:all`
-- Backend serves the built static assets via `@backstage/plugin-app-backend`
-- Both accessible from the same URL (e.g., **http://localhost:7007** or ingress URL)
+The `app-config.local.yaml.example` file contains hardcoded values for:
 
-**Configuration Options for Local Development:**
+- **Frontend URL:** `http://localhost:3000`
+- **Backend URL:** `http://localhost:7007`
+- **OpenChoreo API:** `http://api.openchoreo.localhost` (Kind cluster)
+- **Thunder IDP:** `http://sts.openchoreo.localhost` (Kind cluster)
+- **OAuth Credentials:** Pre-configured from Kind cluster helm values
+  - Client ID: `openchoreo-backstage-client`
+  - Client Secret: `backstage-portal-secret`
 
-Since frontend and backend run on separate ports in development, you need to configure the URLs accordingly:
+**Note:** `app-config.local.yaml` is gitignored and won't affect Docker builds or production deployments. The Docker build only uses `app-config.production.yaml`.
 
-- **Option 1 (Recommended):** Manually override in `app-config.yaml`:
+#### Optional: GitHub Integration
 
-  ```yaml
-  app:
-    baseUrl: http://localhost:3000 # Frontend URL
+If you need GitHub integration for catalog/templates, add your personal access token to `app-config.local.yaml`:
 
-  backend:
-    baseUrl: http://localhost:7007 # Backend API URL
-    cors:
-      origin: http://localhost:3000 # Allow frontend to call backend
-  ```
-
-- **Option 2:** Create `app-config.local.yaml` (not tracked in git) with the above overrides.
-
-- **Option 3:** Use environment variables:
-  ```bash
-  export BACKSTAGE_BASE_URL=http://localhost:3000  # For app.baseUrl
-  # Note: You'll still need to override backend.baseUrl and cors.origin in config
-  ```
-
-**Production/Kind with Ingress:**
+```yaml
+integrations:
+  github:
+    - host: github.com
+      token: YOUR_GITHUB_TOKEN_HERE
+```
 
-- Set `BACKSTAGE_BASE_URL` to your ingress URL (e.g., `http://openchoreo.localhost`)
-- The ingress routes both frontend and backend through the same origin
-- Both `app.baseUrl` and `backend.baseUrl` use the same value
+### 3. Configuration Files
 
-### 3. Configuration
+The application uses three configuration files:
 
-The application uses two primary configuration files:
+| File | Purpose | Used When |
+|------|---------|-----------|
+| `app-config.yaml` | Base configuration with environment variable placeholders | Referenced by both local and Docker builds |
+| `app-config.local.yaml` | Local development overrides (gitignored) | Local development with `yarn start` |
+| `app-config.production.yaml` | Production configuration | Docker builds, Kind cluster, production Kubernetes |
 
-- `app-config.yaml` - Base configuration for local development (uses environment variables)
-- `app-config.production.yaml` - Production configuration
+**Configuration Loading Order:**
 
-You can optionally create `app-config.local.yaml` for local overrides (this file is not tracked in git).
+Backstage CLI automatically loads configs in this order (later files override earlier ones):
+1. `app-config.yaml`
+2. `app-config.local.yaml` (if it exists)
 
-#### Environment-Driven Configuration
+#### Advanced: Using Environment Variables
 
-All configuration now uses environment variables for flexibility across deployment environments. Key configuration sections in `app-config.yaml`:
+If you prefer to use environment variables instead of `app-config.local.yaml`, you can set these in your shell:
 
-```yaml
-# Backstage base URLs (from commit 5d84dd7)
-app:
-  title: OpenChoreo Portal
-  baseUrl: ${BACKSTAGE_BASE_URL} # Frontend URL
-
-backend:
-  baseUrl: ${BACKSTAGE_BASE_URL} # Backend API URL
-  session:
-    secret: ${BACKEND_SECRET} # Required for authentication cookies
-  cors:
-    origin: ${BACKSTAGE_BASE_URL} # CORS origin (should match frontend URL)
-
-# OpenChoreo integration
-openchoreo:
-  baseUrl: ${OPENCHOREO_API_URL}
-  token: ${OPENCHOREO_TOKEN} # optional
-  defaultOwner: 'platformengineer'
-  schedule:
-    frequency: 30 # seconds between catalog syncs
-    timeout: 120 # request timeout
-
-# Thunder IDP integration
-thunder:
-  baseUrl: ${THUNDER_BASE_URL} # e.g., http://localhost:8090
-  # token: ${THUNDER_TOKEN}  # Optional: uncomment if needed
-  defaultNamespace: 'default'
-  schedule:
-    frequency: 600 # seconds between runs (10 minutes)
-    timeout: 300 # seconds for timeout (5 minutes)
-
-# OAuth authentication provider
-auth:
-  environment: development
-  providers:
-    default-idp:
-      development:
-        clientId: ${OPENCHOREO_AUTH_CLIENT_ID}
-        clientSecret: ${OPENCHOREO_AUTH_CLIENT_SECRET}
-        authorizationUrl: ${OPENCHOREO_AUTH_AUTHORIZATION_URL}
-        tokenUrl: ${OPENCHOREO_AUTH_TOKEN_URL}
-        scope: 'openid profile email'
-
-# GitHub integration (optional)
-integrations:
-  github:
-    - host: github.com
-      token: ${GITHUB_TOKEN}
+```bash
+export BACKSTAGE_BASE_URL=http://localhost:3000
+export BACKEND_SECRET=your-secret-key-here
+export OPENCHOREO_API_URL=http://api.openchoreo.localhost
+export THUNDER_BASE_URL=http://sts.openchoreo.localhost
+export OPENCHOREO_AUTH_CLIENT_ID=openchoreo-backstage-client
+export OPENCHOREO_AUTH_CLIENT_SECRET=backstage-portal-secret
+export OPENCHOREO_AUTH_AUTHORIZATION_URL=http://sts.openchoreo.localhost/oauth2/authorize
+export OPENCHOREO_AUTH_TOKEN_URL=http://sts.openchoreo.localhost/oauth2/token
+export GITHUB_TOKEN=your-github-token  # Optional
 ```
 
-**Note:** In production deployments (Kubernetes/Helm), these environment variables are automatically injected by the Helm chart. See the [openchoreo/openchoreo repository](https://github.com/openchoreo/openchoreo) deployment configuration at `install/helm/openchoreo/templates/backstage/deployment.yaml` for details.
+Then run: `yarn start`
+
+**Note:** In production deployments (Kubernetes/Helm), environment variables are automatically injected by the Helm chart. See the [openchoreo/openchoreo repository](https://github.com/openchoreo/openchoreo) at `install/helm/openchoreo/templates/backstage/deployment.yaml` for details.
 
 ### 4. Start the Application
 
diff --git a/app-config.local.yaml.example b/app-config.local.yaml.example
@@ -0,0 +1,67 @@
+# Local Development Configuration for Backstage with Kind Cluster
+#
+# This file contains pre-configured values for running Backstage locally
+# (at localhost:3000 and localhost:7007) while connecting to services
+# running in a Kind cluster (*.openchoreo.localhost).
+#
+# Quick Start:
+#   1. Copy this file: cp app-config.local.yaml.example app-config.local.yaml
+#   2. Start Backstage: yarn start
+#   3. Access at: http://localhost:3000
+#
+# Note: app-config.local.yaml is gitignored and won't affect production builds.
+# The Docker build only uses app-config.production.yaml.
+
+app:
+  # Backstage frontend URL (local development)
+  baseUrl: http://localhost:3000
+
+backend:
+  # Backstage backend URL (local development)
+  baseUrl: http://localhost:7007
+
+  # CORS configuration for local development
+  cors:
+    origin: http://localhost:3000
+    methods: [GET, HEAD, PATCH, POST, PUT, DELETE]
+    credentials: true
+
+  # Session secret for authentication cookies (development only)
+  session:
+    secret: dev-secret-change-in-production
+    cookie:
+      secure: false
+      sameSite: 'lax'
+      httpOnly: true
+      path: /
+      maxAge: 86400000 # 24 hours
+
+# OpenChoreo API configuration (Kind cluster)
+openchoreo:
+  baseUrl: http://api.openchoreo.localhost
+  # token: ""  # Optional: uncomment if you need API authentication
+
+# Thunder IDP configuration (Kind cluster)
+thunder:
+  baseUrl: http://sts.openchoreo.localhost
+
+# OAuth authentication configuration (Kind cluster)
+auth:
+  environment: development
+  providers:
+    default-idp:
+      development:
+        # OAuth credentials from Kind cluster helm values
+        # (see openchoreo/install/dev/openchoreo-values.yaml)
+        clientId: openchoreo-backstage-client
+        clientSecret: backstage-portal-secret
+        authorizationUrl: http://sts.openchoreo.localhost/oauth2/authorize
+        tokenUrl: http://sts.openchoreo.localhost/oauth2/token
+        scope: 'openid profile email'
+
+# GitHub integration (optional)
+# Uncomment and add your personal access token if you need GitHub integration
+# integrations:
+#   github:
+#     - host: github.com
+#       token: YOUR_GITHUB_TOKEN_HERE
diff --git a/app-config.yaml b/app-config.yaml
@@ -1,3 +1,16 @@
+# Base Backstage Configuration
+#
+# This file contains the base configuration with environment variable placeholders.
+# Environment variables are used in Docker builds and production deployments.
+#
+# For local development with Kind cluster:
+#   1. Copy the example file: cp app-config.local.yaml.example app-config.local.yaml
+#   2. Run: yarn start
+#   3. The app-config.local.yaml will automatically override values from this file
+#
+# Note: app-config.local.yaml is gitignored and won't affect Docker builds.
+# Docker builds only use app-config.production.yaml.
+
 app:
   title: OpenChoreo Portal
   # Environment variable is injected by Helm chart (see https://github.com/openchoreo/openchoreo install/helm/openchoreo/templates/backstage/deployment.yaml)
@@ -9,7 +22,6 @@ organization:
   name: OpenChoreo
 
 backend:
-  https: true
   # Used for enabling authentication, secret is shared by all backend plugins
   # See https://backstage.io/docs/auth/service-to-service-auth for
   # information on the format
