Deployment

This guide covers publishing an EasyAdminBlazor project to production, with a focus on Nginx reverse proxy (WebSocket is required for Blazor Server), HTTPS, Windows hosting, and a go-live checklist.

1. Publish the Project

Run this in the project root:

dotnet publish -c Release -o publish

Copy the whole publish folder to the server. The output includes runtime files, so the server does not need the .NET SDK — but it does need the matching .NET 10 Runtime (for IIS hosting on Windows, install the ASP.NET Core Hosting Bundle as well).

2. Production Configuration

Environment variable

Set ASPNETCORE_ENVIRONMENT=Production. The framework will load appsettings.Production.json and override development settings.

Database and automatic schema sync

• During development, UseAutoSyncStructure(true) syncs the schema automatically. Set it to false in production so the app never alters the production schema unexpectedly at startup.
• For the first release, sync the schema on a development database first. If you really need auto-create, enable it temporarily and disable it once everything works.
• For MySQL, use Charset=utf8mb4 in the connection string to avoid garbled Chinese text.
• Keep database passwords out of the repository; override them with environment variables or a secrets manager.

Keys and security

• Change AdminRouteSecret: it is the secret for the admin entry. Replace it with your own value before going live.
• Change AesKey: used for cookie encryption. Replace it before going live (existing sessions will be invalidated, which is expected).
• Change the default admin password: the template ships with admin / 123yyq. Change it immediately after the first login.

3. Nginx Reverse Proxy (Recommended)

Blazor Server relies on WebSocket long connections, so Nginx must pass the Upgrade headers or pages will disconnect and reconnect constantly:

server {
    listen 80;
    server_name admin.example.com;

    location / {
        proxy_pass http://127.0.0.1:5207;   # change the port to the actual listening port
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;            # keep Blazor Server connections alive
    }
}

Notes:

• Program.cs already calls app.UseForwardedHeaders; forwarding X-Forwarded-Proto keeps HTTPS callback URLs and login redirects correct
• Use Let's Encrypt (certbot) or a cloud certificate, and redirect port 80 to 443
• Multi-tenant resolves tenants by domain, so the reverse proxy must pass the original Host header, or every request will be treated as the same tenant

4. Hosting on Windows

IIS

1. Install the ASP.NET Core Hosting Bundle
2. Enable the IIS WebSocket Protocol (Blazor Server relies on WebSocket long connections; without it, admin pages keep reconnecting/reloading):
   • Windows Server: Server Manager → Add Roles and Features → Web Server (IIS) → Application Development → check "WebSocket Protocol"; or run Install-WindowsFeature Web-WebSockets in an elevated PowerShell
   • Windows client / standalone IIS: Control Panel → Turn Windows features on or off → IIS → World Wide Web Services → Application Development Features → check "WebSocket Protocol"
   • Run iisreset and restart the application pool after installation
3. Point the site's physical path to the publish folder
4. Set the application pool to "No Managed Code"
5. Grant write permission on wwwroot/uploads

Windows service

Use NSSM or winsw to register dotnet YourApp.dll as a Windows service for auto-start and crash recovery. Grant the service account write permission on the uploads directory.

5. Go-Live Checklist

• AdminRouteSecret and AesKey changed
• Default admin password changed
• UseAutoSyncStructure disabled, or the schema verified on a development database
• HTTPS configured, port 80 redirects to 443
• WebSocket configured in the reverse proxy (Upgrade headers)
• wwwroot/uploads is writable
• Database backed up; connection string uses environment variables
• Log level set to Production (Information or Warning)
• Redis (if used) has a password and is not exposed to the public network
• Multi-tenant domains resolve to the server

6. Common Pitfalls

• Pages disconnect and reconnect constantly: usually the Nginx Upgrade/Connection headers are missing, or proxy_read_timeout is too short
• Admin pages keep reloading/reconnecting on IIS: the IIS WebSocket Protocol feature is not enabled (see the IIS steps above)
• Login redirects become http: the reverse proxy is not forwarding X-Forwarded-Proto, or UseForwardedHeaders is not effective
• File uploads fail: check write permission on wwwroot/uploads and the FileSettings configuration
• Database errors at startup: the production connection string is not applied; confirm the environment variable name matches appsettings.Production.json
• Admin returns 404: AdminRouteSecret changed; visit /admin/{your-new-secret}