Differences

This shows you the differences between two versions of the page.

--- services:nodeserve [2024/08/12 14:03] – created jas
+++ services:nodeserve [2024/08/13 11:48] (current) – [Nodeserve] jas
@@ Line 1: / Line 1: @@
-====== Nodeserve User Documentation ======
+====== Nodeserve ======
-Nodeserve allows you to make NodeJS apps available for others to access on the web.  Follow these instructions for enabling access to your NodeJS apps on the web.
+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.
-.  Create a directory in your home directory called "nodejs".  This will be used for hosting your NodeJS applications.
+.  Create a directory in your home directory called "nodejs".  This will be used for hosting your Node.js applications.
   % mkdir ~/nodejs
@@ Line 13: / Line 13: @@
   % mkdir ~/nodejs/app1
-.  Develop your NodeJS app in its respective app directory.
+.  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.
-.  For each app, create a package.json file using the //npm init -y// command.
+  % cd ~/nodejs/app1
+  % npm init -y
+.  Develop your app.  You can use **npm install** to install whatever packages you need.
-.  Let the server know that you want your app to be accessible on the web using the "nodeserve" command.
+.  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.
-The nodeserve command has 3 options - add, del, and list:
+.  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>
-nodeserve add <appname> to add an application
+Usage: nodeserve add <app-name> - allocate a port for a Node.js app
-nodeserve del <appname> to delete an application
+       nodeserve del <app-name> - delete a port allocation for a Node.js app
-nodeserver list to list applications
+       nodeserve list           - list port allocations for Node.js apps
 </code>
-For example, to let the server know you want "app1" to be accessible on the web:
+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
-App 'app1' added for user 'jas' with port 4000.
+Port 4000 has been allocated for app 'app1', and user 'bob'.
 </code>
-You can list the apps that you've made web accessible:
+You can list the port allocations for your apps:
 <code>
 % nodeserve list
-List of apps for user 'jas':
+List of app port allocations for user 'bob':
   app1 -> Port 4000
 </code>
-You can stop an app from being web accessible:
+You can also delete a port allocation for an app:
 <code>
 % nodeserve del app1
-App 'app1' deleted for user 'jas'.
+Port allocation for app 'app1', and user 'bob' has been removed.
 </code>
-NOTE: Deleting an app simply tells the Node web server that you don't want it to make your app web accessible.  It doesn't actually delete your app from your home directory.
+.  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.
-.  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>.
-The web server will look up the port number of your app, and set the port number in the PORT environment variable.  It will then  start running your app on the Node web server as your user id.  Since your NodeJS app is running as you, it can read and write files in your home directory.  The Nodeserve web server will automatically forward web traffic from https://nodeserve.eecs.yorku.ca/<user>/<app> to your app.  You can even use query strings like this: https://nodeserve.eecs.yorku.ca/<user>/<app>?opt1=option1&opt2=option2
+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 ======
-.  Each user can use the //nodeserve add// command to add up to 10 applications.  If you need to make more apps available, you will need to delete some.  Applications will be disabled at the end of each term.
+.  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.
 .  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.
@@ Line 73: / Line 90: @@
 . 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.
-. 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 NodeJS 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.
+. 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.
-. Since your application is running on the server, you don't have direct access to view the console, but that doesn't mean that you can't view the console!  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 NodeJS app:
+. 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>