Home

Updated 2024-09-17

Running `nc-multiplex` on Digital Ocean

Here are instructions for creating a digital ocean droplet to run nc-multiplex.

1. Create a Droplet

https://www.digitalocean.com/community/tutorials/how-to-install-node-js-on-ubuntu-16-04

Create a Droplet

Select (assuming you are using a local ssh key)

SFO3
Ubuntu 24.04 (LTS) x64
Basic
CPU: Regular $4/mo (512MB)
SSH Key: <yourkey>
Add improved metrics (free)
Name: sfo3-ncmultiplex

Log in using the terminal app.

ssh -i ~/.ssh/<yourkey> root@<droplet_ip>

2. Open Ports

If you decide to turn on the firewall, open up all of these ports. But you can also run without ufw. https://www.digitalocean.com/community/questions/how-to-open-port-in-nodejs-ubuntu-server-for-ssl

ufw status
ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 3000:3100/tcp
ufw allow 4000:4100/tcp
ufw allow 2929/tcp
ufw allow 9485/tcp
ufw enable

3. Install Repo

git clone https://github.com/netcreateorg/nc-multiplex.git
cd nc-multiplex

4. Update NVM / Node

https://www.digitalocean.com/community/tutorials/how-to-install-node-js-on-ubuntu-16-04

sudo aptupdate
sudo apt install build-essential libssl-dev
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install
nvm use
npm ci

If you have other versions of node installed, it can be useful to set a default node version, especially if you're often rebooting or taking other actions that might leave you with a different default node version. Use the nvm alias default command, e.g.:

nvm alias default 18.20.04

5. Install Net.Create

Assuming we're still in the ~/nc-multiplex directory

git clone https://github.com/netcreateorg/netcreate-itest.git
cd netcreate-itest
git checkout dev (or whichever branch is appropriate)
npm ci

Run it once to set configuration files

./nc.js --dataset=demo

Check to make sure Net.Create is running.

Go to http://<your_ip>:3001

You should see an empty demo graph with no errors.

Package the (assuming still in ~/nc-multiplex/netcreate-itest folder) so that we build the production files (not dev mode with all the build watchers)

npm run package

6. Start Reverse Proxy Server

Start nc-multiplex to make sure it's running.

cd ~/nc-multiplex
node nc-multiplex.js

The output should look like this:

root@sfo3-ncmultiplex:~/nc-multiplex# node nc-multiplex.js 
...nc-launch-config: found primary repo ./netcreate-itest




...nc-multiplex: 
...nc-multiplex: STARTED!
...nc-multiplex: 
[HPM] Proxy created: (pathname, req) => {
      // only match if there is a trailing '/'
      if (req.params.file) return true; // legit file
      if (req.params.graph && req.originalUrl.endsWith('/')) return true; // legit graph
      return false;
    }  -> http://localhost:3000
[HPM] Proxy created: /  -> http://localhost:3000
...nc-multiplex: running on port 80.
...nc-multiplex:  NODE VERSION: v18.18.2 OK
...nc-launch-config: found primary repo ./netcreate-itest
...nc-launch-instance:
...nc-launch-instance: STARTING DB base
...nc-launch-instance:
...nc-launch-instance: 1. Setting netcreate-config.js.
...nc-launch-instance: 2. Starting server
APP_SERV -
APP_SERV - *** GO TO ONE OF THESE URLS in CHROME WEB BROWSER
APP_SERV - *** MAINAPP - http://localhost:3000
APP_SERV - *** CLIENTS - http://xxx.xxx.xxx.xxx:3000
APP_SERV -
APP_SERV - shell is /bin/bash
APP_SERV - NOTICE: CODE-WORKSPACE NOT LOADED
APP_SERV - .. skipped version environment checks
SRV_NET  - unisys network is active on port 4000
...nc-launch-instance: 3. Server started on port 3000!
...nc-multiplex: Received message from spawned fork: nc-launch-instance.js: Completed!
...nc-multiplex: 
...nc-multiplex: base STARTED!
...nc-multiplex: 
APP_SERV - ARCHITECTURE: x86_64
APP_SERV - NOTICE: NETCREATE TESTED ON X86 NODEJS LIBRARIES
APP_SERV - .. For Mac ARM64 launch a Rosetta-compatible shell by running
APP_SERV -    arch -x86_64 /bin/bash
APP_SERV - git branch is dev-bl/cleanup-comments
APP_SERV - nodejs version is v18.18.2
ServerDB - dataset loaded ./runtime/base.loki m_max_nodeID '0', m_max_edgeID '0'
ServerDB - template loaded ./runtime/base.template.toml

7. Set up PM2

After you've made sure that everything is running correctly, set up PM2 so nc-multiplex runs automatically. https://www.digitalocean.com/community/tutorials/how-to-set-up-a-node-js-application-for-production-on-ubuntu-18-04

npm install pm2@latest -g
pm2 start nc-multiplex.js
pm2 startup systemd
pm2 save

pm2 reload all

If you want to use a custom script like do-start.sh

#!/bin/bash

echo "Starting nc-multiplex..."
# old command erases log
# node nc-multiplex > log.txt

# new command appends to log, and captures stderr too
# note that this is a different file than above
node nc-multiplex-sri >> log.txt 2>&1

Then set pm2 to use the script, e.g.

npm install pm2@latest -g
pm2 start do-start.sh
pm2 startup systemd
pm2 save
pm2 reload all

