Table of Contents

Lesson 0: Setup

⏱️ 12:55–1:22 · Start as soon as you sit down, keep going while Lecture 1 runs, and finish at the setup checkpoint · Branch: init

Objective

Get The Rabbit Hole running on your machine, open the Umbraco backoffice, and save your AI key where the site can find it. Along the way, download every NuGet package the workshop needs in one go, so the lessons don't wait on conference Wi-Fi.

What you'll need

Tool Version Check with
.NET SDK 10.0 or later dotnet --version
Git any recent git --version
VS Code + the C# Dev Kit extension latest —
Note

The lessons use dotnet CLI commands so they work in any editor on any OS. If you prefer Visual Studio or Rider, go for it. You'll just translate the commands into your IDE.

You'll also need an AI key: your own OpenAI or Microsoft Foundry key. Bring your AI key shows how to get one, and Step 8 covers saving it.

Important

Missing the .NET 10 SDK? Start that download first, right now. It's the biggest thing on this page.

Steps

1. Clone the workshop repository

git clone https://github.com/marceldigital/Umbraco-AI-Workshop-2026.git

cd Umbraco-AI-Workshop-2026

2. Download everything in one go

The main branch uses every package you'll add during the lessons. Restoring it now downloads them all into your local NuGet cache while Lecture 1 runs, so each lesson's dotnet add package is instant.

git checkout main

dotnet restore

3. Switch to the starting point

git checkout init

init is the podcast site as a client might hand it to you: a working Umbraco 17 site with no AI features yet.

4. Trust the .NET development certificate

The site runs on HTTPS locally. Trust the development certificate so your browser doesn't complain:

dotnet dev-certs https --trust

Accept the prompt your OS shows you.

5. Run the site

dotnet run --project src/TheRabbitHole.Web

The first start takes a minute: it builds the solution and boots Umbraco. When you see Now listening on: https://localhost:44339 it's ready.

Note

The build shows two warnings: Parameter 'scopeFactory' is unread and Parameter 'hub' is unread. They're expected. Those are the services you'll put to work in Lesson 2.

Tip

To stop the site, press Ctrl+C in the terminal. Most lessons ask you to stop the site, make changes, and start it again.

6. Visit the site and the backoffice

  1. Open https://localhost:44339. You should see The Rabbit Hole homepage listing four episodes.
  2. Open https://localhost:44339/umbraco. You're signed in straight away as the Administrator, with no login screen.
Note

That's a development-only convenience built into the workshop site, so nobody has to type a password after switching branches. If you ever do see the login screen (after logging out, or a long break), click Sign in with Developer login, or log in with admin@example.com / password1234.

Deep dive: how the developer login works

The code is in src/TheRabbitHole.Web/AutoLogin/, wired up by .AddAutoLogin(builder.Environment) in Program.cs.

  • It registers a backoffice external login provider, the same mechanism you'd use for Microsoft Entra ID or Google. But its "remote" sign-in never leaves the site: it signs in the user named in Autologin:Backoffice:Email in appsettings.Development.json.
  • It also tells the backoffice login page to redirect to that provider automatically, which is why you never see the page.
  • It only switches on in the Development environment. Never enable anything like it on a real site: anyone who could reach the backoffice would be signed in as that user.
  • appsettings.Development.json also raises the backoffice session timeout (Umbraco:CMS:Global:TimeOut) to a day, so you aren't timed out while you're busy in your editor.

7. Find your AI key

You need three values: an API key, a chat endpoint and a transcription endpoint.

  • Already have an OpenAI or Microsoft Foundry key? Use it with the endpoints in the tabs below.
  • No key yet? Bring your AI key has the steps for both providers. Adding billing or deploying models can take a while, so leave the site running and come back here when you have your key.

8. Save your key and endpoints as user secrets

Pick your path and run the three commands from the repo root. Replace the key placeholder with your own key. You can run them while the site is running; it picks them up the next time it starts, which is the first thing Lesson 1 does.

dotnet user-secrets set "Umbraco:AI:Secrets:ApiKey" "<your-openai-key>" --project src/TheRabbitHole.Web

dotnet user-secrets set "Umbraco:AI:Variables:ChatEndpoint" "https://api.openai.com/v1/" --project src/TheRabbitHole.Web

dotnet user-secrets set "Umbraco:AI:Variables:TranscriptionEndpoint" "https://api.openai.com/v1/" --project src/TheRabbitHole.Web

On OpenAI, one endpoint serves both chat and transcription, so both variables get the same value.

User secrets live in your user profile, not in the repository, so they can't be committed by accident, and they stay put when you switch branches. Lesson 1, Step 4 explains how Umbraco AI reads them.

✅ Checkpoint

  • ⬜ The homepage lists 4 episodes, including The 500th Question.
  • ⬜ The backoffice opens without asking you to log in, and Content → Home → Episodes shows the same 4 episodes.
  • ⬜ The top navigation has no AI section yet. That's what we'll add in Lesson 1.
  • ⬜ You've saved your three user secrets.

🧯 Troubleshooting

I see the Umbraco login screen

Click Sign in with Developer login. The automatic sign-in skips the login screen, except straight after you've logged out or been timed out. If there's no Developer login button, make sure you started the site with dotnet run (which uses the Development environment), and log in with admin@example.com / password1234 meanwhile.

dotnet --version shows 8.x or 9.x

Install the .NET 10 SDK from the link above. Multiple SDKs can live side by side, and the repo automatically uses the newest installed SDK.

The restore is crawling

That's the conference Wi-Fi. Leave it running while Lecture 1 is on. If it fails partway through, run dotnet restore again: it keeps what it already downloaded.

"Address already in use" / port 44339 is taken

Something else (often another Umbraco site) is using the port. Stop it, or run on different ports:

dotnet run --project src/TheRabbitHole.Web --urls "https://localhost:44349;http://localhost:42048"

Use the new port in your browser. Lesson 6 assumes 44339, so switch back when you can.

The browser warns the connection isn't private

Re-run dotnet dev-certs https --trust and restart your browser. On Linux, follow the distro-specific instructions.

git checkout complains about local changes to Umbraco.sqlite.db

The site's SQLite database is part of the repo, so running the site changes it. If you've only been exploring, discard the changes:

git restore .

See Troubleshooting for more on switching branches.