JOTPOT Server Docs

Welcome the the documentation for JOTPOT Server, this first section is a guide on getting started with JOTPOT Server.
JOTPOT Server is a multipurpose server that is designed to elegantly fulfil a variety of tasks. The most simple function of JOTPOT Server is as a standard file server. Even if you are starting a more complex server, the following setup is almost universal.

Download

To start the first method, we will download the basic files that we need, all these downloads are available on jotpot.uk/server. JOTPOT Server is written in JavaScript for Node.js and also a bit of Go. The main server software is written for Node.js, with some more advanced features such as the load balancer written in Go. For this reason, there are a few different ways of running JOTPOT Server. The first is to run the server with Node.js. To do this, make sure that you either have Node.js installed or have a binary for it. It is recommended that you use a stable version from v6 onwards. And make sure that it is up-to-date with all the latest security and stability updates. Node.js can be downloaded from nodejs.org/en/download. Once installed, download and extract the Node.js source from jotpot.uk/server.
Here is an example of downloading the source from the Linux command line:

	wget https://www.jotpot.co.uk/releases/25D/jps.tar.gz
	tar -xzf jps.tar.gz
	rm jps.tar.gz

The source should then be in your current directory.
This source contains the basic configuration so there is no need to download anything else if you are using this method.
Another method of downloading JOTPOT Server is to download a version of Node.js that contains JOTPOT Server and has already been compiled into a binary, these are also available for a variety of platforms at jotpot.uk/server. If your platform is not supported you can compile your own (instructions on the download page), or just run it from Node.js (which is probably easier at this point).
When you have the correct binary, you will also need a configuration file and an error page, these can be downloaded also from jotpot.uk/server under the downloads titled 'A simple HTTP server connfig.json file' and 'The default error page'. Put these downloads into the same directory as the binary, and you are ready to go!

Setting things up

JOTPOT Server looks for the files to serve in the sites directory, each host should have a directory within this where it's webspace is contained. For example, if you were hosting the website 'example.com', then in your directory with the main server files - the one with the configuration file etc. - you would setup a directory named 'sites', and within that, one named 'example.com'. Please notes that port numbers other than 80 and 443 (for default HTTP and HTTPS) are included in the directory name, so when the server receives a request with the host 'example.com:8080', JOTPOT Server looks under 'sites/example.com;8080' - note how the colon is replaced with a semi-colon.
For localhost, we can set this up like this on Linux:

	mkdir sites
	mkdir sites/localhost

Or on Windows:

	md sites
	md sites/localhost

When JOTPOT Server receives a request, by default, it looks for that file, it will attempt to stat it. So a request for 'example.com/hello.html' would cause the server to stat 'sites/example.com/hello.html', if the file exists and is a file, then JOTPOT Server will serve that file. If it is a directory, then it will then attempt to stat 'sites/example.com/hello.html/index.html', and if that is a file, it will serve that. If 'sites/example.com/hello.html' doesn't exist, it looks for the filename, however with a '.page' extension, so 'sites/example.com/hello.html.page'. This can be useful if you would like 'example.com/hello' to load 'sites/example.com/hello.page'. If no file can be found, it responds with a 404, we will talk more about error responses later.
However, if the directory 'sites/example.com' doesn't exist, it will return a 404, unless the 'useDefaultHostIfHostDoesNotExist' property in the config.json file is set to true (from 25F onwards), in which case, it will act as if the host is the 'defaultHost' property in the config.json file, so if the default host were 'default' and the 'sites/example.com' directory didn't exist, it would instead look in the 'sites/default' directory.

Before you run, you might want to change a few settings in the config.json file. THe first one you might want to change is the port for the default HTTP server. It will be set to port 80, the default port for HTTP, however on Linux, you have to run it as root to be able to use that port (as is is below port 1024, and thus a privileged port) and also some other programmes you have running might be using that port, such as skype using port 80 on windows. If the port you are trying to use is in use, you will get the error: EADDRINUSE (error address in use), that is a sign you need to stop the programme using that port or change the port.
You can change the port by looking under the httpservers property in the config.json file and changing ' "port": 80, ' to ' "port": 8080, ' or whatever number you like.
You will then need to rename your localhost directory from 'localhost' to 'localhost;8080' (replace 8080 with the port number you used).

