Prerequisites & Environment Setup¶

This guide walks you through installing every tool you need before you can build and run LBS Foundry. Once everything here is installed, follow backend-local-setup.md to create the databases, configure the project, and run it.

Every tool below has two install paths:

PowerShell (recommended) — copy-paste, fast, repeatable.
Browser fallback — for when winget is blocked, broken, or you prefer the GUI.

Each step ends with a small Verify check so you know you didn't skip anything.

1. System Requirements¶

Operating System¶

Windows 10/11 (recommended — this guide is written for Windows)
macOS (supported — substitute brew for winget)
Linux (Ubuntu 20.04+ supported)

Hardware¶

RAM: 16 GB minimum, 32 GB recommended
Storage: 10 GB free space minimum (SSD strongly recommended)
CPU: Multi-core processor recommended

2. .NET 10 SDK¶

The Foundry backend targets .NET 10. You need the SDK (not just the runtime).

PowerShell (recommended):

winget install --id Microsoft.DotNet.SDK.10 -e

Browser fallback: https://dotnet.microsoft.com/download/dotnet/10.0 → download the SDK x64 Installer for Windows.

After install, close and reopen PowerShell.

Verify:

dotnet --version       # should print 10.0.x
dotnet --list-sdks     # should list 10.0.x

3. SSH Key Setup¶

You'll need an SSH key to push to GitHub and clone private repos.

# Generate an SSH key (press Enter to accept defaults)
ssh-keygen -t ed25519 -C "your.email@luckboxstudios.com"

# Start the SSH agent and add the key
Start-Service ssh-agent
ssh-add $env:USERPROFILE\.ssh\id_ed25519

# Print the public key — copy this and add it to GitHub → Settings → SSH Keys
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub

Verify: ssh -T git@github.com should print Hi <username>! You've successfully authenticated...

4. Software Installation¶

The rest of this guide installs the tools you need, in roughly the order you'll first use them.

4.1 Google Chrome¶

You'll need Chrome for several account setups, OAuth flows, and Clerk's dashboard.

PowerShell (recommended):

winget install --id Google.Chrome -e

Browser fallback: https://www.google.com/chrome/ → click Download Chrome → run the installer.

After install: 1. Open Chrome. 2. Sign in with your Luckbox Google account (from Phase 2.1). 3. Enable Sync so your bookmarks/passwords follow you across machines.

Verify: search "Chrome" in Start Menu — it should appear.

4.2 Windows Terminal & PowerShell 7¶

The default Windows PowerShell is 5.x. Foundry's tooling assumes PowerShell 7+ (pwsh).

PowerShell (recommended):

winget install --id Microsoft.WindowsTerminal -e
winget install --id Microsoft.PowerShell -e

Browser fallback: - Windows Terminal → Microsoft Store: https://aka.ms/terminal - PowerShell 7 → https://github.com/PowerShell/PowerShell/releases/latest (download the .msi for x64)

After install: 1. Open Windows Terminal. 2. Press Ctrl + , (comma) to open Settings. 3. Set Default profile → PowerShell (the new one, not "Windows PowerShell"). 4. Click Save.

Verify: pwsh --version → should print 7.x or higher.

4.3 Visual Studio 2026 Insiders (Community)¶

The primary IDE for the .NET backend.

PowerShell (recommended):

winget install --id Microsoft.VisualStudio.Community.Insiders -e

Browser fallback: https://visualstudio.microsoft.com/insiders/ → click Download Insiders → choose Community 2026 Insiders → run the bootstrapper.

After install: 1. Open Visual Studio Installer (in your Start Menu). 2. Find Visual Studio Community 2026 Insiders → click Modify. 3. In the Workloads tab, check: - ASP.NET and Web Development - Azure Development - .NET Desktop Development 4. Click the Individual Components tab and check: - .NET 10.0 WebAssembly Build Tools 5. Click Modify (bottom-right) → wait for it to finish (15–30 min). 6. Open Visual Studio → sign in with your GitHub account.

