Skip to content

02-setup-local.md

Latest commit

 

History

History
217 lines (144 loc) · 8.67 KB

02-setup-local.md

File metadata and controls

217 lines (144 loc) · 8.67 KB

Local Setup 🖥️

Use this guide if you prefer to run everything on your own laptop.
You have two paths: (A) native Python + virtual-env or (B) VS Code Dev Container with Docker.
Choose whichever feels easier—both lead to the same lessons.

1. Prerequisites

Tool Version / Notes
Python 3.10 + (get it from https://python.org)
Git Latest (comes with Xcode / Git for Windows / Linux package manager)
VS Code Optional but recommended https://code.visualstudio.com
Docker Desktop Only for Option B. Free install: https://docs.docker.com/desktop/

💡 Tip – Verify tools in a terminal:
python --version, git --version, docker --version, code --version

2. Option A – Native Python (quickest)

Step 1 Clone this repo

git clone https://github.com/<your-github>/generative-ai-for-beginners
cd generative-ai-for-beginners

Step 2 Create & activate a virtual environment

python -m venv .venv          # make one
source .venv/bin/activate     # macOS / Linux
.\.venv\Scripts\activate      # Windows PowerShell

✅ Prompt should now start with (.venv)—that means you’re inside the env.

Step 3 Install dependencies

pip install -r requirements.txt

Skip to Section 3 on API keys

2. Option B – VS Code Dev Container (Docker)

We setup this repository and course with a development container that has a Universal runtime that can support Python3, .NET, Node.js and Java development. The related configuration is defined in the devcontainer.json file located in the .devcontainer/ folder at the root of this repository.

Why choose this? Identical environment to Codespaces; no dependency drift.

Step 0 Install the extras

Docker Desktop – confirm docker --version works. VS Code Remote – Containers extension (ID: ms-vscode-remote.remote-containers).

Step 1 Open the repo in VS Code

File ▸ Open Folder… → generative-ai-for-beginners

VS Code detects .devcontainer/ and pops a prompt.

Step 2 Reopen in container

Click “Reopen in Container”. Docker builds the image (≈ 3 min first time). When the terminal prompt appears, you’re inside the container.

2. Option C – Miniconda

Miniconda is a lightweight installer for installing Conda, Python, as well as a few packages. Conda itself is a package manager, that makes it easy to setup and switch between different Python virtual environments and packages. It also comes in handy for installing packages that are not available via pip.

Step 0 Install Miniconda

Follow the MiniConda installation guide to set it up.

conda --version

Step 1 Create a virtual environment

Create a new environment file (environment.yml). If you are following along using Codespaces, create this within the .devcontainer directory, thus .devcontainer/environment.yml.

Step 2 Populate your environment file

Add the following snippet to your environment.yml

name: <environment-name>
channels:
 - defaults
 - microsoft
dependencies:
- python=<python-version>
- openai
- python-dotenv
- pip
- pip:
    - azure-ai-ml

Step 3 Create your Conda environment

Run the commands below in your command line/terminal

conda env create --name ai4beg --file .devcontainer/environment.yml # .devcontainer sub path applies to only Codespace setups
conda activate ai4beg

Refer to the Conda environments guide if you run into any issues.

2 Option D – Classic Jupyter / Jupyter Lab (in your browser)

Who’s this for?
Anyone who loves the classic Jupyter interface or wants to run notebooks without VS Code.

Step 1 Ensure Jupyter is installed

To start Jupyter locally, head over to the terminal/command line, navigate to the course directory, and execute:

jupyter notebook

or

jupyterhub

This will start a Jupyter instance and the URL to access it will be shown within the command line window.

Once you access the URL, you should see the course outline and be able to navigate to any *.ipynb file. For example, 08-building-search-applications/python/oai-solution.ipynb.

3. Add Your API Keys

Keeping your API keys safe and secure is important when building any type of application. We recommend not to store any API keys directly in your code. Committing those details to a public repository could result in security issues and even unwanted costs if used by a bad actor. Here's a step-by-step guide on how to create a .env file for Python and add the GITHUB_TOKEN:

  1. Navigate to Your Project Directory: Open your terminal or command prompt and navigate to your project's root directory where you want to create the .env file.

    cd path/to/your/project

  2. Create the .env File: Use your preferred text editor to create a new file named .env. If you're using the command line, you can use touch (on Unix-based systems) or echo (on Windows):

    Unix-based systems:

    touch .env

    Windows:

    echo . > .env

  3. Edit the .env File: Open the .env file in a text editor (e.g., VS Code, Notepad++, or any other editor). Add the following line to the file, replacing your_github_token_here with your actual GitHub token:

    GITHUB_TOKEN=your_github_token_here

  4. Save the File: Save the changes and close the text editor.

  5. Install python-dotenv: If you haven't already, you'll need to install the python-dotenv package to load environment variables from the .env file into your Python application. You can install it using pip:

    pip install python-dotenv

  6. Load Environment Variables in Your Python Script: In your Python script, use the python-dotenv package to load the environment variables from the .env file:

    from dotenv import load_dotenv
import os

# Load environment variables from .env file
load_dotenv()

# Access the GITHUB_TOKEN variable
github_token = os.getenv("GITHUB_TOKEN")

print(github_token)

That's it! You've successfully created a .env file, added your GitHub token, and loaded it into your Python application.

🔐 Never commit .env—it’s already in .gitignore. Full provider instructions live in providers.md.

4. What’s next?

I want to… Go to…
Start Lesson 1 01-introduction-to-genai
Setup an LLM Provider providers.md
Meet other learners Join our Discord

5. Troubleshooting

Symptom Fix
python not found Add Python to PATH or re-open terminal after install
pip cannot build wheels (Windows) pip install --upgrade pip setuptools wheel then retry.
ModuleNotFoundError: dotenv Run pip install -r requirements.txt (env wasn’t installed).
Docker build fails No space left Docker Desktop ▸ Settings ▸ Resources → increase disk size.
VS Code keeps prompting to reopen You may have both Options active; choose one (venv or container)
OpenAI 401 / 429 errors Check OPENAI_API_KEY value / request rate limits.
Errors using Conda Install Microsoft AI libraries using conda install -c microsoft azure-ai-ml