Making a simple website

So obviously, as a web server, it serves HTML to the browser. This tutorial is made with the assumption that you understand basic HTML, if you don't check out W3Schools HTML tutorial or MDN HTML Basics (or both if you have too much time).
Before we run, we will create a basic website for you to test it out on.
For the sake of this tutorial, we recommend creating 3 files, index.html, page2.html and page3.page - you can write whatever HTML you want inside these files, and save them into 'sites/localhost;<YOUR PORT NUMBER HERE>'

		Your directory structure might now look a bit like this:
		
		J:.
		│   config.json
		│   errorTemp.jpt
		│   jps.exe
		│
		└───sites
		    └───localhost;8080
		            index.html
		            page2.html
					page3.page
	
	

Run!

Running JOTPOT Server is simple, if you downloaded the binary, just navigate to the directory with your config.json file, errorTemp.jpt and sites directory and run the jps or jps.exe. For example on Linux:

	/ $  cd /path/to/jotpot/server
	/path/to/jotpot/server $  ./jps

Or on windows:

	/> cd /path/to/jotpot/server
	/path/to/jotpot/server> jps

If you downloaded the Node.js source and have Node.js installed, here is an example of how to run it on Linux:

	/ $  cd /path/to/jotpot/server
	/path/to/jotpot/server $  node run

Or on windows:

	/> cd /path/to/jotpot/server
	/path/to/jotpot/server> node run

On windows, you will have to add a firewall exception, and on Linux, if you are creating a server on a privileged port (port number below 1024), you will have to run it as root, so begin the command with sudo - although this isn't recommended, you can set it up so that traffic into port 80 goes to port 8080 for example either on your router or with iptables on Linux, there is a guide from nixCraft here.
Now, you can load up your browser, and head to http://localhost:<YOUR PORT NUMBER HERE>. This will load up the index.html page in your localhost;<YOUR PORT NUMBER HERE> directory. Then, go to http://localhost:<YOUR PORT NUMBER HERE>/page2.html and you will see your other web page, or go to http://localhost:<YOUR PORT NUMBER HERE>/page3 to see your page3.page file.