Already installed? winget list --id Microsoft.VisualStudio.Community.Insiders

4.4 GitHub CLI + Copilot CLI Extension¶

gh is used for PRs, auth, and the Copilot CLI extension provides shell suggestions.

PowerShell (recommended):

winget install --id GitHub.cli -e

Browser fallback: https://cli.github.com/ → click Download for Windows → run the .msi.

After install, close and reopen PowerShell, then run:

gh auth login
gh extension install github/gh-copilot

Follow the prompts to log in via browser.

Verify: gh copilot --version

4.5 Git¶

PowerShell (recommended):

winget install --id Git.Git -e

Browser fallback: https://git-scm.com/download/win → run the 64-bit installer with default options.

After install, close and reopen PowerShell, then run:

git config --global user.name "John Doe"
git config --global user.email "john.doe@luckboxstudios.com"

Replace John Doe and john.doe@luckboxstudios.com with your actual info.

Verify:

git --version
git config --global user.name
git config --global user.email

4.6 Visual Studio Code¶

Used for the SvelteKit frontend, markdown, and lighter editing.

PowerShell (recommended):

winget install --id Microsoft.VisualStudioCode -e

Browser fallback: https://code.visualstudio.com/download → click Windows x64 User Installer → run it.

Then sign in: - Click the Account icon (bottom-left) → Sign in with GitHub.

Recommended extensions: - C# Dev Kit - TypeScript and JavaScript Language Features - ESLint - Prettier - GitLens - Svelte for VS Code

Verify: code --version

4.7 Azure Functions Core Tools¶

Required for running Azure Function-based services locally.

PowerShell (recommended):

winget install --id Microsoft.AzureFunctionsCoreTools -e

Browser fallback: https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local → download the Core Tools v4.x Windows installer.

Verify: func --version

4.8 PostgreSQL 18 + pgAdmin¶

The backend connects to two PostgreSQL databases (foundry and ballr). You'll create them in backend-local-setup.md § 1 — for now, just install Postgres and confirm pgAdmin is available.

PowerShell (recommended):

winget install --id PostgreSQL.PostgreSQL.18 -e

Browser fallback: https://www.postgresql.org/download/windows/ → click Download the installer → choose PostgreSQL 18 for Windows x86-64.

When the installer UI appears: 1. Run through with default options. 2. When asked for the superuser password, enter:

supremo

This password is required — the project configs assume it. If you must use a different password, you'll need to update appsettings.Development.json later. 3. Keep the default port 5432. 4. Let it also install pgAdmin (it usually comes bundled).

Verify: 1. Open pgAdmin from the Start Menu. 2. Connect to the local server using password supremo. 3. If it connects → it's working.

# Should report "accepting connections"
pg_isready

# Should connect using password 'supremo'
psql -U postgres -c "SELECT version();"

Tip: if pgAdmin was not installed (e.g. server-only package), grab it separately from https://www.pgadmin.org/download/.

4.9 Node.js 25 (Latest)¶

PowerShell (recommended):

winget install --id OpenJS.NodeJS -e

Browser fallback: https://nodejs.org/ → click the Current download (25.x.x) → run the installer.

After install, close and reopen PowerShell.

Verify:

node --version
npm --version

4.10 pnpm¶

Foundry's frontend uses pnpm, not npm, for workspace management.

PowerShell (must run after Node.js is installed):

npm install -g pnpm@latest

Browser fallback: https://pnpm.io/installation → follow "Using a standalone script" for Windows.

Verify: pnpm --version

4.11 Docker Desktop¶

LBS Foundry uses .NET Aspire, which orchestrates supporting containers (PostgreSQL helpers, Redis, etc.) when the project runs. The Foundry API will fail to start if Docker Desktop is not running.

PowerShell (recommended):

winget install --id Docker.DockerDesktop -e

