Set up your computer for this course

#The 60-second version

Every deep layer in this course has something to build. To build it, a learner needs a small, standard toolkit on their laptop: the Python language, a code editor, Git to keep versions of their work, and a few free accounts.

This topic sets that up once, for the whole course. Each later unit starts with a short "Set up for Unit N" topic that adds only what that unit needs.

The toolkit is free. The SAP side uses SAP's public test system, the sandbox on the SAP Business Accelerator Hub, which holds demo data. The only optional cost is an AI model account, which charges a small amount per request.

#Why it matters to the business

If you manage people who are learning this, setup is where most of them quietly stop. Not because it is hard, but because one blocked install on a company laptop, or one confusing error, ends the evening.

Three things make the difference:

• A laptop they are allowed to install software on. Many corporate laptops block installs or route traffic through a proxy that blocks new sites.
• A rule about data. The course uses only demo data from SAP's sandbox and made-up sample data. Learners should never paste real customer or company data into exercises or into external AI services.
• A rule about keys. An API key is a password for a service. Keys belong in a private file on the learner's machine, never in code, chat messages or shared folders.

#What the setup involves

Plan for about an hour the first time. A learner who gets the check script at the end of the deep layer to print "All set" is ready for every Unit 1 exercise.

#A decision guide: which laptop?

• Personal laptop: the easiest path. Follow the deep layer as written.
• Company laptop with admin rights: usually fine. Check the proxy item below first.
• Locked-down company laptop: ask IT for the items in the next section before starting, or use a personal machine for the course.

#Questions to ask

• Can I install Python, VS Code and Git on this laptop, or does IT install them?
• Does our network block sandbox.api.sap.com or AI model APIs? Can they be allowed for learning?
• What is our policy on sending data to external AI services, even for training?
• Where should API keys for personal learning accounts be kept?
• Who pays for a model account if a learner needs one from Unit 5 onward?

#Common misconceptions

• "I need an SAP system to learn this." Not for most units. SAP's sandbox gives read access to demo data through the same APIs a real system offers.
• "Setup is a one-off chore for developers." Leaders who do it once understand much better what their teams mean by "environment", "keys" and "the proxy blocked it".
• "A trial account is fine for customer work." Trials and sandboxes are for learning. Real projects need proper licensed systems and the customer's approval.

#Key terms

• Terminal: a text window where you type commands.
• Virtual environment: a private copy of Python for one project, so installs don't clash.
• Package or library: ready-made code you install with pip.
• API key: a password that lets a program use a service.
• Environment variable: a named value, such as a key, that programs read at run time.
• .env file: a private text file that holds environment variables for one project.

#Check yourself

#Mental model: one course folder, one private Python, one private key file

Everything you build in this course lives in one folder on your computer. Inside it are:

• a virtual environment (.venv): a private copy of Python and its libraries, only for this course;
• a .env file: your keys, which never leave your machine;
• your code, one subfolder per unit, tracked by Git so you can see every change and build a portfolio.

flowchart TB
  F[orchestrate-course folder] --> V[.venv<br/>private Python + libraries]
  F --> E[.env<br/>your keys, never shared]
  F --> C[unit01, unit02, ...<br/>your code]
  F --> G[.git<br/>history of your work]
  C -->|reads keys from| E
  C -->|runs with| V

If something breaks later, it is almost always one of three things: the virtual environment isn't active, a library isn't installed in it, or a key isn't in .env. The check script at the end tests all three.

#How it works

When you type python triage.py, your terminal finds a Python program, which runs your file. If the virtual environment is active, the terminal uses the private Python in .venv, which has the libraries you installed. If it isn't active, it uses the system Python, which doesn't have them, and you see ModuleNotFoundError.

Keys work the same way. Your code asks for SAP_API_KEY by name. The python-dotenv library reads your .env file and makes its values available under those names. The key itself is never written in your code, so you can share or publish the code safely.

#Build it yourself: set up and check your computer

#What you need

• A Windows, macOS or Linux computer where you can install software.
• About an hour and an internet connection.
• No accounts yet; Step 6 creates the ones you need.

#Step 1: Install Python

Windows

1. Open the Microsoft Store, search for Python Install Manager, and install it. (You can also download it from python.org/downloads.)

2. Press the Windows key, type PowerShell, and press Enter. This opens a terminal.

3. Type the command below and press Enter. The first time, the manager downloads and installs the latest Python for you.

   Copy

   python --version

4. If it asks whether to add a folder to your PATH, answer yes. You should end with a line like Python 3.14.4.