Going a bit further (just a bit, we haven't even got to extensions yet ;)

Now, you can try and access your server from another computer! To do this, find your local IP address, in Linux, use the ifconfig command, work out which interface you are using (mine is eth0, as it is the first eth (ethernet connection), you might be using wlan0 or a separate one) and read off the inet addr value, for example 192.168.1.103. And on windows use the ipconfig command, work out which adapter you are using, mine is the 'Ethernet adapter Ethernet', as mine is an ethernet connection, and read off the IPv4 Address value, again could be something along the lines of 192.168.1.103.
Remember those numbers. Go to another PC (for now, make sure it is on the same local area network (LAN) as the PC you are using as the server), and open the web browser. No go to http://<YOUR.IP.ADDRESS.HERE>:<YOUR PORT NUMBER HERE> (you don't need to add the :PORT part if you are using port 80 as 80 is the default port for HTTP).
You will notice that it responds with a 404: Not Found error, this is because it is now looking in 'sites/<YOUR.IP.ADDRESS.HERE>:<YOUR PORT NUMBER HERE>' for index.html, we could solve this be creating a new directory with that name. But we could also use a feature of JOTPOT Server called host aliasing. This allows you to set an alias up for a host, so host-a.com could be processed as host-b.com. We can set this alias in the config.json file. Find the property named "hostAlias". In the default config, the value will be '{}', if we set it to '{"host-a.com":"host-b.com"}', then host-a.com will be handled as host-b.com. This can continue as such: '{"host-a.com":"host-b.com", "some-other-website.co.uk":"some-other-website.com"}'. With a comma separating the values.
So to set up the alias you want, we can set the "hostAlias" property to '{"<YOUR.IP.ADDRESS.HERE>:<YOUR PORT NUMBER HERE>":"localhost:<YOUR PORT NUMBER HERE>"}'
Then, reboot the server. So this by focusing on the command window it is running in and pressing ctrl+c to kill the programme. If this doesn't work on Windows (due to changed defaults), just close the window. Then rerun the server and the config.json will be reloaded. Now try from the other computer again and your index.html file should pop up!

To connect to your server from another PC that is not on your network, you will need to know your global IP address, the one that points to you from outside of your LAN. You can get your global IP address from jotpot.uk/whatsmyip. You will then need to set up your router to let traffic on your chosen port get to your PC, this is known as port forwarding. Make sure that the port you want to use externally (this could be port 80, the default for HTTP remember or another port), forwards to the port that the server is running on on your PC.
There are some guides available for setting port forwarding up from: PCWorld, wikiHow, BT, How-To Geek and many others with a quick Google search for "how to set up port forwarding" (the How-To Geek one goes in to the most exciting detail)
Then, you will need to set up another host alias (just as we did before), but this time from <YOUR.GLOBAL.IP.ADDRESS>:<The port you chose to forward from> - remembering that if we chose port 80, we don't need the ':80' at the end. And still to 'localhost:<The port your server is running on>'
Reboot the server once more and try to connect via your global IP. If all is good, you should be able to access your web server from anywhere in the world now. However you might need to bare in mind that if you have a dynamically assigned IP address, your IP address will change from time to time, so you might need to keep on top of that.
From there, you can buy a domain name and point that to your IP and turn your website into whatever you like.
Buying a domain is one way to prevent the constant changing of the host aliases in the config file, but, as mentioned earlier, another way would be to use the default host.
So for this, lets rename out localhost directory to 'default', this could be anything, but default makes sense. We should then set our "defaultHost" property in the config.json file to the name of our directory. Luckily, the default one you downloaded, already has this. Then make sure that the "useDefaultHostIfHostDoesNotExist" property is set to true, before rebooting the server. You can also remove all the aliases now as they are no longer required.
After the reboot, no matter what host you use to connect to your server, as long as there isn't a directory for it, it will use the 'sites/default' directory, however if you were to register 2 domains, say "host-a.com" and "host-b.com", you could still have separate directory's for them 'sites/host-a.com' and 'sites/host-b.com', while everything else will go to 'sites/default'.

The rest of the docs dive deeper into JOTPOT Server, it covers the config.json file and also extensions - that give you the power to modify the behaviour of JOTPOT Server and add server-side logic and scripting. Have fun and thank you for using JOTPOT Server :)
JOTPOT Server is all open source on GitHub, so if you encounter any problems, or have any features would like to suggest or add yourself, head over there.

Properties:

'httpServers': Array. Each item of the array should be an object containing the HTTP server options.
'httpsServers': Array. Each item of the array should be an object containing the HTTPS server options.
'redirectToHttps': Array. Each item of the array should be a string of any domains you want to be permanently redirected to the https version of the site.
'canBeHttp': Array. Each item should be paths you do NOT want redirecting to HTTPS if the domain normally gets redirected.
'dataPort': Number, the port you would like the data connections to come though, see data connections.
'hostRedirects': Object. Format: {"host_you_want_redirecting.com":"host_to_redirect_to.com"}
'hostAlias': Object. Similar to hostRedirects however rather then redirecting the server will handle the request as if it came from the domain you set - without the user being redirected.
'pageAlias': Object. The same as hostAlias however with pages instead. Note the format: {"example.com/page1":"example.com/page2"}. If the user goes to example.com/page2, it will be handles as if it were example.com/page1.
'addVarsByDefault': Boolean, true to replace anything served in the format "$:::<var name>:::$" with the value of the variable or false to not replace be default.
'doVarsForIfNotByDefault': Array of Strings. The strings should be in the format: "<hostname>/<path>", any pages included in this array will have variables added to them even if doing them by default is set to false.
'cache': Array of Strings. Each item is in the format "<host>/<page>", this will be cached.
'errorTemplate': String. The file to use as the error page.
'defaultHost': String. The host to use by default if the http request contains no host header or useDefaultHostIfHostDoesNotExist is true and the host requested doesn't exist.
'useDefaultHostIfHostDoesNotExist': Boolean. true if the default host should be used like an alias if the host the user is requesting does not exist.
'behindLoadBalencer': Boolean. true if headers set be the JOTPOT Server load balencer should be used, for example when determining the source IP address or if the request was HTTPS.

HTTP Server Options:
'port': Number, the port you would like the server to be opened on.