Troubleshooting

General

Check your branches
- Keep in mind there are two active repos that might have two different active branchs. Make sure you've checked out the right branch for both nc-multiplex and netcreat-itest.
Use curl http://localhost from the droplet console to troubleshoot port forwarding issues. If you see html, then the server is likely running and you're having trouble with ports not being forwarded.

nc-multiplex runs, but no graphs load

If the main nc-multiplex app seems to run (e.g. you can get to the "manage" screen and seemingly start graphs), but when you go to the graph URL the system just hangs, you probably don't have enough memory.

Check your memory. Graphs won't load if there's less than 256MB free by default. See the MEMORY_MIN value set up in nc-multiplex.js.

In our testing, a DO droplet with 512MB was not adequate for running nc-multiplex.

systemctl

It's easy to screw up systemctl services. To review which systemctl services may have been inadvertently set up: systemctl list-units --type=service

PM2 -- Remove bad service

If you've been running a droplet for a long time, it's possible some of your libraries can be out of date. In particular, if you use pm2 to set up the startup services and have not updated them in a while, your pm2 service might not be accurate.

One way to check:

systemctl list-units --type=service | grep pm2

...and look for a line like:

pm2-root.service	loaded failed failed PM2 proces manager

If you see that, more than likely your pm2 install is wrong.

For example:

node -v     # current version should be v18.18.2
which pm2   # NOTE wrong version: /root/.nvm/versions/node/v18.16.0/

And if you check the current service definition...

less /etc/systemd/system/pm2-root.service

...you might see...

ExecStart=/root/.nvm/versions/node/*v18.16.0*/lib/node_modules/pm2/bin/pm2 resurrect
ExecReload=/root/.nvm/versions/node/*v18.16.0*/lib/node_modules/pm2/bin/pm2 reload all
ExecStop=/root/.nvm/versions/node/*v18.16.0*/lib/node_modules/pm2/bin/pm2 kill

NOTE the PM2 service references a different version.

To fix that you have to:

# 1. disable the current pm2
systemctl disable pm2-root

# 2. stop the pm2 service
systemctl stop pm2-root

# 3. delete the pm2 service file
rm /etc/systemd/system/pm2-root.service

# 4. reload systemd
systemctl daemon-reload

# 5. verify removal
systemctl list-units --type=service | grep pm2

# 6. re-install pm2 (if necessary)
which pm2
node -v
npm install pm2@latest -g

# 7. remove any bad services
pm2 list
pm2 delete <badservice>

# 8. start up a new service
cd ~/nc-multiplex
pm2 start nc-multiplex.js
pm2 startup systemd
pm2 save
pm2 reload all

Changing your PM2 `nc-multiplex.js` script

If you modify your existing start PM2 start script (e.g. pm2 start do-start.sh or pm2 start nc-multiplex.js), you should be able to just reboot the server and pm2 will run the updated script.

However, if you want to switch from one start script to a different start script (e.g. you set up pm2 with pm2 start nc-multiplex.js and then pulled a new branch with the start.sh script, you'll need to go through the "start up a new service" routine, e.g.

pm2 list                  # nc-multiplex
pm2 delete nc-multiplex
pm2 start start.sh
pm2 save
pm2 reload all
reboot

Restarting `nc-multiplex.js`

If you update the nc-multiplex repo, and specifically, if you update the nc-multiplex.js script, you'll need to re-run pm2 and the start-nc-multiplex.sh shell script to restart nc-multiplex.js. Otherwise the old code will continue to run.

pm2 list                      # check running script
pm2 stop start-nc-multiplex
pm2 start start-nc-multiplex

Updating `netcreate-itest`

If you update netcreate-itest repo, you need to rebuild the app and restart graphs.

cd nc-multiplex/netcreate-itest
git fetch
git checkout dev-next
git pull
npm run package
# stop all graphs

# Restart nc-multiplex
pm2 stop start-nc-multiplex
pm2 start start-nc-multiplex

# Re-open any graphs

OLD REFERENCES

Older DO documentation can be found here:

GEM-STEP instructions — has detailed PM2 instructions, probably where Joshua got his do-start.sh script
MEME instructions copied over from NetCreate (I can’t find the original NetCreate instructions)
Rough notes in nc-multiplex

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Home

Running `nc-multiplex` on Digital Ocean

1. Create a Droplet

2. Open Ports

3. Install Repo

4. Update NVM / Node

5. Install Net.Create

6. Start Reverse Proxy Server

7. Set up PM2

Troubleshooting

General

nc-multiplex runs, but no graphs load

systemctl

PM2 -- Remove bad service

Changing your PM2 `nc-multiplex.js` script

Restarting `nc-multiplex.js`

Updating `netcreate-itest`

OLD REFERENCES

Clone this wiki locally

Home

Running nc-multiplex on Digital Ocean

1. Create a Droplet

2. Open Ports

3. Install Repo

4. Update NVM / Node

5. Install Net.Create

6. Start Reverse Proxy Server

7. Set up PM2

Troubleshooting

General

nc-multiplex runs, but no graphs load

systemctl

PM2 -- Remove bad service

Changing your PM2 nc-multiplex.js script

Restarting nc-multiplex.js

Updating netcreate-itest

OLD REFERENCES

Clone this wiki locally

Running `nc-multiplex` on Digital Ocean

Changing your PM2 `nc-multiplex.js` script

Restarting `nc-multiplex.js`

Updating `netcreate-itest`