Deploying Umbraco

The CMS runs as a systemd service on a Hetzner box, behind Caddy as a reverse proxy with automatic HTTPS. This page covers server access, the build and publish pipeline, and the one-time setup of each component.

Note

This is the direction, not a finished state. The Hetzner server is not fully set up yet. Treat the commands below as the intended procedure and expect to correct them as the server is built out — several known gaps are flagged inline.

For this documentation site’s own deploy, see Deploying the docs site.

Access

Host	2a01:4ff:f0:8c5f::1 (IPv6)
Login	root
Provider	Hetzner

ssh -6 root@2a01:4ff:f0:8c5f::1

The -6 is required — the address is IPv6.

Who has access

	Who
Hetzner account	Mark Drake, Robin Alston
SSH key to the server	Mark Drake

Anyone with Hetzner account access can generate additional SSH keys. Keys are only needed by engineers who require direct access to the server or the database — upgrades and routine maintenance. Deploying does not otherwise require console access beyond the rsync push.

Danger

One person currently holds the only SSH key. If that key is lost, server access has to be recovered through the Hetzner console, which is a slower path. Issuing a second key to another engineer is worth doing before it is needed.

Never commit a private key, and never paste one into these docs. The server address above is fine to record; the key is not.

Routine security updates

Download and apply security updates only:

sudo apt update
sudo apt-get upgrade -o APT::Get::Only-Source=security

A reboot is required if this file exists:

cat /var/run/reboot-required

If so:

sudo reboot

.NET runtime

Umbraco 17 targets .NET 10.

sudo apt update
sudo apt install -y aspnetcore-runtime-10.0

To upgrade later:

sudo apt update
sudo apt install --only-upgrade aspnetcore-runtime-10.0

Caution

Install aspnetcore-runtime-10.0, not dotnet-runtime-10.0. The plain runtime does not include the Microsoft.AspNetCore.App shared framework, so the app fails at startup with “The framework ‘Microsoft.AspNetCore.App’ was not found”. Installing the ASP.NET Core runtime pulls the base runtime in as a dependency, so it is the only package needed.

Build and publish

1. Build the client bundles first

cd src/NRI.CMS/Client
npm run release

Danger

This step is not optional and nothing else performs it. NRI.CMS.csproj:143 copies Ssr/** into the publish output, but there is no MSBuild target that builds it, and Ssr/ is gitignored (.gitignore:432) so it never arrives via a checkout. Publishing without running npm run release first ships a stale or missing SSR tree, and the site throws Unknown Svelte island "<Name>" at runtime. Static islands have no client-side fallback, so the content breaks outright rather than degrading.

npm run release runs both builds: the browser client into wwwroot/client and the SSR tree into ../Ssr.

2. Publish from your local machine

dotnet publish -c Release -r linux-x64 --no-self-contained /p:UseAppHost=false -o ./publish

3. Push to the server

rsync -av --delete -e "ssh -6" \
  --exclude="umbraco/" \
  ./publish/ "root@[2a01:4ff:f0:8c5f::1]:/var/www/nri-cms/"

--exclude="umbraco/" protects the runtime data directories from --delete. The IPv6 literal has to be bracketed for rsync, and -e "ssh -6" forces IPv6 the same way the plain ssh command does.

4. Restart

sudo systemctl restart nri-cms
sudo systemctl reload caddy

One-time server setup

Application directory

sudo mkdir -p /var/www/nri-cms
sudo chown www-data:www-data /var/www/nri-cms

Then protect the data folders, which must survive a deploy:

cd /var/www/nri-cms
sudo mkdir -p umbraco/Logs umbraco/Data
sudo chown -R www-data:www-data umbraco

systemd service

sudo nano /etc/systemd/system/nri-cms.service

/etc/systemd/system/nri-cms.service

[Unit]
Description=NRI Umbraco CMS (.NET 10)
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/nri-cms
ExecStart=/usr/bin/dotnet NRI.CMS.dll --urls "http://localhost:5000"
Restart=always
RestartSec=5
Environment=ASPNETCORE_ENVIRONMENT=Production

[Install]
WantedBy=multi-user.target

Enable and start it:

sudo systemctl daemon-reload
sudo systemctl enable --now nri-cms
sudo systemctl status nri-cms

Caddy

Install:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install -y caddy
sudo systemctl enable --now caddy

Configure:

sudo nano /etc/caddy/Caddyfile

/etc/caddy/Caddyfile

nri-inc.org, www.nri-inc.org {
  reverse_proxy localhost:5000
}

Reload:

sudo systemctl reload caddy

To upgrade Caddy later:

sudo apt update
sudo apt install --only-upgrade caddy
sudo systemctl restart caddy

Note

Caddy sets X-Forwarded-For, X-Forwarded-Proto, and X-Forwarded-Host on proxied requests by default, and preserves the original Host header, so no header_up directives are needed. header_up is a reverse_proxy subdirective in any case — placing it at the site-block level is a config error and Caddy will refuse to load the file.

Open questions

Things this procedure does not yet answer. Worth resolving before the server goes live.

• The other two sites. The Caddyfile above only serves nri-inc.org and www.nri-inc.org. Umbraco hosts three top-level sites — NRI Inc, BHPMS, and State Profiles — each resolved by hostname. The other two need their own site blocks (or additional hostnames on this one) or they will not be reachable.
• The database. Nothing here covers where the Umbraco database lives, how it is backed up, or how connection strings reach the app in Production.
• Secrets. appsettings.Production.json and any user-secrets equivalents are not part of the rsync push. How they get onto the server, and who can rotate them, is undefined.
• Deploy from a build host. Publishing from a local machine works, but ties releases to one person’s laptop being correctly set up — in particular to their having run npm run release first. A build host or CI job would remove that failure mode.

Source

Adapted from Deployment Instructions/Deploy NRI Inc.md in the Compendium Obsidian vault. Corrections applied here — the ASP.NET Core runtime package, the nri-inc / nri-cms directory mismatch, the stray /sla path on the rsync target, and the Caddy header_up placement — should be folded back into that note so the two do not drift.