Nucleus .Net Core CMS

Hosting in Linux

NOTE: We have created a shell script to automate many of the steps. This page describes the use of the shell script. This process has been tested with Ubuntu Server 22.04. The script will configure an instance of Nucleus which uses a Sqlite database. After you have completed basic installation, you can configure Nucleus to use a different database type.

Linux Installation

Set up your Linux environment. There are many options for setting up Linux, including:

Nucleus Installation

  1. Connect to a SSH or terminal session.
    Once you have installed Linux, log in as an admin user. If you are using a PC or Raspberry Pi, you may need to connect a keyboard and monitor to your machine in order to see its IP address. If the IP address is not displayed automatically, you can log in and view the IP address by using the hostname -I command.

    If you have configured SSH or are using a virtual machine, you can use SSH to connect from another computer:
    ssh your-admin-username@linux-machine-name-or-ip-address

  2. Create a temporary directory in the root user's home directory for Nucleus installation assets and navigate to it:
    mkdir nucleus-install-files
    cd nucleus-install-files

  3. Download the installer shell script and installation file:
    wget >
    wget >

    If you are installing a later version of Nucleus, download the zip file for that version instead - the installer shell script automatically checks the folder which contains the shell script for the zip file with the most recent version of Nucleus. Download the latest Nucleus version

  4. Run the installer shell script:
    sudo bash ./

    The installation shell script creates a user named nucleus-service, installs the ASP.NET Core 6 runtime, unzip package and Nucleus, then copies the application settings template with settings for Linux, sets file system object ownership and permissions and configures systemd to automatically start, monitor and restart Nucleus. The nucleus-service user is used to run Nucleus, and does not have a password or a shell configured, so you can't log in as this user.

    TIP: If you are installing to a Linux distribution other than Ubuntu Linux, some parts of the shell script may not work, because different Linux distributions use different commands to install packages. In most cases, you can work around this issue by installing the ASP.NET runtime and unzip package before running the script:

Shell script command-line options

For a fresh install you will not generally need to specify any command-line options.

-u, --createuser Use --createuser false to prevent the nucleus-service user from being created. You should only use this option if the user has already been created.
-d, --createdirectories Use --createdirectories false to prevent creation of the /home/nucleus, /home/nucleus/app and /home/nucleus/data directories. This also prevents the commands which set the correct owner and permissions to directories.
-z, --zipfile Override auto-detection of the Nucleus install zip file name and specify the file to use.
-t, --target-directory Override the default application path (/home/nucleus). If used in combination with --createuser true (the default), the specified directory will be assigned as the user's home directory.

sudo bash ./ --zipfile --target-directory /home/services/nucleus-production

  1. Test your installation.
    Use a device with a web browser to test your site. You will need the IP address of your server, or its host name. By default, Nucleus is configured to use http on port 5000.

You should see the Nucleus setup wizard, which performs file system access checks, prompts you to set your site properties and administrator users and creates your new site.

Extended configuration

Configure your database provider

You can leave the default settings as-is to use Sqlite, or configure Nucleus to use a different database type.

If your Nucleus instance is for testing or development, or is an embedded IOT web server or small web application or site, Sqlite is a good choice. For larger production web applications and sites, you should consider using Microsoft SQL Server, MySql or PostgreSql.

Set up a reverse proxy (optional)

Depending on your environment and objectives, you may need to configure a reverse proxy server. Refer to 'When to use Kestrel with a reverse proxy' for more information.
You can set up Nginx, Kubernetes, Apache or another reverse proxy.

See also: Nginx Walkthrough

If you don't want to use a reverse proxy, you can use Nucleus with the default ports (http: 5000, https: 5001), or you can configure Nucleus to run Kestrel using different ports (8080/8443) by editing /home/nucleus/appSettings.Production.json.

sudo nano /home/nucleus/app/appSettings.Production.json

Locate the Kestrel section, and set the port for the Http endpoint and Https endpoints.

NOTE: Linux will not let you use port numbers less than 1024, because only the root user can use those ports. Use a reverse proxy if you want to use the conventional web server ports 80 and 443.

Set up a certificate and configure https

Create a self-signed Certificate

