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
Docker Desktop	Latest	docker.com (optional — for local SQL Server)
Node.js	20+	nodejs.org (optional — for custom property editors)

Verify your setup:

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

Option A: Automated Setup (Recommended)

The setup script handles everything — prerequisites check, project creation, SQL Server, database, build, and run:

# 1. Clone the repository
git clone https://dev.azure.com/ProgressSystemsLtd/CUCloud.Web/_git/psCreditUnion -b feature/upg-v17-double
cd psCreditUnion

# 2. Run the setup script (interactive — prompts for all values)
./templates/Progress.Template/setup.ps1

The script will interactively ask for your project name, domain, database credentials, and admin login. It then:

1. Installs the dotnet template
2. Creates the project with your parameters
3. Starts a SQL Server Docker container (if Docker is available)
4. Creates the client database
5. Restores NuGet packages and builds
6. Optionally runs the site

You can also pass parameters directly to skip the prompts:

./templates/Progress.Template/setup.ps1 `
  -ProjectName "MyCreditUnion" `
  -ClientSlug "mycu" `
  -Domain "mycu.ie" `
  -AdminEmail "admin@mycu.ie" `
  -AdminPassword "Admin2026Strong!"

---

Option B: Manual Step-by-Step

Step 1: Install the Template

# Clone the repository
git clone https://dev.azure.com/ProgressSystemsLtd/CUCloud.Web/_git/psCreditUnion -b feature/upg-v17-double
cd psCreditUnion

# Install the dotnet template
dotnet new install ./templates/Progress.Template

Step 2: Set Up Your Database

Choose how to set up your database. Most clients start from a migrated database template which already contains all content types, content, and media metadata from the v8 migration.

Restore from .bacpac Template (Recommended)

If you've received a .bacpac database template from the migration team, restore it to get a fully populated database with published content:

# Using sqlpackage CLI
sqlpackage /Action:Import \
  /TargetServerName:"localhost" \
  /TargetDatabaseName:"mycu_cms" \
  /SourceFile:"path/to/progress_mycu_v17.bacpac" \
  /TargetTrustServerCertificate:True

Or via SQL Server Management Studio: Right-click Databases → Import Data-tier Application → select the .bacpac file.

What's in the template?

The .bacpac contains the complete migrated v17 database: Umbraco schema, 555+ content types, 666 data types, all published content nodes, media metadata, forms, and user accounts. You get a working site immediately — no manual content creation needed.

After restoring, you still need a running SQL Server. Use Docker or an existing instance:

# Start SQL Server in Docker (if you don't have one)
docker run -d --name progress-sql -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=YourPassword1!" -e "MSSQL_PID=Developer" -p 1433:1433 mcr.microsoft.com/mssql/server:2022-latest

You can also start from an empty database if you prefer:

Docker (Recommended for local dev)Existing SQL ServerAzure SQL

docker run -d --name progress-sql -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=YourPassword1!" -e "MSSQL_PID=Developer" -p 1433:1433 mcr.microsoft.com/mssql/server:2022-latest

Wait ~10 seconds for SQL to start, then create the database:

docker exec progress-sql /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "YourPassword1!" -C -Q "CREATE DATABASE [mycu_cms]"

Port conflicts

If port 1433 is already in use, change -p 1433:1433 to e.g. -p 1434:1433. Then use localhost,1434 as your --DbServer in the next step.

Use any SQL Server instance you already have — local, Azure SQL, or remote. You just need a valid connection string. Create an empty database and note the server address, username, and password.

az sql server create --name mycu-sql --resource-group mycu-rg --admin-user sqladmin --admin-password "YourPassword1!"
az sql db create --server mycu-sql --resource-group mycu-rg --name mycu_cms --service-objective S0

Step 3: Create the Project

Single-line command (copy-paste friendly):

dotnet new progress-cu \
  --ProjectName "MyCreditUnion" \
  --ClientSlug "mycu" \
  --Domain "mycu.ie" \
  --DbServer "localhost" \
  --DbUser "sa" \
  --DbPassword "YourPassword1!" \
  --AdminEmail "admin@mycu.ie" \
  --AdminPassword "Admin2026Strong!" \
  --Country "Ireland" \
  --County "Wexford" \
  --NuGetFeedUrl "https://pkgs.dev.azure.com/ProgressSystemsLtd/CUCloud.Web/_packaging/CUCloud-Web-Packages/nuget/v3/index.json" \
  -o MyCreditUnion

What do these parameters mean?

Parameter	Required	What it does
--ProjectName	Yes	Display name of the credit union. Used in the Umbraco backoffice and page titles.
--ClientSlug	Yes	Short lowercase identifier. Used for the database name ({slug}_cms), Docker container name, ASPNETCORE_ENVIRONMENT value, and the client-specific appsettings.{slug}.json file.
--Domain	Yes	The production domain. Configured in Umbraco's WebRouting:UmbracoApplicationUrl so URLs and redirects work correctly.
--DbServer	No	SQL Server address. Default: localhost. Use localhost,1434 if you changed the Docker port. For Azure SQL: myserver.database.windows.net.
--DbUser	No	SQL Server username. Default: sa.
--DbPassword	No	SQL Server password. Must meet SQL Server complexity requirements.
--AdminEmail	No	Umbraco admin account email. Created automatically on first run via unattended install.
--AdminPassword	No	Umbraco admin password. Must be at least 10 characters with uppercase, lowercase, and a number.
--Country	No	Filters global notifications by country. Default: Ireland.
--County	No	Filters global notifications by county/region. Default: Dublin.
--UmbracoVersion	No	Umbraco CMS version. Default: 17.2.2.
--NuGetFeedUrl	No	Private NuGet feed URL for Progress packages. Default: https://pkgs.dev.azure.com/ProgressSystemsLtd/CUCloud.Web/_packaging/CUCloud-Web-Packages/nuget/v3/index.json. Requires Azure AD authentication (see NuGet Feed documentation).

This creates:

MyCreditUnion/
├── nuget.config                            # NuGet feed configuration (points to your --NuGetFeedUrl)
├── Dockerfile                              # Multi-stage Docker build for deployment
├── README.md                               # Project-specific docs
├── MyCreditUnion.sln                  # Solution file
└── src/
    └── MyCreditUnion/
        ├── MyCreditUnion.csproj       # Thin host — references baseline NuGet packages
        ├── Program.cs                      # Umbraco startup pipeline + DI
        ├── .gitignore                      # Ignores auto-generated schemas, dev settings
        ├── appsettings.json                # Base configuration (Umbraco, uSync, notifications)
        ├── appsettings.Development.json    # Local dev (connection string, debug mode)
        ├── appsettings.Staging.json        # UAT/staging overrides
        ├── appsettings.Production.json     # Production overrides
        ├── Views/
        │   └── _ViewImports.cshtml         # Razor imports (301 baseline views copied on build)
        ├── wwwroot/
        │   └── cssCreditUnion/
        │       └── theme.css               # Client CSS theme variables
        └── uSync/
            └── v17/                        # Schema files imported on first run
                ├── ContentTypes/           # 555+ document type definitions
                ├── DataTypes/              # 666 data type definitions
                ├── DictionaryItems/        # 142 dictionary items
                └── Templates/              # 36 template definitions

Step 4: Build and Run

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

Azure Artifacts Authentication

If using an Azure Artifacts feed (e.g. ProgressSystemsLtd), you need the credential provider installed:

# Install credential provider (one-time)
iex "& { $(irm https://aka.ms/install-artifacts-credprovider.ps1) }"

# First restore — triggers browser login
dotnet restore --interactive

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

Build copies 301 baseline views

The dotnet build step copies 301 Razor views (page templates, partials, BlockGrid/BlockList components) from the Progress.Baseline.Web NuGet package into your project's Views/ folder. This is required for Umbraco and uSync to find the templates. Always run dotnet build before dotnet run.

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

Open your browser:

• Site: http://localhost:5000
• Backoffice: http://localhost:5000/umbraco

Login with the admin email and password you provided.

---

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:5000

1. dotnet build copies baseline views — 301 .cshtml files from the NuGet package into your Views/ folder
2. Umbraco detects empty database → runs unattended install
3. Creates admin user with the email/password from appsettings
4. uSync imports 555+ content types, 666 data types, 142 dictionary items, and 36 templates
5. Site is ready — no manual Umbraco setup needed

---

Customizing Your Client

CSS Theme

Edit src/MyCreditUnion/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 for full details.

How Views and Assets Work

After dotnet build, 301 baseline Razor views and 2,400+ static assets (CSS, JS, vendor libraries) are physically present in your project's Views/ and wwwroot/ folders. They are copied from the Progress.Baseline.Web NuGet package by a .targets file that runs during build.

Key behaviour:

• First build: All baseline files are copied to your project
• Subsequent builds: Only new files (added in newer package versions) are copied. Existing files are never overwritten.
• Your customisations are safe: Once you edit a view or asset and commit to git, no NuGet update will overwrite it
• To reset a file to baseline: Delete it from your project and rebuild — the .targets will re-copy the original

To customise a view, simply edit it directly in your Views/ folder and commit the change to git.

# Check what views you've customised vs baseline
git diff -- Views/

# Reset a specific view to baseline (delete and rebuild)
rm Views/Partials/SiteLayout/footer.cshtml
dotnet build

Upgrading NuGet packages

When you update Progress.Baseline.Web to a newer version and rebuild, only files that don't exist on disk are copied. Your customised views are untouched. Check git status after upgrading to see if any new files were added by the update.

Configuration

Environment-specific settings use the standard ASP.NET Core pattern:

File	When loaded	Purpose
appsettings.json	Always	Base config (Umbraco, uSync, notifications)
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 (contains local connection strings). Production credentials should be injected via environment variables or Key Vault, not committed to the repository.

---

Global Notifications

The platform includes a global notifications banner that displays important messages to site visitors — for example, "Online banking is under maintenance" or "Branch closed due to weather".

Notifications are managed centrally via Umbraco Heartcore (a cloud headless CMS) and filtered per client based on:

• Country — only show notifications relevant to that country
• County — only show notifications for that region
• CU Name — show notifications targeted at a specific credit union

The --Country and --County template parameters configure which notifications your site receives. If your credit union doesn't use this feature, the default values are fine.

---

Building for Deployment

docker build -t mycu:latest --build-arg ASPNETCORE_ENVIRONMENT=mycu --build-arg CONFIGURATION=Release .

See the Azure Hosting Guide and Docker Guide for full deployment instructions.

---

NuGet Packages

The template references these shared packages from the private NuGet feed:

Package	Description
Progress.Baseline.Core	Shared services, interfaces, DI registration, URL rewriting, security middleware
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

NuGet Feed Access

The template's nuget.config is pre-configured to pull Progress.* packages from the Azure Artifacts feed (https://pkgs.dev.azure.com/ProgressSystemsLtd/CUCloud.Web/_packaging/CUCloud-Web-Packages/nuget/v3/index.json). Authentication requires Azure AD credentials (see the Azure Artifacts Authentication note above).

---

Troubleshooting

NuGet restore fails with 'package not found'

Check that nuget.config points to the correct Azure Artifacts feed URL and the package source mapping includes Progress.* for the private feed. Ensure the Azure Artifacts credential provider is installed (see Step 4).

SQL Server connection refused

Ensure Docker is running and the SQL container is started: docker ps | grep progress-sql. If not running: docker start progress-sql.

Port 1433 already in use

Another SQL Server instance is using the port. Either stop it, or use a different port: change -p 1433:1433 to -p 1434:1433 in the Docker command, then use --DbServer "localhost,1434" in the template.

Umbraco shows 'Install' screen instead of auto-installing

Check that Umbraco:CMS:Unattended:InstallUnattended is true in appsettings.json and the database connection string is correct and the database exists.

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 NuGet package into your Views/ folder. If your Views/ folder only contains _ViewImports.cshtml, the build hasn't run yet.

CSS theme not applied

The site stylesheet is loaded from the siteStyleSheet property in Umbraco's Website Configuration content node. Set ASPNETCORE_ENVIRONMENT to your client slug so the correct appsettings file is loaded.