uTPro Sandbox (SQLite default)

A ready-to-run demo of uTPro that runs on SQLite instead of SQL Server, so you can try the full uTPro site on Windows, macOS or Linux without installing a database server.

Instead of building from source, the launcher downloads the pre-built publish asset from the latest stable uTPro GitHub release (publish_output*.zip), asks a few optional configuration questions, points it at a database (SQLite by default), and runs it. No .NET SDK and no build step are required - only the .NET 10 runtime (which the launcher installs locally if it is missing).

Requires .NET 10. uTPro is moving to Umbraco 17 on .NET 10, so the launcher requires a .NET 10 runtime. While the current release still targets .NET 9, it runs on the .NET 10 runtime automatically via DOTNET_ROLL_FORWARD=Major.

---

Prerequisites

The launcher takes care of the .NET runtime for you; you only need the basics:

Platform	Needs	Notes
All	Git	To clone the repo.
All	.NET 10 runtime	Auto-installed into .dotnet/ if missing (no admin rights needed).
Windows	PowerShell + curl	Both ship with Windows 10/11.
macOS / Linux	curl + unzip (or tar)	Usually pre-installed; install via your package manager if not.

Internet access is required on the first run to download the uTPro release and, if needed, the .NET runtime.

---

Quick start (one click)

Windows

git clone https://github.com/T4VN/uTPro.Sandbox.SQLite.git
cd uTPro.Sandbox.SQLite\win
run.cmd

macOS / Linux

git clone https://github.com/T4VN/uTPro.Sandbox.SQLite.git
cd uTPro.Sandbox.SQLite/linux-macos
chmod +x run.sh
./run.sh

On the first run the launcher asks a few questions (see Configuration). Press Enter on every question to accept the safe defaults (SQLite, localhost, no SMTP, manual install wizard). Your answers are saved so later runs never ask again.

Then open http://localhost:5000/umbraco. If you did not set up an admin automatically, complete the first-time install wizard; uTPro's uSync content is imported on first boot.

The second time you run the script it reuses your saved configuration and the existing publish/ output and just starts the website again (no questions, no re-download).

---

What the launcher does

Step	Action
1	Ensures the .NET 10 runtime (ASP.NET Core 10.0+) is available; installs one locally into .dotnet/ if not.
2	Loads your saved config (or asks the questions the first time), downloads the latest release publish_output*.zip, extracts it into publish/, generates appsettings.Production.json from your answers and creates an empty SQLite database file.
3	Runs dotnet uTPro.Project.Web.dll from publish/ at http://localhost:5000.

---

Configuration

On the first run the launcher asks the questions below and saves the answers to sandbox.config (macOS/Linux) or sandbox.config.json (Windows). Leave any answer blank to keep the default. To change them later, run run.cmd reconfigure / ./run.sh reconfigure or just delete the config file.

Question	Default	Effect
Database connection string	blank -> local SQLite	Any value switches uTPro to that database (you are also asked for the provider, default Microsoft.Data.SqlClient).
Use custom local domains?	No -> localhost	If yes, you enter a website URL (utpro.local) and backoffice URL (bo.utpro.local); the launcher enables uTPro's backoffice domain and adds the names to your hosts file (needs admin/sudo, otherwise it prints the lines to add).
Configure SMTP?	No -> empty	If yes, you enter host / port / from / username / password; written to Umbraco:CMS:Global:Smtp.
Create the backoffice admin automatically?	No -> install wizard	If yes, you enter name / email / password; the launcher enables Umbraco unattended install so the admin and schema are created on first boot with no wizard.

The launcher turns those answers into publish/appsettings.Production.json, which ASP.NET Core merges over the release's own appsettings.json. A default (all-blank) run produces:

{
  "ConnectionStrings": {
    "umbracoDbDSN": "Data Source=<abs>/publish/umbraco/Data/Umbraco.sqlite.db;Cache=Shared;Foreign Keys=True;Pooling=True",
    "umbracoDbDSN_ProviderName": "Microsoft.Data.Sqlite"
  },
  "uTPro":  { "Backoffice": { "Enabled": false } },
  "Umbraco": { "CMS": { "Runtime": { "Mode": "Development" } } }
}

• Backoffice:Enabled = false keeps the backoffice on localhost (the release ships with a bo.utpro.local domain); it is enabled with your URL only if you opt into custom domains.
• Runtime:Mode = Development - the release runs in Production mode, which refuses to boot without a configured application URL; Development relaxes that for a local demo.

An empty SQLite file is created up front because Umbraco's start-up database probe opens the file read-only and would otherwise report a boot failure instead of reaching install.

---

Files

The launcher scripts are grouped by platform; all generated files live at the repo root, no matter which platform folder you launch from.

uTPro.Sandbox.SQLite/
├── win/                 # Windows: run.cmd, uninstall.cmd, prepare.ps1
├── linux-macos/         # macOS/Linux: run.sh, uninstall.sh
├── README.md
├── .gitignore
└── (generated at run time, git-ignored: publish/  .dotnet/  sandbox.config*)

