Quick Start — Creating a New Client Project¶

This guide walks through creating a new credit union website from scratch using the Progress platform. Follow these steps to go from zero to a running site in under 10 minutes.

Prerequisites¶

Tool	Version	Download
.NET SDK	10.0+	dotnet.microsoft.com
Git	Any	git-scm.com
Node.js	20+	nodejs.org (optional — only if you customise property editors)
SQL Server	2019+	LocalDB, any reachable SQL instance, or Azure SQL

Docker is not a prerequisite — the template and scaffolding are Docker-free. Production container hosting is a separate concern covered in the Docker Guide.

Verify your setup:

dotnet --version    # Should show 10.x
git --version

The simplest SQL option for local dev is LocalDB (bundled with the .NET SDK / SQL Server Express):

Server=(localdb)\MSSQLLocalDB;Database=mycu_v2;Integrated Security=true;TrustServerCertificate=true;MultipleActiveResultSets=true

Step 1: Install the Template¶

The template lives in the Umbraco.Core source repo. Clone it once and install the template from its templates/Progress.Template folder:

git clone https://dev.azure.com/ProgressSystemsLtd/CUCloud.Web/_git/Umbraco.Core
dotnet new install ./Umbraco.Core/templates/Progress.Template

Verify:

dotnet new list | grep progress-cu

Step 2: Scaffold the Project¶

dotnet new progress-cu \
  --ProjectName "MyCreditUnion" \
  --ClientSlug "mycu" \
  --Domain "mycu.ie" \
  --AdminEmail "admin@mycu.ie" \
  --AdminPassword "Admin2026Strong!" \
  --Country "Ireland" \
  --County "Wexford" \
  -o MyCreditUnion

Template parameters

Parameter	Required	What it does
`--ProjectName`	Yes	Display name of the credit union. Used in the backoffice and emails.
`--ClientSlug`	Yes	Lowercase slug. Used for the database name (`{slug}_v2`) and `ASPNETCORE_ENVIRONMENT`.
`--Domain`	Yes	Production domain. Configured in `Umbraco:CMS:WebRouting:UmbracoApplicationUrl`.
`--AdminEmail`	No	Umbraco admin email created via unattended install.
`--AdminPassword`	No	Umbraco admin password. Default `ChangeMe123!` — override at scaffold time. Must be ≥10 chars with upper/lower/digit.
`--Country`	No	Filters global notifications by country. Default: `Ireland`.
`--County`	No	Filters global notifications by county. Default: `Dublin`.
`--UmbracoVersion`	No	Umbraco CMS version. Default: `17.2.2`.

The generated project layout is fixed — regardless of --ProjectName, the host project is always at src/Progress.Web/Progress.Web.csproj:

MyCreditUnion/
├── .gitignore
├── nuget.config                        # Points to the client Azure Artifacts feed
├── MyCreditUnion.sln                   # Solution file (named from --ProjectName)
├── README.md
└── src/
    └── Progress.Web/
        ├── Progress.Web.csproj         # Thin host — references baseline NuGet packages
        ├── Program.cs                  # Calls AddProgressBaselineDefaults() + Umbraco pipeline
        ├── appsettings.json            # Client-configurable placeholders (see Step 4)
        ├── appsettings.Development.json
        ├── appsettings.Staging.json
        ├── appsettings.Production.json
        ├── Views/_ViewImports.cshtml   # Baseline views (301) are copied here on build
        └── wwwroot/
            └── cssCreditUnion/
                └── theme.css           # Client CSS theme overrides

Step 3: Configure the Database Connection¶

Edit the environment-specific appsettings (appsettings.Development.json for local dev) and set ConnectionStrings:umbracoDbDSN. The generated DB name is {slug}_v2, e.g. mycu_v2:

{
  "ConnectionStrings": {
    "umbracoDbDSN": "Server=(localdb)\\MSSQLLocalDB;Database=mycu_v2;Integrated Security=true;TrustServerCertificate=true;MultipleActiveResultSets=true",
    "umbracoDbDSN_ProviderName": "Microsoft.Data.SqlClient"
  }
}

You do not need to create the database manually — Umbraco installs the schema unattended on first run. Any reachable SQL Server instance works (LocalDB, on-prem, Azure SQL).

Step 4: Build and Run¶

cd MyCreditUnion
dotnet restore src/Progress.Web/Progress.Web.csproj
dotnet build   src/Progress.Web/Progress.Web.csproj
dotnet run     --project src/Progress.Web/Progress.Web.csproj

Azure Artifacts authentication

The four Progress.* packages restore from the client Azure Artifacts feed https://pkgs.dev.azure.com/ProgressSystemsLtd/CUCloud.Web/_packaging/CUCloud-Web-Packages/nuget/v3/index.json. Install the credential provider once, then either az login or use a PAT (Packaging: Read scope):

iex "& { $(irm https://aka.ms/install-artifacts-credprovider.ps1) }"
dotnet restore --interactive

In CI/CD pipelines, use the NuGetAuthenticate@1 task instead.

Build copies 301 baseline views

dotnet build copies 301 Razor views from the Progress.Baseline.Web NuGet package into your project's Views/ folder. Only new files (added in newer package versions) are copied on subsequent builds — your edits are never overwritten.

First run takes 1–2 minutes — Umbraco installs unattended and uSync imports 555+ content types, 666 data types, 142 dictionary items, and 36 templates.

Open your browser:

