Module 3: Setting Up Your Environment | Spring AI for Beginners

"Ten minutes of setup now saves hours of confusion later. Let's get your machine ready to build AI apps."

Level: Beginner · Time: ~1 day · Prerequisites: Modules 1–2

Learning Objectives

By the end of this module, you will be able to:

Install Java and a code editor
Understand how a Spring AI project connects to an AI model
Store your API credentials safely with environment variables
Run a Spring Boot app from the command line

1. Install the Tools

You need three things:

A JDK (Java Development Kit) — version 17 or newer. This includes the compiler and the JVM. (Try Eclipse Temurin.)
A code editor — IntelliJ IDEA Community or VS Code with the Java extensions.
Maven — often bundled with your IDE, or install separately.

Check your install in a terminal:

bash

java -version    ,[object Object],
mvn -version

Beginner tip: If a command "isn't found," the tool isn't on your system PATH. Reinstalling and choosing "add to PATH," or restarting your terminal, fixes it most of the time.

Explain like I'm new: The JDK is the full workshop — compiler, JVM, and developer tools — while a plain JRE only runs finished programs. Because you're building apps, you need the JDK, and version 17+ is the modern baseline that Spring Boot 3 and Spring AI expect.

2. Get Access to an AI Model

Spring AI needs a model to talk to. The Microsoft curriculum uses Azure OpenAI (Microsoft Foundry), which gives you deployments like gpt-4o-mini (chat) and text-embedding-3-small (for RAG later). You can also use plain OpenAI or other providers — Spring AI supports many.

You'll end up with three pieces of information:

an endpoint (a URL),
an API key (a secret password), and
a deployment/model name (which model to use).

Concretely, that might look like an endpoint of https://my-team.openai.azure.com, a long secret key, and a deployment named gpt-4o-mini. Spring AI combines the three to build every request: the endpoint says where to send it, the key proves who you are, and the deployment name picks which model answers.

Concept: The API key is like the password to your AI account. Anyone who has it can spend your money. Treat it like a real password — never paste it into code you'll share, and never commit it to Git.

3. Store Credentials Safely

The golden rule: keep secrets out of your code. Put them in environment variables (or a local .env file that Git ignores), and have your app read them at runtime.

bash

[object Object],
,[object Object], AZURE_OPENAI_ENDPOINT=,[object Object],
,[object Object], AZURE_OPENAI_API_KEY=,[object Object],
,[object Object], AZURE_OPENAI_DEPLOYMENT=,[object Object],

Your application.yaml then references those variables — no secrets in the file itself:

yaml

[object Object],
  ,[object Object],
    ,[object Object],
      ,[object Object], ,[object Object],
      ,[object Object], ,[object Object],
      ,[object Object],
        ,[object Object], ,[object Object],

Security note: Add .env to your .gitignore the moment you create the project. Leaked API keys on public GitHub are found by bots within minutes and can run up large bills.

4. Add Spring AI to Your Project

In pom.xml, add the Spring AI starter for your provider. The starter pulls in the SDK plus Spring Boot auto-configuration:

xml

[object Object],
    ,[object Object],org.springframework.ai,[object Object],
    ,[object Object],spring-ai-starter-model-openai,[object Object],
,[object Object],

Rule of thumb: Use spring-ai-<provider> for plain Java programs, and spring-ai-starter-model-<provider> when you're inside a Spring Boot app (which you usually are).

5. Run the App

From the project directory:

bash

mvn spring-boot:run

Spring Boot starts a local web server (usually at http://localhost:8080). Open that in your browser and you'll see the app. To stop it, press Ctrl+C.

The first run is slower because Maven downloads dependencies and Spring Boot scans your classes to auto-configure beans; later runs start in seconds. Watch the console — Spring Boot prints a banner and a line like Started Application in 2.3 seconds once it's ready to serve requests.

Common mistake: Forgetting to set the environment variables before running. If you see an "authentication" or "missing API key" error, your variables aren't loaded in that terminal session — set them and run again.

✅ Checkpoint

What three pieces of information do you need to connect to an AI model?
Why should API keys live in environment variables, not in code?
What command runs a Spring Boot app?

Answers: 1) An endpoint URL, an API key, and a deployment/model name. 2) To keep secrets out of shared/committed code so they aren't leaked or abused. 3) mvn spring-boot:run.

Key Takeaway: Getting ready means installing a JDK (17+), an editor, and Maven; obtaining a model's endpoint, key, and name from a provider like Azure OpenAI; and — crucially — storing those secrets in environment variables referenced from application.yaml, never hard-coded. Add the Spring AI starter to pom.xml, then mvn spring-boot:run launches your app at localhost:8080.

Further Learning

Part of "Spring AI for Beginners." Adapted from Microsoft's open Spring AI curriculum (MIT License).