Installation Guide

5/30/2024
tested on Ubuntu 24.04 system

WORK IN PROGRESS - UPDATED 07/29/2020
tested on macOS 10.15.5 (Catalina) system / Node 10.22

WORK IN PROGRESS - UPDATED 08/15/2018
tested on clean MacOS 10.13.6 (High Sierra) system
tested on clean Windows 10 Pro (version 1803 build 17134.345) running WSL Ubuntu

NetCreate is a webapp that runs on a local area network (LAN) on MacOS (or on an Ubuntu server at Digital Ocean). The

• You will install the code on a server computer (the "appserver" running on MacOS)
• The appserver is run using the Terminal app by entering command-line instructions.
• People access the app from client computers using the Chrome browser. They must be on the same LAN, but can be PC or Mac.

After initial setup, you'll need to run and occasionally update the software.

If you are new to the command line or would like some entry-level guidance, we have a Getting Started For Folks New To Technology guide available that will offers some tips and tricks for installation and troubleshooting. Some initial documentation on Digital Ocean installation is available in the Getting-Started documentation.

Installing the Development Environment

If you are installing on a clean system, you will need to install Git and Node (as managed by nvm).

1. open Terminal app
2. enter xcode-select --install (accept dialog box, then wait for install to complete)
3. enter touch .zshrc (if you are running macos earlier than Catalina, use touch .bash_profile instead)
4. enter mkdir .nvm (creates important folder for next step).
5. enter curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.11/install.sh | zsh (install nvm; double-check that this is up-to-date on official nvm install page). (if you are running macos earlier than Catalina, replace the zsh at the end of this command with bash)
6. enter mkdir netcreate (creates important folder for next step). This is where your Net.Create install will live. Put this somewhere you'll remember it and name it clearly.
7. enter cd netcreate (switch to your netcreate folder, or to wherever you created the folder to hold your Net.Create install. We'll refer to it as netcreate from here forward)
8. enter nvm install. This will use an existing file in the Github repo that indicates our required version of NodeJS.
9. enter nvm use. This confirms that the compile process will use the correct version of NodeJS that was installed in step 7.

At step 7, if you get a message that the command 'npm' cannot be found:

1. create a .zprofile (touch .zprofile) and add the following lines to the newly-created .zprofile file:

   export NVM_DIR="$HOME/.nvm"
   [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"  # This loads nvm
   [ -s "$NVM_DIR/bash_completion" ] && . "$NVM_DIR/bash_completion"  # This loads nvm bash_completion
   export PATH=/usr/local/share/npm/b> in:$PATH

2. Quit your terminal, reopen it to load the new zshrc and zprofile settings.
3. Re-run the nvm install command.

This project requires brunch, a command-line build tool for managing code compilation. You'll need to install the brunch tool once:

• enter npm install -g brunch@^2.0.0 (NetCreate uses Brunch v2, so we specify the latest version 2.x.x here. Brunch 3.x.x is not compatible.)

Here are the supplemental notes on the installation process and other useful dev tools. Or just contact Dave or Ben.

See also nc-multiplex README for more information on starting Net.Create to support multiple graphs on a single server.

Download and Run the Source Code

First-Time Source Code Installation

In Terminal change your working directory to where you will be keeping the NetCreate code. I use ~/dev here as the example.

Clone the repo from Github:

1. open Terminal app
2. run cd ~/netcreate to go to the folder you created to hold your Net.Create install
3. clone the repository (you may be prompted to enter your github user/password)

git clone https://github.com/netcreateorg/netcreate-itest.git
cd netcreate-itest

4. switch to the dev branch: git checkout dev . Note that this runs the dev branch of Net.Create, which is the most stable current working branch. If you'd like to try a more recent, potentially less stable, version with more features, check the branch list and find the most-recently-updated branch that does not have "dev-" as a prefix in the branch name.
5. enter the build folder: cd build
6. update Node packages: npm ci

This should load all the dependencies from the Internet. It may take several minutes. This takes care of the installation of the code, so you will just be running and updating the project from this point on.

Creating a data folder

Before you run Net.Create for the first time, you also need to create a runtime directory in the build directory, which contains your individual user data and template files. The install process does not automatically create this directory.

1. enter cd ~/netcreate/netcreate-itest/
2. enter mkdir runtime

The template and data files for any networks you create are stored in this runtime folder.

Running NetCreate

To run the project from the netcreate-itest directory.

• open Terminal and cd to the project's directory (e.g. cd ~/netcreate/netcreate-itest/
• enter ./nc.js --dataset=MyNetwork where "MyNetwork" is either the name of a network with existing loki/template files in the runtime directory or a new network for which you would like to create these files. See the User Guide for more information.
  • Deprecated: To run a default network, use npm run dev. The template/loki files for a default network will not be automatically created and this command will likely return error: Initialization error - Cannot find module response and Net.Create will not run.
• open Chrome on the same computer and browse to localhost:3000
• optionally open Chrome on another computer on the same LAN and browser to the "client" address shown on the terminal output (you may need to scroll up to see it)

Reporting Problems: For status messages, both Terminal and the Chrome Javascript console will emit information that may be helpful. If you encounter a problem, please grab a screenshot of the problem that shows the problem with the Terminal and console information and contact us.

Advanced Options

Heartbeat

Both the server and client sides will listen for a hearbeat from each other every 10 seconds (default). You can change this value by editing build/app/unisys/common-defs.js line 13: DEFS.SERVER_HEARTBEAT_INTERVAL = 10000; For example, to set it to 3 seconds, change the line to DEFS.SERVER_HEARTBEAT_INTERVAL = 3000;

Updating the Source Code

When the dev team releases a code update, you can use Terminal to do an update:

• open Terminal and cd to the project build directory.
• be sure you are in the right "branch" by entering git status (we use dev for latest test release)
  it should output something like On branch dev
• enter git pull to update the source code
• enter npm run clean to erase old compiled files "just in case"
• Enter npm ci in case there are new libraries added
• Enter npm run dev to run the project

NOTE: If you have modified the source code you will see a warning about losing changes. To do the git pull command, you will have to do one of the following first:

• git stash push to keep changes you've made
• git reset --hard HEAD to delete changes FOREVER

NOTE: You can also do the git pull through the SourceTree app, which provides a GUI that is a little easier to use than the command line. This is what we actually for our day-to-day.

You should be able follow the RUN instructions at this point.