Browser fallback: https://www.docker.com/products/docker-desktop/ → click Download for Windows → run the installer.

After install: 1. Restart your computer. 2. Open Docker Desktop. 3. Wait for the whale icon in the system tray to turn green (steady, not animated).

Verify: docker --version and docker ps (the latter should return an empty table without errors).

Note: keep Docker Desktop running the entire time you're working on Foundry.

4.12 Bruno¶

For exploring and testing the Foundry API.

PowerShell (recommended):

winget install --id Bruno.Bruno -e

Browser fallback: https://www.usebruno.com/downloads → click Download for Windows → run the installer.

4.13 DBeaver¶

ClickHouse Cloud has a great web console, but you'll also want a desktop SQL client. We recommend DBeaver Community — it has a built-in ClickHouse driver and also handles Postgres.

PowerShell (recommended):

winget install --id dbeaver.dbeaver -e

Browser fallback: https://dbeaver.io/download/ → click Windows (installer) → run the installer.

When you first launch DBeaver: 1. Click Database → New Database Connection. 2. Search for ClickHouse → Next. 3. Get the host / port / username / password from your ClickHouse Cloud console (Connect → JDBC). 4. Test connection → Save.

5. Verification Checklist¶

Run these from a fresh PowerShell window. All commands should succeed without errors.

# Core runtimes
dotnet --version         # 10.0.x
node --version           # v25.x
pnpm --version           # 9.x or higher
pwsh --version           # 7.x

# Source control
git --version
gh --version
gh copilot --version

# Databases
pg_isready               # "accepting connections"
psql --version

# Containers
docker --version
docker ps                # empty table, no error

# Azure Functions
func --version

You should also be able to launch from the Start Menu: - pgAdmin 4 - Visual Studio Community 2026 Insiders - Visual Studio Code - Docker Desktop (icon goes green in tray) - Windows Terminal (defaults to PowerShell 7) - Bruno - DBeaver

6. Common Installation Issues¶

.NET SDK¶

# Clear NuGet cache
dotnet nuget locals all --clear

# Confirm install
dotnet --info

Node.js / pnpm¶

# Clear npm cache
npm cache clean --force

# Reinstall pnpm
npm uninstall -g pnpm
npm install -g pnpm@latest

PostgreSQL¶

# Restart the PostgreSQL 18 service
Restart-Service postgresql-x64-18

# Check status
pg_isready

Git¶

# Reset and reconfigure
git config --global --unset-all user.name
git config --global --unset-all user.email
git config --global user.name "Your Name"
git config --global user.email "your.email@luckboxstudios.com"

Docker Desktop¶

If docker ps errors with "cannot connect", make sure Docker Desktop is running and the whale icon is steady green.
On first launch, Docker may prompt to enable WSL2 — accept and reboot.

7. Next Steps¶

Once all prerequisites are installed:

Backend Local Setup — create the foundry/ballr databases in pgAdmin, drop in launchsettings.json + appsettings.Development.json, build, and run.
Authentication Testing — verify auth end-to-end.
Common Tasks — make your first change.

8. Pro Tips¶

Windows Development¶

Use PowerShell 7+ (pwsh) — not the old Windows PowerShell 5.x.
Enable Developer Mode in Windows Settings (Settings → System → For developers).
Use Windows Terminal with multiple tabs/panes — much nicer than cmd.exe.
Configure Git Credential Manager (installed with Git for Windows by default).

Performance¶

Put your source folder (C:\Users\<you>\source\luckboxstudios) on an SSD.
Exclude build folders (bin/, obj/, node_modules/) from Windows Defender real-time scanning — this alone can cut build times by 30–50%.
Use a local NuGet package cache (default behavior — just don't override it).

Security¶

Keep all tools updated: winget upgrade --all.
Use SSH keys for Git authentication, not HTTPS + password.
Enable 2FA on your GitHub account.
Store secrets in user secrets (dotnet user-secrets), never in appsettings.json.