Skip to content

HowTo

Jump to bottom
Ivo Yankulovski edited this page May 19, 2023 · 30 revisions

NPM Install

Add to your package.json:

For master branch:

"dependencies": {
  "@types/protoss-nodejs-basic": "git+https://github.com/ZetaRet/protoss-nodejs-basic-types.git",
  "protoss-nodejs-basic": "git+https://github.com/ZetaRet/protoss-nodejs-basic.git"
}

For tags:

"dependencies": {
  "protoss-nodejs-basic": "git+https://github.com/ZetaRet/protoss-nodejs-basic.git#v2.0.1"
}

or if the types version exists and matches, otherwise use previous:

"dependencies": {
  "@types/protoss-nodejs-basic": "git+https://github.com/ZetaRet/protoss-nodejs-basic.git-types#v2.10.0",
  "protoss-nodejs-basic": "git+https://github.com/ZetaRet/protoss-nodejs-basic.git#v2.10.0"
}

Localhost development

Configure hosts file if you have access to /etc/hosts and add your subdomain:

127.0.0.1 localhost
127.0.0.1 my.nodewebsite.com.localhost

Open terminal in the ProtoSS node server folder

  • Configure basic ProtoSS server

  • Execute node index.js and start the server.

  • Configure module Subserver

  • create or copy stats.json in index.js folder

  • check modules\Subserver_stats.json

  • Execute node index.js and start the subserver.

  • Configure example.js

  • check Subserver configuration

  • Execute node example.js and start the example.

  • Configure your own application.js

  • check examples and example.js configuration

  • configure stats.json with the right server module, you might use your own implementation

  • you can change path to stats.json from global.ProtoSSCheStatsFile before loading index.js

  • server starts automatically, you might choose to stop it and execute different logic

  • several applications requiring the same index.js will load and share the same stats.json and therefor base server module

  • one application may create several different instances on different ports depending on implementation, sharing static properties with all other servers and applications pointing to the same folder

  • Execute node application.js and start your app.

  • Swap of ports in applications

  • starting new application based on server from the same folder will throw an error

  • in each of your applications sharing server folder close and listen the http server using your own port, you might choose to load it from a separate .json

  • use htport: 0 in your stats.json to listen on random port, or negative integer htport: -1 to disable auto listen in index.js

  • code example:

var myport = 5000;
var protossche = require('./index.js');
protossche.serverche.htserv.close().listen(myport);

Configure HTTPS server

  • set https: true in stats.json
  • place key.pem and cert.pem in your server folder of index.js
  • or specify httpsop Object in stats.json for any additional Node server configuration based on official documentation
  • special https options keys: keyPath, certPath, pfxPath, caPath

Apache Configuration

Load or enable in your httpd file the proxy modules:

LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so

Enable HTTP/2, if you need it locally, node will leverage the protocol:

LoadModule proxy_http2_module modules/mod_proxy_http2.so
LoadModule http2_module modules/mod_http2.so

Enforce protocols in main httpd and/or vhost:

ProtocolsHonorOrder On
Protocols h2 http/1.1

Enable SSL, if you need it locally, and configure the server keys:

LoadModule ssl_module modules/mod_ssl.so

Generate self-signed certificates.
Configure listen ports in httpd:

Listen 0.0.0.0:80
Listen [::0]:80

Listen 0.0.0.0:443
Listen [::0]:443

Enable SSL engine in your vhost configuration and add the secure port:

<VirtualHost *:80 *:443>
	...
	SSLEngine on
	SSLCertificateKeyFile "Drive:\path\to\certs\my.nodewebsite.com.localhost.key"
	SSLCertificateFile "Drive:\path\to\certs\my.nodewebsite.com.localhost.cert"
	...
</VirtualHost>

Add to your vhost configuration of ServerName my.nodewebsite.com.localhost the proxy line:

ProxyPass /node http://my.nodewebsite.com.localhost:8888/node

/node is your base url, you might omit it in the node url or change it
http://my.nodewebsite.com.localhost is your node host, use raw http for performance instead of https, ssl can be enforced from the next server layer of Apache/NGINX
8888 is your node listen port

You can load many ProxyPass lines with different base url, port or node host, including referring to the same host and port node from another route.

Rewrite of url is usually required by rewrite_module:

LoadModule rewrite_module modules/mod_rewrite.so

Add to root of the domain .htaccess for both dynamic route binding and SSL:

RewriteEngine On
RewriteBase /

RewriteCond %{HTTPS} !=on
RewriteRule ^/?(.*) https://%{SERVER_NAME}/$1 [R,L]

RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /?htPath=1 [L]

And in each folder of interest, before the other .htaccess code:

RewriteEngine On
RewriteBase /

If your system runs with Indexes enabled, you should either disable them for production or put new .htaccess in each folder with the code above. This will require index.php or index.html in the same folder, returning its content including an empty file.

GZIP transfer is enabled per header content-type and requires deflate module + filter module.

LoadModule deflate_module modules/mod_deflate.so

LoadModule filter_module modules/mod_filter.so

Create folder node in the root of your domain and create .htaccess with the following code:

AddOutputFilterByType DEFLATE text/plain
AddOutputFilterByType DEFLATE text/html
AddOutputFilterByType DEFLATE text/xml
AddOutputFilterByType DEFLATE text/css
AddOutputFilterByType DEFLATE text/javascript
AddOutputFilterByType DEFLATE application/xml
AddOutputFilterByType DEFLATE application/xhtml+xml
AddOutputFilterByType DEFLATE application/rss+xml
AddOutputFilterByType DEFLATE application/javascript
AddOutputFilterByType DEFLATE application/x-javascript
AddOutputFilterByType DEFLATE application/json

AddOutputFilterByType DEFLATE can exist in several places including root .htaccess
or main httpd file, if you have access to it

AddOutputFilterByType DEFLATE text/plain text/html text/xml text/css text/javascript application/xml application/xhtml+xml application/rss+xml application/javascript application/x-javascript application/json

Use vhost module:

LoadModule vhost_alias_module modules/mod_vhost_alias.so

Sample vhost for localhost:

<VirtualHost *:80>
	ServerName my.nodewebsite.com.localhost
	ServerAlias my.nodewebsite.com.localhost
	DocumentRoot "Drive:\path\to\website"
	ProxyPass /node/images !
	ProxyPass /node http://my.nodewebsite.com.localhost:8888/node
	<Directory "Drive:\path\to\website">
		Options +Indexes +Includes +FollowSymLinks +MultiViews
		AllowOverride All
		Require local
	</Directory>
</VirtualHost>

Indexes, Includes, FollowSymLinks, MultiViews might require separate module load, and can be disabled on production. Misconfiguration can create server confusion and require more awareness, use them for security and quick API access, depending on service type.

LoadModule negotiation_module modules/mod_negotiation.so
LoadModule include_module modules/mod_include.so

Caching of assets depends on all the other configurations and requires expires_module:

LoadModule expires_module modules/mod_expires.so

Add to .htaccess:

<IfModule mod_expires.c>
ExpiresActive On
ExpiresByType video/mp4 "access 1 month"
ExpiresByType video/webm "access 1 month"
ExpiresByType image/gif "access 1 month"
ExpiresByType image/png "access 1 month"
ExpiresByType image/jpg "access 1 month"
ExpiresByType image/jpeg "access 1 month"
ExpiresByType image/x-icon "access 1 month"
ExpiresByType font/woff "access 1 month"
</IfModule>

Caching of JS/CSS files on user machines is not promoted due to security reasons and requires additional version mechanism.

Web Sockets can work behind proxy and upgrade request automatically using wstunnel and htaccess configuration, including vhost configuraiton of ProxyPass

LoadModule proxy_wstunnel_module modules/mod_proxy_wstunnel.so

Sockets will leverage the rest of the configuration. We do not recommend the use of compression on socket server. Messages should be sent directly using Socket Controller of the hybrid ProtoSS HTTP server. The controller is a custom implementation of your choice and you can use any web socket server to achieve the effect. Use SSL from your HTTP server configuration.
The socket will operate using HTTP route API to receive/respond to each client socket instead, check Subserver.

Securing your socket using Apache SSL along with HTTP server:
The communication between Apache and ProtoSS hybrid server with socket won’t be encrypted, but it will be encrypted from the browser to Apache.
Open your node socket on url ws://my.nodewebsite.com.localhost:9999 (simply open port 9999 to WebSocket Server configuration) and follow the legacy vhost configuration of secure socket:

ProxyPass /wss ws://my.nodewebsite.com.localhost:9999 retry=0 keepalive=On  
ProxyPassReverse /wss ws://my.nodewebsite.com.localhost:9999 retry=0

Access url for socket now is wss://my.nodewebsite.com.localhost/wss

The Apache configuration can be modified to work with NGINX server.

Node.js works with PHP simultaneously, or any other server using ProxyPass.

Logic is separated by folder.

Now all of your nodes are fully automated with GZIP, SSL, CACHE, H2

Clone this wiki locally