FlashPanel

Deploy an ASP.NET application ​

Suppose you have an ASP.NET Core application that you want to run under the domain domain.com. The application runs on Kestrel at port 3000 and is managed by a Systemd Service, while the website on FlashPanel forwards requests for the domain to port 3000.

Prerequisites ​

  • Server connected to FlashPanel
  • Domain DNS pointed to the server's IP

Step 1: Install the .NET SDK ​

Go to the server management page, click the Apps menu, select the Not Installed tab, find ASP.NET Core, then click Install. Choose the Version that matches your project's .NET version (for example, choose 8.0 for a project targeting net8.0). See Applications for details.

Step 2: Create a Website ​

  1. Go to the server management page, click the Sites menu in the sidebar, then click the New Site button
  2. Enter the Domain Name (e.g., domain.com)
  3. Enter the Proxy Port: the port your application will listen on, for example 3000
  4. Click Create Site

TIP

If you enable Website Isolation, the website runs as its own Linux user. In that case, replace flashpanel in the paths below with the website's isolation username.

Step 3: Upload the Source Code ​

Choose one of the following:

  • From Git (recommended): on the site management page, click the Install Source Code menu and install your repository. See Source Code Installation.
  • Upload it yourself: open File Manager on the website's overview page and upload your code to the website directory. See File Manager.

The source code lives in /home/flashpanel/domain.com.

Step 4: Build and Publish ​

Open Terminal on the website's overview page (the terminal logs in as the user that owns the website and opens the website directory), then run:

bash
cd /home/flashpanel/domain.com

# Update the database (only when using Entity Framework Core migrations)
dotnet ef database update

# Build and publish the Release version to the publish directory
dotnet publish -c Release -o publish

After this command, the main file is publish/<ProjectName>.dll, for example publish/domain_com.dll.

TIP

dotnet ef database update is only needed if your application uses Entity Framework Core and the dotnet-ef tool is installed (dotnet tool install --global dotnet-ef). Skip it if your application does not use database migrations.

Step 5: Create a Service for the Application ​

Use the Systemd Service management feature to run the application in the background and restart it automatically:

  1. Go to the server management page, click the Service menu, then click Create Service
  2. Enter a Name, for example domain_com (short, without special characters)
  3. Replace the content in the editor with the following:
ini
[Unit]
Description=ASP.NET - domain.com

[Service]
WorkingDirectory=/home/flashpanel/domain.com/publish
ExecStart=/usr/bin/dotnet /home/flashpanel/domain.com/publish/domain_com.dll --urls "http://127.0.0.1:3000"
Restart=always
RestartSec=10
KillSignal=SIGINT
SyslogIdentifier=domain_com
User=flashpanel
Environment=ASPNETCORE_ENVIRONMENT=Production
Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false
StandardOutput=append:/var/log/services/domain_com.log
StandardError=append:/var/log/services/domain_com-error.log

[Install]
WantedBy=multi-user.target
  1. Keep Boot with the system selected so the service starts when the server reboots
  2. Click Create Service. The service is created and started right away

WARNING

  • Replace 3000 with the website's Proxy Port. 127.0.0.1 makes the application accept requests only through the website, without exposing the port to the Internet
  • Replace domain.com with your website's domain and domain_com.dll with your project's dll file name
  • User is the user that owns the website (do not use root)
  • Linux file names are case-sensitive. With ASPNETCORE_ENVIRONMENT=Production, the application reads appsettings.Production.json, not appsettings.production.json
  • Environment variable names do not support the colon (:). Use a double underscore (__) instead; for example, the key ConnectionStrings:DefaultConnection is declared as:
    ini
    Environment=ConnectionStrings__DefaultConnection={Connection String}

Step 6: Install SSL ​

On the site management page, click the SSL menu and install a certificate for the domain. See SSL.

Verify the Result ​

  1. On the Service page, the domain_com service shows as active
  2. Visit https://domain.com and check that your application responds correctly

Updating the Application ​

  1. Update the source code (click Deploy Now in the Deployments menu if it was installed from Git, or upload the new version with File Manager)
  2. Open the website's Terminal and run dotnet publish -c Release -o publish again
  3. On the Service page, click the Restart button of the domain_com service

TIP

If the source code was installed from Git, you can add dotnet publish -c Release -o publish to the Deployment Script so you do not have to run step 2 by hand. The Deployment Script runs as the user that owns the website, so it cannot restart a Systemd Service; you still need to click Restart on the Service page.

Troubleshooting ​

Application Won't Start ​

  1. On the Service page, click View Error Log for the domain_com service
  2. Run the application manually in the website directory to see the error: dotnet publish/domain_com.dll --urls "http://127.0.0.1:3000"
  3. Check that the dll path in ExecStart is correct

502 Bad Gateway ​

  1. Check that the service is running on the Service page
  2. Make sure the port in --urls matches the website's Proxy Port
  3. See also 502 Bad Gateway

You must install or update .NET to run this application ​

The installed .NET version does not match the version your project targets. Run dotnet --list-runtimes to see the installed versions, then install the right version on the Apps page.