Path	Purpose
win/run.cmd / linux-macos/run.sh	One-click launchers for Windows / macOS / Linux.
win/uninstall.cmd / linux-macos/uninstall.sh	Stop the site and delete all generated files (back to a clean git state).
win/prepare.ps1	Windows-only helper (called by run.cmd): runs the config wizard, downloads + extracts the release, generates appsettings.Production.json, creates the empty database. run.sh re-implements the same logic inline in bash, so macOS/Linux do not need it.
sandbox.config / sandbox.config.json	Your saved answers, at the repo root (git-ignored; may contain passwords).
publish/	Downloaded release output at the repo root (git-ignored, created at run time).
.dotnet/	Locally installed .NET runtime at the repo root, if the launcher had to fetch one (git-ignored).

---

What you can do in this quickstart

This sandbox runs the pre-built uTPro release (no compiler on the machine), which keeps it fast to start. That means:

• ✅ Browse and edit content, media, and settings in the backoffice.
• ✅ Edit existing templates / views (.cshtml) right in the backoffice - changes are recompiled at runtime (thanks to Runtime:Mode=Development), no rebuild needed.
• ✅ All existing document types already have their strongly-typed models compiled into the shipped assemblies, so the existing site renders normally.
• ⚠️ Creating a brand-new document type works, but it won't get a strongly-typed ModelsBuilder model (the release runs ModelsMode=Nothing and there is no SDK to regenerate/compile one). Templates for new types can still use dynamic access such as Model.Value("alias"). Full typed-model + document-type development needs the source + .NET SDK build flow, which is outside the scope of this quickstart.

---

Updating to a newer uTPro release

The launcher records which release it installed in a marker file (publish/.utpro-release). On every run it asks GitHub for the latest release tag and compares it with the installed one:

• First run - downloads the latest release and stamps the version.

• Same version - just starts the existing site (no download).

• Newer version available - shows the installed vs. latest version and asks what to do:

  Choice	Action	Your data
  [1] Update and RESET	Uninstalls the old version and installs the latest as a clean install. Asks for confirmation first.	⚠️ Deleted (database + media)
  [2] Keep current version (default)	Skips the update and runs the version you already have.	✅ Kept
  [3] Update and KEEP data	Installs the latest release but preserves your existing database and uploaded media.	✅ Kept

If GitHub can't be reached (offline), the launcher skips the check and runs the existing publish/ output.

The data preserved by choice [3] (and wiped by [1]) is: publish/umbraco/Data (the SQLite database) and any media under publish/wwwroot/media or publish/media.

You can still force a fully clean re-download at any time by deleting the output and running again:

rm -rf publish        # Windows: delete the "publish" folder

---

Uninstall / clean up

To stop the site and remove everything the launcher generated (returning the folder to its clean checked-in state), run the uninstall script:

Windows

cd win
uninstall.cmd          REM add -y to skip the confirmation prompt

macOS / Linux

cd linux-macos
./uninstall.sh         # add -y to skip the confirmation prompt

It stops the running uTPro process and deletes publish/, .dotnet/, the saved sandbox.config / sandbox.config.json and any downloaded archives (all at the repo root). Only the checked-in files remain, so git status is clean afterwards. Run the launcher again to set it back up.

---

Notes & limitations

• SQLite is intended for evaluation / demo / development, not production. It does not handle high write-concurrency well (you may hit database is locked under load).
• The first boot takes longer while Umbraco creates the schema and uSync imports content.
• To reset the demo completely, delete the publish/ folder (and the config file to be asked the questions again) and run the launcher again.
• The launcher runs uTPro's own published host (uTPro.Project.Web.dll); the only changes applied are in the generated appsettings.Production.json described under Configuration.

---

Troubleshooting

Symptom	Fix
Port 5000 already in use	Edit APP_URL at the top of win\run.cmd / linux-macos/run.sh to another port (e.g. http://localhost:5080).
run.sh: Permission denied	Run chmod +x linux-macos/run.sh first.
Download is slow or interrupted	Just re-run the launcher to retry. It only skips downloading once publish/ contains a complete extract; an interrupted download is re-attempted from the start.
"unzip: command not found" (Linux)	Install it, e.g. sudo apt-get install unzip (Debian/Ubuntu) or sudo dnf install unzip (Fedora).
Backoffice login won't load	Make sure you open http://localhost:5000/umbraco (not a custom domain); the overlay already disables uTPro's bo.utpro.local domain.
Change your answers	Run run.cmd reconfigure / ./run.sh reconfigure from the platform folder, or delete the sandbox.config / sandbox.config.json file at the repo root.
Reset the demo	Delete the publish/ folder and run the launcher again.
Update to a newer release	Just run the launcher; if a newer release exists it offers to update (keeping or resetting your data). See Updating to a newer uTPro release.