macOS

1. Go to python.org/downloads, download the macOS installer and run it, accepting the defaults.

2. Press Cmd+Space, type Terminal, and press Enter.

3. Run:

   Copy

   python3 --version

   You should see a version line such as Python 3.14.4.

#Step 2: Install VS Code

VS Code is a free editor for writing code, with a terminal built in.

1. Download it from code.visualstudio.com and install it.
2. Open VS Code. Click the Extensions icon on the left (four small squares), search for Python, and install the one published by Microsoft.

#Step 3: Make your course folder

1. In your terminal, go to your home folder and create the course folder:

   Copy

   cd ~
   mkdir orchestrate-course
   cd orchestrate-course

   (cd means "change directory". ~ is your home folder; this works in PowerShell too.)

2. In VS Code, choose File > Open Folder and open orchestrate-course. From now on you can use VS Code's own terminal: Terminal > New Terminal.

#Step 4: Create and turn on the virtual environment

1. In the terminal, inside orchestrate-course, run:

   Copy

   python -m venv .venv

   (Use python3 on macOS or Linux.) This creates a hidden .venv folder.

2. Turn it on:

   • Windows (PowerShell):

     Copy

     .venv\Scripts\Activate.ps1

   • macOS / Linux:

     Copy

     source .venv/bin/activate

3. Your prompt now starts with (.venv). Do this every time you open a new terminal for the course.

4. In VS Code, press Ctrl+Shift+P (Cmd+Shift+P on Mac), run Python: Select Interpreter, and choose the one inside .venv. VS Code then activates it for you in new terminals.

#Step 5: Install the course libraries

1. In VS Code, choose File > New File, paste the three lines below, and save it as requirements.txt in your course folder:

   Copy

   requests
   anthropic
   python-dotenv

2. With (.venv) showing, run:

   Copy

   pip install -r requirements.txt

   Wait for "Successfully installed". Each unit's setup topic adds its own lines to this file.

#Step 6: Get your keys and store them in .env

SAP sandbox key (free, needed now)

1. Go to api.sap.com and click Log On at the top right. If you have no SAP account, register; it's free.
2. Search for Sales Order (A2X) and open it.
3. Click Show API Key, then Copy Key and Close.

Model key (optional until you use a model)

1. Create an account in the Claude Console, add a small amount of credit, and create an API key.

Store them

1. In VS Code, create a new file and save it as .env (just that, starting with a dot) in your course folder.

2. Put your keys in it, one per line, keeping the quotes:

   Copy

   SAP_API_KEY="paste-your-sap-key-here"
   ANTHROPIC_API_KEY="paste-your-model-key-here"

3. Save the file. Leave out the second line if you don't have a model key yet.

#Step 7: Install Git and start your portfolio

1. Install Git:

   • Windows: download the installer from git-scm.com/downloads and accept the defaults.
   • macOS: run xcode-select --install in the terminal and follow the prompts. It installs Git with Apple's command-line tools.

2. Close and reopen your terminal, reactivate .venv (Step 4), and check Git works:

   Copy

   git --version

3. Tell Git your name and email (it labels your changes with them):

   Copy

   git config --global user.name "Your Name"
   git config --global user.email "you@example.com"

4. In VS Code, create a file named .gitignore in the course folder with these two lines. They stop Git from tracking your keys and your private Python:

   Copy

   .env
   .venv/

5. Turn the folder into a Git repository and save a first version:

   Copy

   git init
   git add .
   git commit -m "Set up the course folder"

#Step 8: Run the check script

1. Create a new file, paste the script below, and save it as check_setup.py in your course folder.

2. With (.venv) showing, run:

   Copy

   python check_setup.py

"""Check that your computer is ready for the Orchestrate course.

Run it from your course folder:  python check_setup.py
It only reads your setup; it changes nothing and sends no keys anywhere.
"""
import importlib.util
import os
import shutil
import sys
import urllib.error
import urllib.request

problems = 0


def report(ok: bool, label: str, fix: str = "", optional: bool = False) -> None:
    """Print one line: OK, MISSING (must fix) or LATER (optional for now)."""
    global problems
    if ok:
        print(f"  OK       {label}")
    elif optional:
        print(f"  LATER    {label}  ->  {fix}")
    else:
        problems += 1
        print(f"  MISSING  {label}  ->  {fix}")