Site: https://localhost:5001
Backoffice: https://localhost:5001/umbraco

Log in with the admin email and password you provided.

Step 5: Configure Client Settings¶

Program.cs already wires up baseline defaults:

builder.Configuration.AddProgressBaselineDefaults();

This ships sensible defaults for BlockPreview, DisallowedUploadedFileExtensions, Runtime.Mode, etc. at the lowest precedence — anything you set in appsettings.json always wins. See the Baseline Architecture guide for the full list.

The scaffolded appsettings.json ships with empty placeholders for the values you'll typically want to fill in:

Key	Purpose
`OpenModulesUrl`	URL of the credit union's online banking / member portal
`FriendlyCaptcha:Secret` / `FriendlyCaptcha:SiteKey`	Friendly Captcha credentials for forms
`ProgressSettings:ProjectAlias`	Used by the Heartcore notifications integration
`ProgressSettings:GoogleMapsApiKey`	Branch locator map
`ProgressSettings:MapboxAccessToken`	Alternative map provider
`ProgressSettings:Twitter`	X/Twitter handle for social embeds
`ProgressSettings:Notifications`	Country / County / CuName filters for the global notifications banner

Empty placeholders are intentional — leave them blank if a feature is unused.

What Happens on First Run¶

sequenceDiagram
    participant Dev as Developer
    participant App as Umbraco App
    participant DB as SQL Server
    participant uSync as uSync

    Dev->>App: dotnet run
    App->>DB: Create Umbraco schema
    App->>DB: Create admin user (unattended)
    App->>uSync: Import content types
    uSync->>DB: Create document types, data types, templates
    App->>Dev: Site ready at localhost:5001

dotnet build copies baseline views into Views/
Umbraco detects empty database → runs unattended install
Creates the admin user from appsettings
uSync imports 555+ content types, 666 data types, 142 dictionary items, 36 templates
Site is ready — no manual Umbraco setup

Customising Your Client¶

CSS Theme¶

Edit src/Progress.Web/wwwroot/cssCreditUnion/theme.css:

:root {
  --main-blue: #103d5b;
  --main-green: #4eb53d;
  --link-color: #004cba;
}

.header { background-color: var(--main-blue); }
.btn-primary { background-color: var(--main-green); border-color: var(--main-green); }

See the CSS Theming Guide.

View Overrides¶

After dotnet build, all 301 baseline views are physically present in Views/. To customise one, just edit it in-place and commit. Subsequent NuGet upgrades will not overwrite existing files — only brand-new files are copied.

git diff -- Views/                       # See what you've customised
rm Views/Partials/SiteLayout/footer.cshtml  # Reset a file
dotnet build                              # Re-copies the baseline original

Pulling baseline updates into existing files — when a newer Progress.Baseline.Web version fixes or improves a view you have not customised, opt in explicitly:

dotnet build /p:BaselineUpdate=true       # Sync all baseline files; review with git diff

Identical files are a no-op, so only genuinely changed files appear in git diff — review file-by-file and commit what you want to keep. CI never sets this flag, so committed overrides are never silently clobbered. See the Baseline Architecture — Section 6 for the full workflow.

Configuration Layering¶

File	When loaded	Purpose
Baseline defaults	Always (lowest precedence)	Shipped via `AddProgressBaselineDefaults()`
`appsettings.json`	Always	Client-configurable values
`appsettings.Development.json`	`ASPNETCORE_ENVIRONMENT=Development`	Local dev (connection string, debug mode)
`appsettings.Staging.json`	`ASPNETCORE_ENVIRONMENT=Staging`	UAT/staging overrides
`appsettings.Production.json`	`ASPNETCORE_ENVIRONMENT=Production`	Production (BasicAuth, URLs, uSync disabled)

Never commit secrets

appsettings.Development.json is gitignored by default. Production credentials should be injected via environment variables or Key Vault.

NuGet Packages¶

The template references four shared packages, version-pinned to 1.* (stable per-major float):

Package	Description
Progress.Baseline.Core	Shared services, interfaces, DI registration, URL rewriting, security middleware, `AddProgressBaselineDefaults()`
Progress.Baseline.Web	190+ Razor views, 172 client CSS themes, JavaScript, vendor libraries
Progress.CustomPropertyEditors	31 custom Umbraco backoffice property editors
Progress.LoanCalculator	Loan calculation engine, API, and calculator views

Each tag on the Umbraco.Core repo's main branch produces a stable NuGet version (auto-bumped patch — e.g. 1.0.7 → 1.0.8). Clients pinned to 1.* get fixes automatically on the next restore. See Baseline Architecture for the full release model.

Troubleshooting¶

NuGet restore fails with '401 Unauthorized'

Run az login (or set up a PAT) and ensure the Azure Artifacts credential provider is installed. Then dotnet restore --interactive.

NuGet restore fails with 'package not found'

Check that nuget.config points to the CUCloud-Web-Packages feed and the Progress.* package source mapping is present.

Umbraco shows the install screen instead of auto-installing

Verify Umbraco:CMS:Unattended:InstallUnattended is true in appsettings.json and the connection string is correct.

Views are missing or show errors

Run dotnet build (not just dotnet restore). The build step copies 301 baseline views from the Progress.Baseline.Web package into Views/.

CSS theme not applied

The stylesheet is loaded via the siteStyleSheet property on the Website Configuration content node. Confirm the file exists at wwwroot/cssCreditUnion/theme.css and the property points to cssCreditUnion/theme.css.