Umbraco .NET Installation and Setup

Installation and Setup of Umbraco (.NET)

Umbraco 13/14 runs on .NET 8. Installed via dotnet CLI or Visual Studio template. Database is SQL Server (production) or SQLite (development). Requires ASP.NET Core knowledge — not PHP engine launched in five minutes.

System Requirements

• .NET 8 SDK
• SQL Server 2019+, SQL Server Express or SQLite
• IIS 10+ / Kestrel / nginx as reverse proxy
• Windows Server 2019+ or Linux (Ubuntu 20.04+)

Installation via CLI

# install Umbraco templates
dotnet new install Umbraco.Templates

# new project
dotnet new umbraco -n MyProject --friendly-name "Admin" \
  --email [email protected] \
  --password "P@ssw0rd123" \
  --connection-string "Data Source=|DataDirectory|/Umbraco.sqlite.db;Cache=Shared;Foreign Keys=True;Multithread Safety=True"

cd MyProject

# run
dotnet run

For SQL Server instead of SQLite:

dotnet new umbraco -n MyProject \
  --connection-string "Server=localhost;Database=UmbracoDb;Trusted_Connection=True;TrustServerCertificate=True"

appsettings.json Structure

{
  "ConnectionStrings": {
    "umbracoDbDSN": "Server=srv;Database=UmbracoDb;User=sa;Password=secret;TrustServerCertificate=True",
    "umbracoDbDSN_ProviderName": "Microsoft.Data.SqlClient"
  },
  "Umbraco": {
    "CMS": {
      "Global": {
        "Id": "b9c6e1a1-0000-4000-8000-000000000001",
        "SendVersionCheckResult": false,
        "UseHttps": true,
        "ReservedPaths": "~/.well-known",
        "MainDomLock": "FileSystemMainDomLock"
      },
      "Security": {
        "AllowPasswordReset": true,
        "AuthCookieName": "UMB_UCONTEXT",
        "UsernameIsEmail": true,
        "UserPassword": {
          "RequireDigit": true,
          "RequireLowercase": true,
          "RequireNonLetterOrDigit": false,
          "RequireUppercase": true,
          "RequiredLength": 10
        }
      },
      "Content": {
        "AllowedUploadFiles": ["jpg", "jpeg", "png", "gif", "webp", "svg", "pdf", "docx"],
        "MaximumAllowedUploadSizeInBytes": 10485760,
        "ResolveUrlsFromTextString": false
      },
      "DeliveryApi": {
        "Enabled": true,
        "ApiKey": "your-secret-key-here"
      }
    }
  }
}

IIS Setup

<!-- web.config -->
<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*"
             modules="AspNetCoreModuleV2"
             resourceType="Unspecified" />
      </handlers>
      <aspNetCore
        processPath="dotnet"
        arguments=".\MyProject.dll"
        stdoutLogEnabled="false"
        stdoutLogFile=".\logs\stdout"
        hostingModel="inprocess">
        <environmentVariables>
          <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Production" />
        </environmentVariables>
      </aspNetCore>
    </system.webServer>
  </location>
</configuration>

Nginx as Reverse Proxy

server {
    listen 443 ssl http2;
    server_name mysite.com;

    ssl_certificate     /etc/letsencrypt/live/mysite.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mysite.com/privkey.pem;

    client_max_body_size 20M;

    location / {
        proxy_pass         http://127.0.0.1:5000;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection keep-alive;
        proxy_set_header   Host $host;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }

    location /media/ {
        alias /var/www/mysite/wwwroot/media/;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
}

systemd Service Setup (Linux)

# /etc/systemd/system/mysite.service
[Unit]
Description=MyProject Umbraco site
After=network.target

[Service]
WorkingDirectory=/var/www/mysite
ExecStart=/usr/bin/dotnet /var/www/mysite/MyProject.dll
Restart=always
RestartSec=10
KillSignal=SIGINT
SyslogIdentifier=mysite
User=www-data
Environment=ASPNETCORE_ENVIRONMENT=Production
Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false

[Install]
WantedBy=multi-user.target

systemctl enable mysite
systemctl start mysite
systemctl status mysite

Logging Configuration

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Warning",
      "Override": {
        "Microsoft": "Warning",
        "Umbraco": "Warning"
      }
    },
    "WriteTo": [
      {
        "Name": "File",
        "Args": {
          "path": "umbraco/Logs/UmbracoTraceLog.txt",
          "rollingInterval": "Day",
          "retainedFileCountLimit": 14
        }
      }
    ]
  }
}

Update Umbraco

# update package
dotnet add package Umbraco.Cms --version 13.x.x

# run migrations — automatically on startup
dotnet run

# or via Umbraco CLI
dotnet umbraco migrate

Umbraco executes DB schema migrations on app start. In production, recommend running migrations separately before code swap.

Backup

For SQL Server:

BACKUP DATABASE [UmbracoDb]
TO DISK = N'D:\Backups\UmbracoDb_20240315.bak'
WITH NOFORMAT, NOINIT, NAME = 'UmbracoDb-Full',
     SKIP, NOREWIND, NOUNLOAD, STATS = 10;

Plus sync wwwroot/media/ — uploaded files stored there.

Development Timelines

Setup on VPS with Nginx and SQL Server, backoffice and first admin: 1 day. With SSL, systemd service, backup config and basic content types: 2–3 days.