def reachable(url: str) -> bool:
    """True if the site answers at all. Any HTTP status, even an error, counts."""
    try:
        urllib.request.urlopen(url, timeout=10)
        return True
    except urllib.error.HTTPError:
        return True  # the site answered, it just wants a key
    except Exception:
        return False


print("\n1. Python")
v = sys.version_info
report(v >= (3, 10), f"Python {v.major}.{v.minor}.{v.micro}", "install Python 3.10 or newer (Step 1)")
in_venv = sys.prefix != sys.base_prefix
report(in_venv, "virtual environment is active", "activate .venv (Step 4)")

print("\n2. Libraries")
for module, package in [("requests", "requests"), ("anthropic", "anthropic"), ("dotenv", "python-dotenv")]:
    found = importlib.util.find_spec(module) is not None
    report(found, package, "pip install -r requirements.txt (Step 5)")

print("\n3. Keys")
if importlib.util.find_spec("dotenv") is not None:
    from dotenv import load_dotenv
    load_dotenv()  # reads the .env file in this folder, if there is one
report(os.path.exists(".env"), ".env file in this folder", "create it (Step 6)")
report(bool(os.environ.get("SAP_API_KEY")), "SAP_API_KEY", "add it to .env (Step 6)")
report(bool(os.environ.get("ANTHROPIC_API_KEY")), "ANTHROPIC_API_KEY",
       "optional until you use a model; add it to .env (Step 6)", optional=True)

print("\n4. Tools")
report(shutil.which("git") is not None, "git", "install Git (Step 7)")
report(os.path.isdir(".git"), "this folder is a Git repository", "run git init (Step 7)", optional=True)

print("\n5. Network")
report(reachable("https://sandbox.api.sap.com/"), "SAP sandbox (sandbox.api.sap.com)",
       "blocked: try another network or ask IT to allow it")
report(reachable("https://api.anthropic.com/"), "Model API (api.anthropic.com)",
       "blocked: try another network or ask IT to allow it", optional=True)

print()
if problems:
    print(f"{problems} item(s) to fix. Fix them in order, then run this again.")
    sys.exit(1)
print("All set. Your computer is ready for the course.")

#What success looks like

The first run on a fresh computer usually shows a few MISSING lines. That's the point: each one names the step that fixes it. Fix them in order and run the script again. When everything is ready you see:

1. Python
  OK       Python 3.14.4
  OK       virtual environment is active

2. Libraries
  OK       requests
  OK       anthropic
  OK       python-dotenv

3. Keys
  OK       .env file in this folder
  OK       SAP_API_KEY
  OK       ANTHROPIC_API_KEY

4. Tools
  OK       git
  OK       this folder is a Git repository

5. Network
  OK       SAP sandbox (sandbox.api.sap.com)
  OK       Model API (api.anthropic.com)

All set. Your computer is ready for the course.

LATER lines are fine for now. They mark things you need only in later units, such as the model key.

#What each part of the script does

The script uses only Python's built-in modules, so it runs even before Step 5. It changes nothing and sends no keys anywhere.

#If something goes wrong

#Where this shows up in SAP

On real projects you will meet the same ideas under SAP names. Keys become service keys and destinations on SAP BTP, created by an administrator instead of pasted into a file. Your private course folder becomes a project in a team repository with review rules. The habits are the same: never put credentials in code, keep a history of every change, and prove the environment works before blaming the code.

Later units add SAP-side setup when they need it, for example an SAP BTP trial account for the platform units. Each unit begins with a short Set up for Unit N topic that lists exactly what to add and why.

#Pitfalls

• Forgetting to activate .venv. The most common cause of "it worked yesterday". Look for (.venv) before running anything.
• Installing libraries with a different Python. If you ran pip install without .venv active, the libraries went elsewhere. Activate, then install again.
• Keys in code. Pasting a key into a script "just to test" is how keys leak when the file is shared. Always use .env.
• Company laptop surprises. Proxies and install blocks are normal. Ask IT early, or use a personal machine.
• Real data in exercises. Use the sandbox and sample data only. Never send company or customer data to an external AI service for practice.

#Exercise: prove your setup and save it

1. Complete Steps 1 to 8.

2. Run python check_setup.py until it prints All set, or until only LATER lines remain.

3. Save your work in Git:

   Copy

   git add check_setup.py
   git commit -m "Add setup check"

4. Create a folder unit01 inside your course folder. Put the blocked sales orders prototype there when you do it.

Done when: check_setup.py prints All set (or only LATER lines), and git log shows at least two commits. This folder is the start of the portfolio you build through Unit 14.

#Check yourself