====== Nodeserve ======

The Nodeserve system is designed to streamline the deployment and management of Node.js applications for EECS users. This platform allows users to easily host their Node.js apps on the web, providing a seamless interface for starting, and stopping their applications. By automating much of the setup and configuration, Nodeserve enables users to focus on development and learning without worrying about the complexities of server management. This guide will walk you through everything you need to get started with Nodeserve.

1.  Create a directory in your home directory called "nodejs".  This will be used for hosting your Node.js applications.

  % mkdir ~/nodejs

2.  Create a subdirectory inside the "nodejs" directory for each application that you intend to host.

For example, if you will be hosting an application "app1", create a directory in your nodejs directory called "app1":

  % mkdir ~/nodejs/app1

3.  Change into your app directory, and create a //package.json// file using the **npm init -y** command.  Using the "-y" option stops npm from asking you questions such as version, description, author, etc. and uses the defaults.

  % cd ~/nodejs/app1
  % npm init -y
  
4.  Develop your app.  You can use **npm install** to install whatever packages you need.

5.  Test your app on any EECS machine.  It's harder to debug your app when it's running on the server, so it makes sense to do most of your debugging locally.

6.  Allocate a port number for your app using the **nodeserve** command.

Each Node.js application must be allocated a unique port number to communicate with the web server. Ports act as channels for data to flow in and out of your app. We allocate a specific port for your app to ensure it runs smoothly without conflicts with other apps. This avoids issues that can arise from choosing an arbitrary port, which might already be in use by another service or application.

The nodeserve command has 3 options which can be used to add, delete, or list port allocations:

<code>
Usage: nodeserve add <app-name> - allocate a port for a Node.js app
       nodeserve del <app-name> - delete a port allocation for a Node.js app
       nodeserve list           - list port allocations for Node.js apps
</code>

A few notes on app names:

  * <app-name> can contain alphanumeric characters, -, and _.
  * <app-name> is limited to a maximum of 20 characters.

In addition, each user can be allocated a maximum of 10 port allocations.

For example, to get a port allocation for an app "app1":

<code>
% nodeserve add app1
Port 4000 has been allocated for app 'app1', and user 'bob'.
</code>

You can list the port allocations for your apps:

<code>
% nodeserve list

List of app port allocations for user 'bob':
  app1 -> Port 4000
</code>

You can also delete a port allocation for an app:

<code>
% nodeserve del app1
Port allocation for app 'app1', and user 'bob' has been removed.
</code>

7.  Visit your app on the web by visiting:  https://nodeserve.eecs.yorku.ca/<user>/<app> where <user> is your EECS username, and <app> is your application name.  

The web server will look up the port number allocated to your app, and set the port number in the PORT environment variable.  It will start running your app.  It will forward client requests from https://nodeserve.eecs.yorku.ca/<user>/<app> to your application running on http://localhost:<port>.

A few additional notes:

  * Your web application will run as your user ID.  It can read and write files in your home directory.
  * Any additional query arguments added to URL will be passed to your application - so, https://nodeserve.eecs.yorku.ca/<user>/<app>?opt1=option1&opt2=option2 will be passed to http://localhost:port?opt1=option1&opt2=option2.
 
====== Helpful Hints ======

1.  Each user can use the **nodeserve add** command to allocate a port for up to 10 applications.  If you need to make additional apps available, use **nodeserve del** to delete a port allocation from an older application. 

2.  When developing your code, please do not hard-code the port number allocated to you via the nodeserve command in your app. Instead, your code should read the port number from the environment variable //PORT//.  The system will let your app know which port number to use.

For example:

<code>
const port = process.env.PORT;
server.listen(port, () => {
    console.log(`Server is listening on port ${port}`);
});
</code>

3. In order to ensure that the server is not overloaded with applications which do not need to be running all the time, your application will automatically shutdown after approximately 10 minutes of inactivity.  Note however that whenever the application is called again, it will restart.

4. Sometimes, you may need to terminate your application before the period of inactivity expires.  For example, if your app is already running, and you make changes to the code, the changes won't be in effect until your app is restarted.    To terminate your app, visit the [[https://nodeserve.eecs.yorku.ca/admin|Nodeserv Admin Page]].  After logging in with your EECS username and password, you'll see a list of your running Node.js apps with a "Terminate" button beside each.  Click the "Terminate" button beside the app that you wish to terminate, and your app will be immediately terminated. 

5. Since your application is running on a server that you cannot login to, you don't have direct access to view the console.  However, this doesn't mean that you can't view the console of your app.  To modify your code to ensure that console messages are written to a file called "app.log" in your app directory, add the following to your Node.js app:

<code>
const fs = require('fs');
const logFile = fs.createWriteStream(`${__dirname}/app.log`, { flags: 'a' });
const logStdout = process.stdout;

// Override console.log to write to the file and stdout
console.log = function (...args) {
    logFile.write(new Date().toISOString() + ' - ' + args.join(' ') + '\n');
    logStdout.write(new Date().toISOString() + ' - ' + args.join(' ') + '\n');
};
</code>