Встановлення та налаштування Umbraco (.NET)

Встановлення та налаштування Umbraco (.NET)

Umbraco 13/14 працює на .NET 8. Встановлюється через dotnet CLI або шаблон у Visual Studio. База даних — SQL Server (продакшн) або SQLite (розробка). Потребує знайомства з ASP.NET Core — це не PHP-рушій, який розгортається за п'ять хвилин.

Системні вимоги

• .NET 8 SDK
• SQL Server 2019+, SQL Server Express або SQLite
• IIS 10+ / Kestrel / nginx як reverse proxy
• Windows Server 2019+ або Linux (Ubuntu 20.04+)

Встановлення через CLI

# встановити шаблони Umbraco
dotnet new install Umbraco.Templates

# новий проект
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

# запуск
dotnet run

Для SQL Server замість SQLite:

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

Структура appsettings.json

{
  "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

<!-- 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 як 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-сервісу (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

Конфігурація логування

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

Обновлення Umbraco

# оновити пакет
dotnet add package Umbraco.Cms --version 13.x.x

# запустити миграції — автоматично при старті
dotnet run

# або через CLI Umbraco
dotnet umbraco migrate

Umbraco виконує міграції схеми БД при старті додатка. В продакшені рекомендується запустити migration окремо перед змною кода.

Резервне копіювання

Для SQL Server:

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

Плюс синхронізація папки wwwroot/media/ — там зберігаються завантажені файли.

Терміни розробки

Встановлення на VPS з Nginx та SQL Server, налаштування backoffice та першого адміністратора: 1 день. З SSL, systemd-сервісом, налаштуванням бэкапів та базовими типами контенту: 2–3 дні.