diff --git a/.devcontainer/README.md b/.devcontainer/README.md new file mode 100644 index 0000000..d515bc0 --- /dev/null +++ b/.devcontainer/README.md @@ -0,0 +1,166 @@ +# GitHub Codespaces / Dev Container Configuration + +This folder contains the development container configuration for running the .NET AI Workshop in GitHub Codespaces or VS Code Dev Containers. + +## 🚀 Quick Start with GitHub Codespaces + +[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/dotnet-presentations/ai-workshop?quickstart=1) + +Click the badge above or follow these steps: + +1. Navigate to the repository on GitHub +2. Click the **Code** button +3. Select the **Codespaces** tab +4. Click **Create codespace on main** + +Your Codespace will be automatically configured with: + +- ✅ .NET 9.0 SDK +- ✅ Docker-in-Docker (for Qdrant vector database) +- ✅ Azure CLI and Azure Developer CLI +- ✅ GitHub CLI +- ✅ Microsoft.Extensions.AI.Templates pre-installed +- ✅ VS Code extensions for C# and GitHub Copilot + +## 📋 What's Included + +### Development Tools + +- **.NET 9.0 SDK**: Latest .NET runtime for AI Web Chat applications +- **Docker-in-Docker**: Required for running Qdrant vector database in Aspire +- **Azure CLI**: For deploying applications to Azure +- **Azure Developer CLI (azd)**: For streamlined Azure deployments +- **GitHub CLI**: For working with GitHub Models and repositories + +### VS Code Extensions + +- **GitHub Copilot**: AI-powered code completion +- **C# Dev Kit**: Full C# development experience +- **Azure GitHub Copilot**: Azure-specific AI assistance + +### Starting Solution + +The Codespace automatically: + +- Restores the **Part 2 - Project Creation** starting solution +- Sets it as the default solution in VS Code +- Configures port forwarding for the Aspire dashboard + +## 🔧 Configuration Details + +### Port Forwarding + +The following ports are automatically forwarded: + +- **18888**: Aspire Dashboard (primary port) +- **15000-15004**: Additional Aspire services ports +- Dynamic ports are forwarded as needed for your applications + +### Post-Creation Setup + +After the Codespace is created, the following commands run automatically: + +```bash +dotnet workload update +dotnet new install Microsoft.Extensions.AI.Templates +dotnet dev-certs https --trust +dotnet restore "Part 2 - Project Creation/GenAiLab" +``` + +## 📚 Next Steps + +Once your Codespace is ready: + +1. **Configure GitHub Token**: Follow [Part 1 - Setup](../Part%201%20-%20Setup/README.md) to create a GitHub token for GitHub Models +2. **Set User Secrets**: Right-click on `GenAiLab.AppHost` project and select "Manage User Secrets" +3. **Run the Application**: Press F5 or run `dotnet run --project "Part 2 - Project Creation/GenAiLab/GenAiLab.AppHost"` + +### 🔐 Managing Secrets in Codespaces + +#### GitHub Token for GitHub Models + +1. Create a GitHub token with **Models: Read-only** permission at [GitHub token settings](https://github.com/settings/personal-access-tokens/new) +2. In your Codespace, open the terminal +3. Navigate to the Part 2 solution: + + ```bash + cd "Part 2 - Project Creation/GenAiLab" + ``` + +4. Set the user secret: + + ```bash + dotnet user-secrets set "ConnectionStrings:openai" "Endpoint=https://models.inference.ai.azure.com;Key=YOUR-GITHUB-TOKEN" --project GenAiLab.AppHost + ``` + +#### Using Codespace Secrets (Recommended for Multiple Sessions) + +To avoid re-entering your token each time: + +1. Go to your GitHub settings → Codespaces → Secrets +2. Add a new secret named `GITHUB_MODEL_TOKEN` +3. Update your `.devcontainer/devcontainer.json` to include: + + ```json + "containerEnv": { + "GITHUB_MODEL_TOKEN": "${localEnv:GITHUB_MODEL_TOKEN}" + } + ``` + +4. Access it in your application configuration + +#### Azure OpenAI Configuration + +If using Azure OpenAI (Part 4+), store your endpoint and key: + +```bash +dotnet user-secrets set "ConnectionStrings:openai" "Endpoint=https://YOUR-RESOURCE.openai.azure.com;Key=YOUR-KEY" --project GenAiLab.AppHost +``` + +## 🌐 Alternative Configurations + +For developers who want to use local AI models or work offline, the original development container configurations are still available in `.github/.devcontainer/`: + +- **Standard Container**: `.github/.devcontainer/devcontainer.json` +- **Ollama Container**: `.github/.devcontainer/Ollama/devcontainer.json` + +See [.github/.devcontainer/README.md](../.github/.devcontainer/README.md) for details. + +## 🐛 Troubleshooting + +### Docker Issues + +If you encounter Docker-related errors when running Aspire applications: + +1. Ensure Docker is running: `docker ps` +2. Try restarting the Codespace +3. Check Docker service: `sudo systemctl status docker` + +### Port Forwarding Issues + +If the Aspire dashboard doesn't open automatically: + +1. Check the **Ports** tab in VS Code +2. Manually forward port 18888 or the dynamic port shown in the console +3. Click the globe icon to open the forwarded port in a browser + +### Memory Issues + +The Codespace requires at least 8GB of RAM. If you experience memory issues: + +1. Close unnecessary browser tabs +2. Stop unused Docker containers: `docker stop $(docker ps -q)` +3. Increase Codespace machine size (requires paid plan) + +## 💡 Tips + +- **Persist your GitHub token**: Store it in Codespace secrets for automatic configuration +- **Save your work frequently**: Codespaces auto-save, but commits ensure persistence +- **Use branches**: Create feature branches for your workshop progress +- **Port visibility**: Set port visibility to "Public" if you need to share your Aspire dashboard + +## 📖 Learn More + +- [VS Code Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) +- [GitHub Codespaces](https://docs.github.com/en/codespaces) +- [.NET Aspire Dev Containers](https://learn.microsoft.com/en-us/dotnet/aspire/get-started/dev-containers) diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000..900ce20 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,48 @@ +// For format details, see https://aka.ms/devcontainer.json. For config options, see the +// README at: https://github.com/devcontainers/templates/tree/main/src/dotnet +{ + "name": ".NET AI Workshop", + "image": "mcr.microsoft.com/devcontainers/dotnet:9.0", + "features": { + "ghcr.io/devcontainers/features/docker-in-docker:2": {}, + "ghcr.io/devcontainers/features/common-utils:2": {}, + "ghcr.io/devcontainers/features/azure-cli:1": { + "installBicep": true, + "version": "latest" + }, + "ghcr.io/azure/azure-dev/azd:0": { + "version": "stable" + }, + "ghcr.io/devcontainers/features/github-cli:1": {} + }, + "customizations": { + "vscode": { + "extensions": [ + "GitHub.copilot", + "ms-dotnettools.csdevkit", + "ms-azuretools.vscode-azure-github-copilot" + ], + "settings": { + "dotnet.defaultSolution": "Part 2 - Project Creation/GenAiLab/GenAiLab.sln" + } + } + }, + // Use 'forwardPorts' to make a list of ports inside the container available locally. + // Port ranges for Aspire dashboard (typically 18888 or dynamically allocated 15000-19999) + "forwardPorts": [15000, 15001, 15002, 15003, 15004, 18888], + "portsAttributes": { + "18888": { + "label": "Aspire Dashboard", + "protocol": "http", + "onAutoForward": "notify" + } + }, + // Use 'postCreateCommand' to run commands after the container is created. + "postCreateCommand": "bash .devcontainer/post-create.sh", + // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root. + "remoteUser": "vscode", + "hostRequirements": { + "memory": "8gb", + "cpus": 2 + } +} diff --git a/.devcontainer/post-create.sh b/.devcontainer/post-create.sh new file mode 100755 index 0000000..543e7b2 --- /dev/null +++ b/.devcontainer/post-create.sh @@ -0,0 +1,30 @@ +#!/bin/bash +set -e + +echo "Setting up .NET AI Workshop environment..." + +# Update dotnet workload +echo "Updating .NET workload..." +sudo dotnet workload update + +# Install AI templates +echo "Installing Microsoft.Extensions.AI.Templates..." +dotnet new install Microsoft.Extensions.AI.Templates + +# Trust dev certificates +echo "Trusting dev certificates..." +dotnet dev-certs https --trust || true + +# Navigate to Part 2 solution and restore +echo "Restoring Part 2 starting solution..." +cd "Part 2 - Project Creation/GenAiLab" +dotnet restore + +echo "✅ Environment setup complete!" +echo "" +echo "📚 To get started:" +echo " 1. Open the README.md at the root to view workshop instructions" +echo " 2. Follow Part 1 - Setup for GitHub token configuration" +echo " 3. Run the Part 2 solution to start the workshop" +echo "" +echo "🚀 Quick start: Open 'Part 2 - Project Creation/GenAiLab/GenAiLab.sln'" diff --git a/Part 1 - Setup/README.md b/Part 1 - Setup/README.md index 2793a40..5033006 100644 --- a/Part 1 - Setup/README.md +++ b/Part 1 - Setup/README.md @@ -1,11 +1,30 @@ # Part 1: Setup -> **⏱️ Estimated Time:** 15-20 minutes +> **⏱️ Estimated Time:** 15-20 minutes (or 5 minutes with GitHub Codespaces!) ## In this workshop In this workshop, you will set up your development environment for building AI applications with .NET. You'll install the required tools and configure your environment to work with the workshop materials. +## 🚀 Quick Start with GitHub Codespaces (Recommended) + +The fastest way to get started with no local installation required! + +[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/dotnet-presentations/ai-workshop?quickstart=1) + +**Why use Codespaces?** + +- ✅ No Docker installation required +- ✅ Pre-configured environment with all tools +- ✅ Works from any computer with a browser +- ✅ Perfect for workshops and training sessions + +Click the badge above, then skip to [Step 2: Create a GitHub Account](#step-2-create-a-github-account-if-needed) to continue. [Learn more about Codespaces](../.devcontainer/README.md). + +## Local Development Setup + +If you prefer to work locally or need offline access, follow the steps below. + ## Prerequisites Before starting, ensure you have: diff --git a/Part 2 - Project Creation/README.md b/Part 2 - Project Creation/README.md index 8011bf8..578ff13 100644 --- a/Part 2 - Project Creation/README.md +++ b/Part 2 - Project Creation/README.md @@ -1,11 +1,13 @@ # Create a new project using the AI Web Chat template -> **⏱️ Estimated Time:** 35-50 minutes +> **⏱️ Estimated Time:** 35-50 minutes (or skip to [Run the Application](#run-the-application) if using GitHub Codespaces) ## In this workshop In this workshop, you'll create a new project using the AI Web Chat template in Visual Studio. You'll configure GitHub Models as the AI service provider, set up the connection string, and run and explore the application. +> **💡 Using GitHub Codespaces?** If you opened this workshop in GitHub Codespaces, the Part 2 project is already created and restored! You can skip directly to [Set the GitHub Models connection string](#set-the-github-models-connection-string) and continue from there. + ## Create the project using Visual Studio Create a new project using the AI Web Chat template as follows: @@ -152,9 +154,18 @@ For GitHub Models to work, you need to set up a connection string with a GitHub > **Note**: For additional guidance on configuring GitHub Models access, see the [Microsoft documentation quickstart](https://learn.microsoft.com/en-us/dotnet/ai/quickstarts/ai-templates?tabs=dotnet-cli%2Cconfigure-visual-studio%2Cconfigure-visual-studio-aspire&pivots=github-models#configure-access-to-github-models). -1. In the Solution Explorer, right-click on the `GenAiLab.AppHost` project and select "Manage User Secrets" +2. **For Visual Studio users**: In the Solution Explorer, right-click on the `GenAiLab.AppHost` project and select "Manage User Secrets" + + **For Codespaces/CLI users**: Open a terminal and run: + + ```bash + cd "Part 2 - Project Creation/GenAiLab" + dotnet user-secrets set "ConnectionStrings:openai" "Endpoint=https://models.inference.ai.azure.com;Key=YOUR-GITHUB-TOKEN" --project GenAiLab.AppHost + ``` + + Replace `YOUR-GITHUB-TOKEN` with the token you created in step 1. -1. In the `secrets.json` file that opens, add the following connection string: +3. **For Visual Studio users only**: In the `secrets.json` file that opens, add the following connection string: ```json { @@ -164,27 +175,48 @@ For GitHub Models to work, you need to set up a connection string with a GitHub Replace `YOUR-API-KEY` with the GitHub token you created in step 1. -1. Save the `secrets.json` file. +4. **For Visual Studio users only**: Save the `secrets.json` file. ## Run the application Now let's run the application and explore its features: +### For Visual Studio Users + 1. Make sure that Docker Desktop is running. This is required to run containerized resources like Qdrant. 1. Make sure the `GenAiLab.AppHost` project is set as the startup project. 1. Press F5 or click the "Start Debugging" button in Visual Studio. - > **Note:** When running the application for the first time, Visual Studio may display a prompt asking you to trust the IIS Developer certificate. This prompt sometimes appears beneath the browser window. If the `aichatweb-app` resource doesn't start, check for this certificate prompt and click "Yes" to accept it. The application won't run until you've accepted this certificate. +### For GitHub Codespaces Users + +1. Docker is already running in your Codespace - no need to start it separately. + +1. Open a terminal in VS Code (Terminal → New Terminal) + +1. Navigate to the AppHost project and run it: + + ```bash + cd "Part 2 - Project Creation/GenAiLab" + dotnet run --project GenAiLab.AppHost + ``` + +1. VS Code will detect the forwarded ports and show a notification. Click "Open in Browser" when the Aspire dashboard port (typically 18888 or 15xxx) is ready. + +1. The .NET Aspire dashboard will open showing all services. Look for the `aichatweb-app` endpoint and click it to open the web application. + +### What Happens Next (All Users) + +> **Note for Visual Studio users:** When running the application for the first time, Visual Studio may display a prompt asking you to trust the IIS Developer certificate. This prompt sometimes appears beneath the browser window. If the `aichatweb-app` resource doesn't start, check for this certificate prompt and click "Yes" to accept it. The application won't run until you've accepted this certificate. - ![Trust SSL Certificate](../images/trust-ssl-certificate.png) +![Trust SSL Certificate](../images/trust-ssl-certificate.png) 1. The .NET Aspire dashboard will open in your browser first, displaying all the services in your application. -1. Shortly after, the web application will launch in another browser tab. +1. Shortly after, the web application will launch in another browser tab (or you can click the endpoint in the Aspire dashboard). -> If you run into issues running the Qdrant container, stop debugging and start it again. +> **Troubleshooting**: If you run into issues running the Qdrant container, stop debugging and start it again. In Codespaces, check that Docker is running with `docker ps`. ## Review the services in the .NET Aspire dashboard diff --git a/README.md b/README.md index e01850f..b1bd53f 100644 --- a/README.md +++ b/README.md @@ -2,8 +2,25 @@ Get up to speed quickly with AI app building in .NET! Explore the new .NET AI project templates integrated with Microsoft Extensions for AI (MEAI), GitHub Models, and vector data stores. Learn how to take advantage of free GitHub Models in development, then deploy with global scale and enterprise support using Azure OpenAI. Gain hands-on experience building cutting-edge intelligent solutions with state-of-the-art frameworks and best practices. +## 🚀 Quick Start with GitHub Codespaces + +The fastest way to get started! No local setup required - everything runs in the cloud. + +[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/dotnet-presentations/ai-workshop?quickstart=1) + +Click the badge above to launch a fully configured development environment with: + +- ✅ .NET 9.0 SDK pre-installed +- ✅ All required tools (Docker, Azure CLI, GitHub CLI) +- ✅ AI templates ready to use +- ✅ Starting solution pre-configured + +Perfect for users who can't install Docker locally or prefer a cloud-based environment. [Learn more about Codespaces setup](.devcontainer/README.md). + ## Prerequisites +> **💡 Using GitHub Codespaces?** If you're using GitHub Codespaces, most prerequisites are pre-installed. You only need a GitHub account and to follow the token configuration steps in Part 1. [Jump to Getting Started](#getting-started) + ### AI Web Chat Application Requirements (Parts 1-6) - Visual Studio 2022 or Visual Studio 2026