This command will create a self-signed certficate with no subject defined. A self-signed certificate is useful in a testing or development environment, but is not useful for a production environment, because your browser will display a security warning. When you browse to your site, you will have to ignore or disable security warnings, or "trust" the certificate in your browser, as it is not issued by a recognized certification authority.

sudo openssl req -nodes -new -keyout nucleus.key -x509 -days 365 -out nucleus.crt -subj "/"

sudo chown :nucleus-service nucleus.key nucleus.crt
sudo chmod g+rw nucleus.key nucleus.crt
sudo cp nucleus.crt /home/nucleus/certs
sudo cp nucleus.key /home/nucleus/certs

Configure Nucleus to use the certificate

If you are using a reverse proxy, you will generally want to configure the reverse proxy to use your certificate and manage ("terminate") SSL connections, so you won't need to configure Nucleus for https, and can skip this section.

If you will be running Nucleus without a reverse proxy, configure https and certificate settings with:

sudo nano /home/nucleus/app/appSettings.Production.json

Add or un-comment the following setting in Kestrel:Endpoints section. In the default Linux settings template, the section is already present (commented out), so you can just un-comment the section and fill in the password:

  "HttpsInlineCertAndKeyFile": {
    "Url": "https://*:5001",  // or "https://your-hostname:5001" if you want to specify a host name
    "Certificate": {
      "Path": "/home/nucleus/certs/nucleus.crt",
      "KeyPath": "/home/nucleus/certs/nucleus.key",
      "Password": "your-certificate password"


Nginx Walkthrough

Follow the steps in this section if you want to install and configure Nginx as a reverse proxy.

sudo apt install nginx

Create configuration file:
sudo nano /etc/nginx/sites-enabled/nucleus

Insert these settings. If you have not created a certificate, omit or comment out the two listen commands which refer to port 443, and the two ssl_certificate lines:

server {
    listen        80;
    listen        443 ssl default_server;
    listen        [::]:443 ssl default_server;
    ssl_certificate     /home/nucleus/certs/nucleus.crt;
    ssl_certificate_key /home/nucleus/certs/nucleus.key;

    server_name _;

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

To comment out a line, add # to the start of the line.

Remove the default configuration file:
sudo rm /etc/nginx/sites-enabled/default

Restart nginx:
sudo systemctl restart nginx

At this point, Nginx is configured to listen on port 80 (and/or 443 if you have created a certificate), and will communicate with Nucleus on the local machine/port 5000.

Configure a firewall

Allow SSH connections:
sudo ufw allow "OpenSSH"

Allow http and https connections:

  • If you are using a reverse proxy (like Nginx) which listens on ports 80/433:
    sudo ufw allow proto tcp from any to any port 80,443

  • If you are using Kestrel (no reverse proxy), which listens on ports 5000/5001 by default:
    sudo ufw allow proto tcp from any to any port 5000,5001

Allow FTP:
sudo ufw allow 22

Enable firewall on next boot:
sudo ufw enable

Review settings:
sudo ufw status

Restart to enable the firewall:
sudo shutdown -r now


If you are not able to access Nucleus using your browser, you can try the following steps.

  1. Check service status.
    systemctl status nucleus

  2. Check service logs.
    journalctl -xeu nucleus

  3. Check the Nucleus error log.
    Navigate to the Nucleus log folder:
    cd /home/nucleus/data/logs
    then list the contents:
    Choose today's log - log filenames use UTC dates, so the file name might not match your local time zone - then open the log file in an editor:
    nano 14-Dec-2022 UTC_MYCOMPUTER.log.

  4. Try running Nucleus interactively.
    First, you will need to configure the nucleus-service user to allow logins.
    sudo passwd nucleus-service
    sudo usermod --shell /bin/bash nucleus-service

    Then, login as the nucleus-service user and try running Nucleus interactively. Log messages will be displayed on-screen.
    cd /home/nucleus/app
    sudo systemctl stop nucleus
    /usr/share/dotnet/dotnet Nucleus.Web.dll

    After you have finished troubleshooting, you can disable login for the Nucleus service user with:
    sudo passwd --delete nucleus-service
    sudo usermod --shell /usr/sbin/nologin nucleus-service