Merge pull request #55 from karpikpl/feature/configuration

Author: karpikpl

.dockerignore

@@ -1,4 +1,9 @@
-.env
+**/.env
+**/.env.local
+.env*
+.dockerignore
+**/node_modules/
+api/public
 .dockerignore
 .git
 .gitignore

.env

@@ -16,3 +16,7 @@ VUE_APP_GITHUB_TEAM=
 # Determines the GitHub Personal Access Token to use for API calls.
 # Create with scopes copilot, manage_billing:copilot or manage_billing:enterprise, read:enterprise AND read:org
 VUE_APP_GITHUB_TOKEN=
+
+# GitHub Api Url
+# for proxy api - set to /api/github defaults to https://api.github.com
+VUE_APP_GITHUB_API=

.github/workflows/deploy_proxy_to_ghcr.yml

@@ -0,0 +1,35 @@
+name: Build and push Docker image for Proxy
+
+on:
+  push:
+    branches:
+      - main
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+permissions:
+  packages: write
+
+jobs:
+  push_to_ghcr:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout GitHub Action
+        uses: actions/checkout@v4
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and Push Docker Image
+        run: |
+          GITHUB_REPO="${GITHUB_REPO,,}-with-proxy"  # convert repo name to lowercase as required by docker
+          echo "building docker image in repository '$GITHUB_REPO' ..."
+          docker build -f api.Dockerfile --label "org.opencontainers.image.title=copilot-metrics-viewer-with-proxy" --label "org.opencontainers.image.description=Metrics viewer with proxy for GitHub Copilot usage" --label "org.opencontainers.image.source=$GITHUB_REPO" -t ghcr.io/$GITHUB_REPO:latest .
+          docker push ghcr.io/$GITHUB_REPO:latest
+        env:
+          GITHUB_REPO: ${{ github.repository }}

.gitignore

@@ -21,3 +21,7 @@ pnpm-debug.log*
 *.njsproj
 *.sln
 *.sw?
+.azure
+
+api/public
+test.http

DEPLOYMENT.md

