In this section, we will look at installing MeshCentral on Ubuntu 20.04 LTS. (Other supported versions are very similar.) This is a long term support of Ubuntu freely available for download at https://www.ubuntu.com. Both the desktop and server versions of Ubuntu will work. If this is a remote server and the desktop will not be needed, the server version of Ubuntu can be used and will require fewer resources. This section will describe a way to install MeshCentral in a user’s home folder, however there is a more secure way to do it, see “Increased Security Installation” For more information.

In all cases, MeshCentral must not be installed as root user. It’s not secure and the instructions below will not work correctly.

The first prerequisite is to ensure NodeJS is installed on the system. We will install the node version manager, activate it, then install an LTS version of NodeJS.

sudo add-apt-repository universe
sudo apt update

Now we install nvm (Node Version Manager) - nvm makes keeping NodeJS up to date very simple. It also allows you to run multiple versions of Nodejs side by side, or to roll back in case there are issues with a new version. If you are installing MeshCentral on Ubuntu 18.04, the version of NodeJS included is very out of date, and does not meet the minimum requirements for MeshCentral. So getting nvm going first will avoid a lot of headaches in the future.

Be sure to check the project's Github page for the latest version and adjust the command below as needed - https://github.com/creationix/nvm (I'll also include the usual reminders about piping scripts from the web directly into bash. Take the time to READ the script, ideally you should fully understand what it is doing, and feel confident it isn't doing anything to your system it should not be.)

wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash

You can either close out of your session, then reconnect to start using nvm, or if you are in a hurry, run the commands below to add nvm to the system path, and add nvm to bash completion:

export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"

and now to manually load nvm:

[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

One of the best features of nvm is that it allows you to install and run multiple versions of Nodejs. This can be extremely useful when updating to newer versions, for example. MeshCentral currently only requires Nodejs v10 or higher. I personally recommend running the latest Long Term Support version. Let's take a look and see what versions of Nodejs are currently available via nvm:

nvm ls-remote

The command above should return a list similar to the one shown below. It can be a long list, but notice how it identifies LTS versions for you.

    ...    
        v18.9.0
        v18.9.1
       v18.10.0
       v18.11.0
       v18.12.0   (LTS: Hydrogen)
       v18.12.1   (LTS: Hydrogen)
       v18.13.0   (LTS: Hydrogen)
       v18.14.0   (Latest LTS: Hydrogen)
        v19.0.0
        v19.0.1
        v19.1.0
        v19.2.0
        v19.3.0
        v19.4.0
        v19.5.0
        v19.6.0    ...

Looking at the list above, we will install the most recent LTS version: v18.14.0

nvm install v18.14.0

Since nvm allows for multiple versions of Nodejs to be installed side by side, we are going to go ahead and tell it to use the version we just installed as the default:

nvm alias default v18.14.0

Now we will update npm

npm install npm@latest -g

You can verify the versions of NodeJS and NPM just installed with the following commands:

node -v
npm -v

If you are going to be running a large instance, it is advised to use MongoDB as the database. For smaller instances (100 systems or fewer being managed) the default NeDB can be used instead and you can skip this step. If you do want to use MongoDB it can be installed with the command below:

sudo apt install mongodb -y

In most distributions this will also configure MongoDB to run as a service and start it running for you. We can start the service manually, and enable the service to start automatically in the future with these commands:

sudo systemctl start mongodb
sudo systemctl enable mongodb

We can verify MongoDB is running by entering the MongDB shell like this:

mongo --host 127.0.0.1:27017

Then exit the Mongo shell by pressing CTRL-C.

The database and log files will be created in these locations. This info is useful for making backups of the database.

/var/log/mongodb
/var/lib/mongo

On Linux, as a security feature, ports below 1024 are reserved for processes running as “root” user. In our case, we need MeshCentral to listen/run on ports 80 and 443. To accomplish this, we first need to discover where NodeJS runs from:

which node
node: /usr/bin/node

In this case, the result shows NodeJS binaries are found at /usr/bin/node. We will use this path in the next command, which will allow NodeJS to utilize ports below 1024. Note that these permissions may sometimes be lost when updating the Linux Kernel and the command may need to be run again. ¹⁾

sudo setcap cap_net_bind_service=+ep /usr/bin/node

We are finally ready to install MeshCentral! We use NPM to install the latest version of MeshCentral with the command below: <HTML> <span style=“color:red;font-size:110%;”>!!DO NOT USE “SUDO” FOR THIS COMMAND!!</span> </HTML>

npm install meshcentral

After the installation completes we can manually run MeshCentral for the first time:

node ./node_modules/meshcentral

At this point, you should see MeshCentral create its' certificates and start running. Running manually like this MeshCentral is using the default configuration, and is in LAN only mode. You can open a web browser and either enter the name or IP address of the server in the address bar (or https://localhost if you are able to test from the server itself) and see the MeshCentral login page.

If you chose to use MongoDB stop here. You will need to edit the MeshCentral configuration to tell it to use MongoDB.

If you are using the built-in NeDB, I would recommend going ahead and creating your administrator account now. The first account created becomes the server administrator account so you should create it as soon as it is practically possible. In either case, MeshCentral is in a usable state now, but there are still a couple of things to do still. Press CTRL-C to stop MeshCentral and we will continue on.

By default, MeshCentral uses NeDB with a database file stored at ~/meshcentral-data/meshcentral.db. While this is great for small servers managing up to around 100 systems, if you chose to install MongoDB in the steps above, it is time to tell MeshCentral to use it instead.

The majority of the configuration options for MeshCentral are stored in a file called config.json, stored in the ~/meshcentral-data directory. We will edit it now to start using MongoDB. We start by opening the file in a text editor:

nano ~/meshcentral-data/config.json

Inside the text editor, we need to make the top section of the file look like this:

{
  "settings": {
    "MongoDb": "mongodb://127.0.0.1:27017/meshcentral",
    "WANonly": true,
    "_Port": 443,
    "_RedirPort": 80,
    "_AllowLoginToken": true,
    "_AllowFraming": true,
    "_WebRTC": false,
    "_ClickOnce": false,
    "_UserAllowedIP" : "127.0.0.1,::1,192.168.0.100"
  },
  <...more stuff here...>
}

If you are starting with the default config.json file created by the installation, you will need to remove some of the leading underscore characters “_” and add it to the beginning of some other values. This leading underscore character indicates a disabled (or commented out) value. So to enable a setting the value should not start with this underscore. To disable a setting you need to *add* the underscore. For full details on all of the available options in config.json you can see our config.json reference or the Complete config.json schema on GitHub.

Once you have finished editing the config.json file, save it (CTRL-O in nano) and exit the text editor (CTRL-X in nano) and manually run MeshCentral again:

node ./node_modules/meshcentral

Now go ahead and create a new account. The first account created becomes the server administrator, so yo don't want to delay creating this account. Once you have created this account and logged in with it successfully you can close MeshCentral again using CTRL-C. Next we will set up MeshCentral to run automatically in the background.

Since Ubuntu supports systemd, we are going to use that to auto start MeshCentral in the background. First we need to know what our own username and group are. The simplest way to find this info is (from your home folder) run

ls -l

Doing so should give output similar to this example below:

drwxr-xr-x 2 user group 4096 Jul 20 00:03 Desktop
drwxr-xr-x 2 user group 4096 Jul 20 00:03 Documents
drwxr-xr-x 2 user group 4096 Jul 20 00:03 Download
...

Make note of the username and group. In the sample above, the username is user and the group is group.

We will also need to know the path where NodeJS binaries are at. to find this enter:

which node
node: /usr/bin/node

Node is usually installed at /usr/bin/node but if your check above shows a different path, make note of it and enter it into the appropriate place in the file we are about to create.

We will need all of this information to create the description file for the MeshCentral service we create. To create this description file, enter:

sudo nano /etc/systemd/system/meshcentral.service

In this new file, enter the following lines:

[Unit]
Description=MeshCentral Server

[Service]
Type=simple
LimitNOFILE=1000000
ExecStart=/usr/bin/node /home/user/node_modules/meshcentral
WorkingDirectory=/home/user
Environment=NODE_ENV=production
User=user
Group=group
Restart=always
# Restart service after 10 seconds if node service crashes
RestartSec=10
# Set port permissions capability
AmbientCapabilities=cap_net_bind_service

[Install]
WantedBy=multi-user.target

Be sure you set the username and group values correctly for your specific installation. Notice that the ExecStart and WorkingDirectory lines include the path to the user's home folder. So make sure you have the correct username in there. Also be sure to double check the path to NodeJS in the ExecStart line.

Once we have this file created we can now enable, start, stop and disable MeshCentral:

sudo systemctl enable meshcentral.service
sudo systemctl start meshcentral.service
sudo systemctl stop meshcentral.service
sudo systemctl disable meshcentral.service

Run the first two commands to enable then start MeshCentral. Enabling the service will make MeshCentral start up automatically each time the computer restarts.

Once MeshCentral is started, you can access it via web browser just as we did earlier. You should now refer to the MeshCentral User's Guide or this wiki's configuration guides for information about on how to further configure and use MeshCentral.