Installation Guide

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 cd ~; mkdir dev (creates a 'dev' directory in your user folder)
4. enter touch .zshrc (if you are running macos earlier than Catalina, use touch .bash_profile instead)
5. enter mkdir .nvm (creates important folder for next step)
6. 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)
7. enter cd dev (switch to your 'dev' folder)
8. enter nvm install 10.22 (install our required version of NodeJS)
9. enter nvm use 10.22 (tell system to use NodeJS 10.22 for this directory)
10. enter nvm default 10.22 so nvm remembers your choice for every session

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.

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 ~/dev to go to your dev folder
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
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 ~/dev/netcreate-itest/build/
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 build directory.

• open Terminal and cd to the project's build directory (e.g. cd ~/dev/netcreate-itest/build
• 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.