@@ -0,0 +1,171 @@
+# Deployment of Copilot Metrics Viewer
+
+There are a few ways to deploy the Copilot Metrics Viewer, depending on the type of metrics (Organization/Enterprise) and the level of control required.
+
+The app runs in a Docker container, so it can be deployed anywhere containers are hosted (AWS, GCP, Azure, Kubernetes, etc.).
+
+## Authentication to GitHub
+
+The Metrics Viewer can be integrated with GitHub application authentication, which authenticates the user and verifies their permissions to view the metrics. This option is recommended since it doesn't use Personal Access Tokens. The downside of using a GitHub application is that it can only authorize users to view metrics at the organization level (no support for Enterprise).
+
+With a Personal Access Token, user credentials are not verified, and the application simply renders Copilot metrics fetched using the PAT stored in the backend.
+
+## Authentication for Copilot Metrics Viewer
+
+By default Azure Deployments deploy a web app available on the public Internet without authentication (unless GitHub app is used).
+
+Application can be easily secured in azure using built-in features like Authentication settings on ACA/AppService (EasyAuth on Azure). Azure Container Apps and App Services allow for adding IP restrictions on ingress. Both can also be deployed using private networking architectures. 
+
+Options below provide most basic and cost effective ways of hosting copilot-metrics-viewer.
+
+## Scenario 1: One-click Azure Deployment
+
+The simplest way to deploy is to use the "one-click" option that creates resources in Azure. The deployment includes:
+
+* Azure Container App with a consumption environment
+* Azure Log Analytics Workspace
+
+![Azure ARM Deployment](./azure-deploy/arm-deployment.png)
+
+Application will use a pre-built docker image hosted in GitHub registry: `ghcr.io/github-copilot-resources/copilot-metrics-viewer-with-proxy`.
+
+**Prerequisites:** Contributor permission to a resource group in Azure and a subscription with the `Microsoft.App` resource provider enabled.
+
+> [!IMPORTANT]
+> **Estimated cost** for running this in Azure is about $1 per month, as Container Apps have the first 2 million requests each month free.
+
+1. **Option 1 - Using a Personal Access Token in the Backend**:
+
+    [![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fgithub-copilot-resources%2Fcopilot-metrics-viewer%2Fmain%2Fazure-deploy%2Fwith-token%2Fazuredeploy.json)
+
+2. **Option 2 - Using GitHub App Registration and GitHub Authentication**:
+
+    When using this method, [register your app in Github first](#github-app-registration).
+
+    [![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fgithub-copilot-resources%2Fcopilot-metrics-viewer%2Fmain%2Fazure-deploy%2Fwith-app-registration%2Fazuredeploy.json)
+
+    **Important**: After deploying Option 2, the redirect URI needs to be updated with the URL of the deployed container app.
+
+    Go to: `https://github.com/organizations/<your-org>/settings/apps/<your-app>` or in the UI to the settings of the registered application and add the following redirect URLs:
+
+    ```
+    http://<YOUR Container APP URL>.azurecontainerapps.io/callback
+    https://<YOUR Container APP URL>.azurecontainerapps.io/callback
+    ```
+
+### Deployment with private networking
+
+> [!CAUTION]
+> When deploying to a private network, specify a subnet (at least /23) for the Azure Container Apps Environment.
+App deployment does not create any DNS entries for the application, in order to create a private DNS Zone linked to provided Virtual Network, follow up the deployment with DNS deployment targeting same resource group:
+>
+>[![DNS Zone deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fgithub-copilot-resources%2Fcopilot-metrics-viewer%2Fmain%2Fazure-deploy%2Fdns%2Fazuredeploy.json)
+
+## Scenario 2: Azure Deployment with azd
+
+If more control over the deployed container image is needed, an infrastructure-as-code option has been provided using Azure Bicep. The application can be deployed using the [Azure Developer CLI](https://aka.ms/azd) (azd).
+
+In this scenario, the container is built from the source code locally, which provides additional opportunities to modify, scan, etc.
+
+**Prerequisites:** 
+- Contributor permission to a subscription in Azure with the `Microsoft.App` resource provider enabled.
+- Permissions for creating role assignments.
+- Azure CLI (az), Azure Developer CLI  (azd) and Docker installed locally.
+
+> [!IMPORTANT]
+> **Estimated cost** for running this in Azure is about $10 per month, Container Apps have the first 2 million requests each month free and Container Registry costs about $5.
+
+The deployment creates:
+
+* Azure Resource Group
+* Azure Container App with a consumption environment
+* Azure Container Registry
+* Azure Log Analytics Workspace
+* Azure Application Insights
+* Azure Key Vault
+
+![AZD Deployment](./azure-deploy/azd-deployment.png)
+
+Before running `azd up`, configure GitHub variables:
+
+```bash
+azd env set VUE_APP_SCOPE <organization/enterprise>
+# when using organization
+azd env set VUE_APP_GITHUB_ORG <org name>
+# when using enterprise
+azd env set VUE_APP_GITHUB_ENT <ent name>
+azd env set VUE_APP_GITHUB_API /api/github
+azd env set GITHUB_CLIENT_ID <client id>
+azd env set GITHUB_CLIENT_SECRET <client secret for the GH App>
+```
+
+## Scenario 3: Deploying the container
+
+Application can be deployed anywhere where containers can run and configured via environment variables:
+
+For GitHub App:
+
+```bash
+docker run -it --rm -p 3000:3000 \
+-e VUE_APP_SCOPE=organization \
+-e VUE_APP_GITHUB_API=/api/github  \
+-e VUE_APP_GITHUB_ORG=<org name> \
+-e GITHUB_CLIENT_ID=<client id> \
+-e GITHUB_CLIENT_SECRET=<client secret for the GH App> \
+-e SESSION_SECRET=<random string>  \
+ghcr.io/github-copilot-resources/copilot-metrics-viewer-with-proxy
+```
+
+or with PAT token and enterprise:
+
+```bash
+docker run -it --rm -p 3000:3000 \
+-e VUE_APP_SCOPE=enterprise \
+-e VUE_APP_GITHUB_API=/api/github  \
+-e VUE_APP_GITHUB_ENT=<enterprise name> \
+-e VUE_APP_GITHUB_TOKEN=<github PAT> \
+-e SESSION_SECRET=<random string>  \
+ghcr.io/github-copilot-resources/copilot-metrics-viewer-with-proxy
+```
+
+or with PAT token and organization:
+
+```bash
+docker run -it --rm -p 3000:3000 \
+-e VUE_APP_SCOPE=organization \
+-e VUE_APP_GITHUB_API=/api/github  \
+-e VUE_APP_GITHUB_ORG=<org name> \
+-e VUE_APP_GITHUB_TOKEN=<github PAT> \
+-e SESSION_SECRET=<random string>   \
+ghcr.io/github-copilot-resources/copilot-metrics-viewer-with-proxy
+```
+
+## Github App Registration
+
+While it is possible to run the API Proxy without GitHub app registration and with a hardcoded token, it is not the recommended way.
+
+To register a new GitHub App, follow these steps:
+
+> [!TIP]
+> Navigate using link: replace `<your_org>` with your organization name and open this link:
+[https://github.com/organizations/<your_org>/settings/apps](https://github.com/organizations/<your_org>/settings/apps)
+
+or navigate using UI:
+1. Go to your organization's settings.
+2. Navigate to "Developer settings".
+3. Select "GitHub Apps".
+4. Click "New GitHub App".
+
+1. Set a unique name.
+2. Provide a home page URL: your company URL or just `http://localhost`.
+3. Add a callback URL for `http://localhost:3000/callback`. (We'll add the real redirect URL after the application is deployed.)
+4. Uncheck the "Webhook -> Active" checkbox.
+5. Set the scopes:
+   - Select **Organization permissions**.
+   - Under **GitHub Copilot Business**, select **Access: Read-only**.
+6. Click on 'Create GitHub App' and, in the following page, click on 'Generate a new client secret'. (IMPORTANT: _**Save it for later**_)
+7. Install the app in the organization:
+   - Go to "Install App".
+   - Select your organization.
+
+Note the `Client ID` and `Private Key`.

README.md

@@ -150,6 +150,58 @@ docker run -p 8080:80 --env-file ./.env copilot-metrics-viewer
 ```
 The application will be accessible at http://localhost:8080
 
+## Running with API Proxy
+
+Project can run with an API proxy which hides GitHub tokens and is secure enough to be deployed.
+Api Proxy project is in `\api` directory. Vue app makes the calls to `/api/github` which then are proxied to `https://api.github.com` with appropriate bearer token.
+
+Proxy can authenticate user using GitHub App. In order to do that, following environment variables are required:
+
+* `GITHUB_CLIENT_ID` - client Id of the GitHub App registered and installed in the enterprise/org with permissions listed above.
+* `GITHUB_CLIENT_SECRET` - client secret of the GitHub App
+* `SESSION_SECRET` - random string for securing session state
+
+It's also possible to run with **PAT Token**, see examples below for required variables.
+
+For local development register `http://localhost:3000/callback` as GH App callback Uri.
+For deployed version use the Uri of your app.
+
+To build and run the app with API proxy:
+
+```bash
+docker build -t copilot-metrics-viewer-with-proxy -f api.Dockerfile .
+```
+
+To run:
+
+```bash
+docker run -it --rm -p 8080:3000 --env-file ./.env copilot-metrics-viewer-with-proxy
+```
+
+Proxy can also run with token hardcoded on the backend (which hides it from frontend calls), here's a sample:
+
+```bash
+docker run -it --rm -p 3000:3000 \
+-e VUE_APP_SCOPE=enterprise \
+-e VUE_APP_GITHUB_API=/api/github  \
+-e VUE_APP_GITHUB_ENT=<enterprise name> \
+-e VUE_APP_GITHUB_TOKEN=<github PAT> \
+-e SESSION_SECRET=<random string>  \
+copilot-metrics-viewer-with-proxy
+```
+
+or
+
+```bash
+docker run -it --rm -p 3000:3000 \
+-e VUE_APP_SCOPE=organization \
+-e VUE_APP_GITHUB_API=/api/github  \
+-e VUE_APP_GITHUB_ORG=<org name> \
+-e VUE_APP_GITHUB_TOKEN=<github PAT> \
+-e SESSION_SECRET=<random string>   \
+copilot-metrics-viewer-with-proxy
+```
+
 ## License 
 
 This project is licensed under the terms of the MIT open source license. Please refer to [MIT](./LICENSE.txt) for the full terms.

api.Dockerfile

@@ -0,0 +1,31 @@
+# Stage 1: Build the Vue.js application
+FROM node:14 as build-stage
+WORKDIR /app
+COPY package*.json ./
+RUN npm install
+COPY . .
+# this will tokenize the app
+RUN npm run build
+
+# Stage 2: Prepare the Node.js API
+FROM node:14 as api-stage
+WORKDIR /api
+# Copy package.json and other necessary files for the API
+COPY api/package*.json ./
+RUN npm install
+# Copy the rest of your API source code
+COPY api/ .
+
+# Copy the built Vue.js app from the previous stage
+COPY --from=build-stage /app/dist /api/public
+COPY --from=build-stage /app/dist/assets/app-config.js /api/app-config.template.js
+
+# install gettext-base for envsubst
+RUN apt-get update && apt-get install -y gettext-base
+
+# Expose the port your API will run on
+EXPOSE 3000
+
+# Command to run your API (and serve your Vue.js app)
+RUN chmod +x /api/docker-entrypoint.api/entrypoint.sh
+ENTRYPOINT ["/api/docker-entrypoint.api/entrypoint.sh"]

api/.env

@@ -0,0 +1,8 @@
+# Client Id from GitHub App installed on the organization
+GITHUB_CLIENT_ID=
+
+# Client Secret from GitHub App installed on the organization
+GITHUB_CLIENT_SECRET=
+
+# Secret for the session - random string for session
+SESSION_SECRET=

api/docker-entrypoint.api/entrypoint.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+
+configTemplateFile=/api/app-config.template.js
+configTargetFile=/api/public/assets/app-config.js
+
+# Temporarily unset VUE_APP_GITHUB_TOKEN
+# this is requiered until vue app is updated to remove tokens from it
+tempToken=$VUE_APP_GITHUB_TOKEN
+unset VUE_APP_GITHUB_TOKEN
+
+envsubst <"$configTemplateFile" >"$configTargetFile"
+
+# Restore VUE_APP_GITHUB_TOKEN
+export VUE_APP_GITHUB_TOKEN=$tempToken
+
+node server.mjs