HTTPS Server Options:
'port': Number, the port you would like the server to be opened on.

JOTPOT Server allows JavaScript files to be run and take control over the server, anything is possible via extensions and 'limited' extensions can be run to ensure an extension can only handle requests etc. from a specific domain/domains for security and stability.
Any file in the working directory of the server, with the full filename ending in '.jpe.js' will be loaded as extensions. There are 2 types of extensions, 'Master' extensions, and 'worker' extensions. JOTPOT Server runs using the Node.js cluster modules, this means that there is a master process and then an amount of workers. The master process runs all extensions (where the server.isMaster variable will be true) and each worker runs all the extensions (where the server.isMaster variable is false). They have some shared API features however some different features.
Every extension is loaded with the standard Node.js require function, console object, setTimeout along with the setInterval and setImmediate functions.
There is also a 'server' object for controlling and interacting with the current JOTPOT Server instance, documented below.
The most key consent of extensions is server.handle, and for developing simple applications, it can be all that is needed.

The server object is an object available is master and worker extensions, however with differences in each.

JOTPOT Server has a serese of events that extensions can handle to add behavior to or to overwrite the behavior of.
Please see server.handle() for handling events.

Events:

• 'ready' event: This is the first event to fire, this event is fired when the current process is up and ready. This is fired for both master extensions and worker extensions and is the only event currently for master extensions. It cannot be overwritten, so the return value is ignored. The handler is called with no arguments.
• 'request' event: This event is fired whenever a request is received, this event is fired before any redirects happen, such as redirects to HTTPS or redirects to the login page, so this should generally not be handled. The default behavior can be overwritten to if the handler returns true or returns a promise that resolves true, JOTPOT Server will stop handling the request. The handler is called with 2 arguments, the request object and the response object.
• '<domain>/request' event: This is the equivalent to the 'request' event however only fires for the domain before the '/'
• 'fullrequest' event: This event is fired after a request is redirected and has page/host aliases applied, this event is however fired before any authentication checks happen, so this should generally not be handled if an account system is active of the page. The default behavior can be overwritten to if the handler returns true or returns a promise that resolves true, JOTPOT Server will stop handling the request. The handler is called with 2 arguments, the request object and the response object.
• '<domain>/fullrequest' event: This is the equivalent to the 'fullrequest' event however only fires for the domain before the '/'
• 'allowedrequest' event: This event is fired when the server is ready to respond to the event, the user will have gone through all redirects, any aliases will have been applied and the user will be authenticated to access the page they are requesting. In most cases, this is the best event to handle for server side rendering, analytics and most other use cases.
• '<domain>/allowedrequest' event: This is the equivalent to the 'allowedrequest' event however only fires for the domain before the '/'

So, lets say you want to render a page serverside for the user, you could use the serveer.handle function to create this functionality.
When you handle any request event, so 'request', 'fullrequest', 'allowedrequest' or any host specific request, the handler function will receive 2 arguments, the request and the response object. These are documented below.
Here is an example:

	//Handle the request when we know it is allowed, to ensure that
	// we don't serve a page to a user that isn't logged in.
	server.handle('allowedrequest', (req, resp) => {
		
		//The request and response object have everything the standard
		// Node.js objects have however with some modified properties
		// and some additional ones.
		
		//Note how the domain is at the start of the req.url, see
		// req.url in the request docs below for how it is different.
		// You might also want to use req.purl here instead.
		if (req.url === 'www.exmaple.com/content.html') {
			
			//Call you own function to hamdle the request and the
			// response as you would in any other Node.js server.
			renderContentPage(req, resp) ;
			
			//Return true to say that this has handled the event
			// so the default behavior gets overwritten.
			return true ;
			
		}
		
		//If we haven't handled it, return false so the server 
		// continues with the default behavior for the request.
		return false ;
		
	});
	

The 'request' object is passed as the first argument to any hander function handling a request - with the second argument always been the response object. It is the Node.js IncomingMessage object however has some modified properties and some added properties to make working with it easier. All of these changed/additional properties are listed below.

The 'response' object is always passed to the request hander as the second argument, and similar to the 'request' object is the Node.js ServerResponse object however with a couple of added properties for ease of use. These added properties are documented below.