Difference between revisions of "Node.js on Windows"

From Hostek.com Wiki
Jump to: navigation, search
(Created page with "== Installing Node.js on Windows VPS == #Download and install the Node.js installer (MSI) for Windows: https://nodejs.org/download/ #*Be sure to install the version with the...")
 
(updated grammar, examples, troubleshooting, and outline)
 
(One intermediate revision by the same user not shown)
Line 1: Line 1:
== Installing Node.js on Windows VPS ==
+
== Installing Node.js on a Windows VPS ==
  
#Download and install the Node.js installer (MSI) for Windows: https://nodejs.org/download/
+
=== Node.js ===
#*Be sure to install the version with the correct bitness of your server. Note that if you have Node.js already installed or the executable already on your server you can skip this step, although you might need to set additional permissions.
+
#Download and install the iisnode module from: https://github.com/Azure/iisnode/downloads
+
#Add "list folder" permissions on c:\home for IIS_USERS. Caution if your hosting multiple applications for various customers you might need to make further security considerations.
+
  
=== Running Your Node.js Application ===
+
Note that if you have Node.js already installed or the executable already on your server, then you can skip this step.
  
You should have a domain already created using our control panel WCP. Copy the Node.js application to a the destination folder, where you want to run it. For example: your-domain.com/node, will likely be in
+
#Download and install the Node.js installer (MSI) for Windows: https://nodejs.org/download/
 +
#*Be sure to install the correct version that matches your server's bitness.
 +
#Accept the defaults and finish installing Node.js.
  
<pre>
+
You can confirm that you've successfully installed Node.js by following these steps.
c:\home\your-domain.com\wwwroot\node
+
#Launch a new command prompt(cmd).
</pre>
+
#Run 'node --version' and it should print out the Node.js version installed on your server.
  
You will need to create a web.config and or iisnode.yml file (or modify the existing), see the next section for specifics.
+
=== iisnode ===
  
=== Modify iisnode web.config settings ===
+
If you want to host Node.js applications with IIS, then you'll need to use the "iisnode" IIS module.
  
'''If you followed the steps to install we suggest getting the example web.config and iisnode.yml from: C:\Program Files\iisnode\www\configuration'''
+
#Download and install the latest stable iisnode module from: https://github.com/Azure/iisnode/releases
 +
#*Be sure to install the correct version that matches your server's bitness.
 +
#Add "list folder" permissions on c:\home for IIS_IUSRS. You can use the "Advanced" permissions control to apply the permission to "This folder only". '''Caution:''' If you're hosting multiple applications for various customers you might need to make further security considerations.
 +
#*This assumes that you're using the default site path of 'C:\Home\domain.tld' that we configure on Windows VPS servers. If you have a custom setup, then you'll need to be sure that the 'IIS_IUSRS' group has "list folder" permissions for all directories leading up to your site's webroot.
  
NOTE: The iisnode.yml file overrides any iisnode specific settings except for the handler and entrypoint which you are required to include in the web.config.  
+
== Running Your First Node.js Application ==
  
<pre>
+
=== Configure your site for iisnode ===
    <handlers>
+
      <add name="iisnode" path="hello.js" verb="*" modules="iisnode" />
+
    </handlers>
+
</pre>
+
  
==== Example web.config ====
+
For your Node.js application to work with IIS, you will need to configure the site for use with iisnode. You can accomplish this with some web.config options, or a web.config option as well as a .yml config file. For the sake of simplicity and getting started quickly, we've provided a couple of examples below.
  
The only thing you'll need to change in this web.config example is moving the path to the node.exe executable and the interceptor. The nice thing about the web.config provided by the example is it details all the available settings. Here's an example web.config:
+
The only changes you'll probably need to make in the example yaml config are the paths to the node.exe executable and the interceptor.  
  
<pre>
+
'''web.config:'''
 +
 
 +
<syntaxhighlight lang="xml">
 
<configuration>
 
<configuration>
  <system.webServer>
+
<system.webServer>
 
+
    <!-- indicates that the hello.js file is a node.js application
+
    to be handled by the iisnode module -->
+
  
 
     <handlers>
 
     <handlers>
       <add name="iisnode" path="hello.js" verb="*" modules="iisnode" />
+
       <add name="iisnode" path="node_app.js" verb="*" modules="iisnode" />
 
     </handlers>
 
     </handlers>
 
+
   
     <iisnode
+
     <rewrite>
       nodeProcessCommandLine="&quot;%programfiles%\nodejs\node.exe&quot;"  
+
       <rules>
      interceptor="&quot;%programfiles%\iisnode\interceptor.js&quot;"    
+
        <rule name="nodejs">
      node_env="%node_env%"
+
          <match url="(.*)" />
      nodeProcessCountPerApplication="1"
+
          <conditions>
      maxConcurrentRequestsPerProcess="1024"
+
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
      maxNamedPipeConnectionRetry="100"
+
          </conditions>
      namedPipeConnectionRetryDelay="250"     
+
          <action type="Rewrite" url="/node_app.js" />
      maxNamedPipeConnectionPoolSize="512"
+
        </rule>
      maxNamedPipePooledConnectionAge="30000"
+
       </rules>
      asyncCompletionThreadCount="0"
+
    </rewrite>
      initialRequestBufferSize="4096"
+
   
      maxRequestBufferSize="65536"
+
    <security>
      watchedFiles="*.js;iisnode.yml"
+
       <requestFiltering>
      uncFileChangesPollingInterval="5000"     
+
        <hiddenSegments>
       gracefulShutdownTimeout="60000"
+
          <add segment="node_modules" />
      loggingEnabled="true"
+
          <add segment="iisnode" />
      logDirectory="iisnode"
+
        </hiddenSegments>
      debuggingEnabled="true"
+
       </requestFiltering>
       debugHeaderEnabled="false"
+
    </security>
      debuggerPortRange="5058-6058"
+
      debuggerPathSegment="debug"
+
      maxLogFileSizeInKB="128"
+
      maxTotalLogFileSizeInKB="1024"
+
       maxLogFiles="20"
+
      devErrorsEnabled="true"
+
      flushResponse="false"     
+
      enableXFF="false"
+
      promoteServerVars=""
+
      configOverrides="iisnode.yml"
+
    />
+
  
 
   </system.webServer>
 
   </system.webServer>
 
</configuration>
 
</configuration>
</pre>
+
</syntaxhighlight>
 +
 
 +
'''iisnode.yml:'''
 +
 
 +
<syntaxhighlight lang="yaml">
 +
# The optional iisnode.yml file provides overrides of 
 +
# the iisnode configuration settings specified in web.config. 
 +
 
 +
node_env: production 
 +
nodeProcessCommandLine: "C:\Program Files\nodejs\node.exe" 
 +
interceptor: "C:\Program Files\iisnode\interceptor.js" 
 +
nodeProcessCountPerApplication: 1 
 +
maxConcurrentRequestsPerProcess: 1024 
 +
maxNamedPipeConnectionRetry: 24 
 +
namedPipeConnectionRetryDelay: 250 
 +
maxNamedPipeConnectionPoolSize: 512 
 +
maxNamedPipePooledConnectionAge: 30000 
 +
asyncCompletionThreadCount: 0 
 +
initialRequestBufferSize: 4096 
 +
maxRequestBufferSize: 65536 
 +
watchedFiles: *.js;iisnode.yml 
 +
uncFileChangesPollingInterval: 5000 
 +
gracefulShutdownTimeout: 60000 
 +
loggingEnabled: true 
 +
logDirectory: iisnode 
 +
debuggingEnabled: true 
 +
debuggerPortRange: 5058-6058 
 +
debuggerPathSegment: debug 
 +
maxLogFileSizeInKB: 128 
 +
maxTotalLogFileSizeInKB: 1024 
 +
maxLogFiles: 20 
 +
devErrorsEnabled: false 
 +
flushResponse: false 
 +
enableXFF: false 
 +
promoteServerVars:
 +
</syntaxhighlight>
 +
 
 +
=== Create your application ===
 +
 
 +
For the most part, your Node.js application should work as expected. It's important to note that there are some differences. For example, the express .listen() method works differently with iisnode apps, which you can see later in the wiki. If necessary, you can find a handful of example applications in the iisnode github repo: https://github.com/Azure/iisnode/tree/master/src/samples/
 +
 
 +
In our example, we've created a very simple express application. You'll need to use npm to install the "express" node module. To do this, navigate to your site's web root in command prompt or powershell and then run the following command:
 +
 
 +
<pre>npm install express --save</pre>
 +
 
 +
Here is our example application:
 +
 
 +
'''node_app.js:'''
 +
 
 +
<syntaxhighlight lang="javascript">
 +
var express = require('express');
 +
var app = express();
 +
app.get('/', function (req, res) {
 +
res.send('Hello World!');
 +
});
 +
// This is REQUIRED for IISNODE to work
 +
app.listen(process.env.PORT, () => {
 +
console.log('listening')
 +
})
 +
</syntaxhighlight>
 +
 
 +
If you browse to your site, you should see the text "hello world".
 +
 
 +
If you need a simpler example that requires no 3rd party modules, then you can use this one from the iisnode github repo: https://github.com/Azure/iisnode/blob/master/src/samples/helloworld/hello.js
 +
 
 +
== Troubleshooting Your Node.js Application ==
 +
 
 +
If you followed this wiki, then logging should be enabled for your application. The standard output and standard error messages should be logged to their own respective log files in the "iisnode" directory.
 +
 
 +
=== Common Errors ===
 +
 
 +
'''Error: EPERM: operation not permitted, lstat 'C:\home''''
  
==== iisnode.yml for configuration ====
+
This means that your site's web user doesn't have permission to list the folder contents. Double-check the permissions of your site's web user and make sure that it can list the contents of all directories leading up to your site's web root.
  
[http://tomasz.janczuk.org/2012/05/yaml-configuration-support-in-iisnode.html About the iisnode.yml configuration it's importance.]
 
  
 
[[Category:Tutorials]]
 
[[Category:Tutorials]]
 
[[Category:Windows-VPS]]
 
[[Category:Windows-VPS]]

Latest revision as of 21:24, 28 December 2017

Installing Node.js on a Windows VPS

Node.js

Note that if you have Node.js already installed or the executable already on your server, then you can skip this step.

  1. Download and install the Node.js installer (MSI) for Windows: https://nodejs.org/download/
    • Be sure to install the correct version that matches your server's bitness.
  2. Accept the defaults and finish installing Node.js.

You can confirm that you've successfully installed Node.js by following these steps.

  1. Launch a new command prompt(cmd).
  2. Run 'node --version' and it should print out the Node.js version installed on your server.

iisnode

If you want to host Node.js applications with IIS, then you'll need to use the "iisnode" IIS module.

  1. Download and install the latest stable iisnode module from: https://github.com/Azure/iisnode/releases
    • Be sure to install the correct version that matches your server's bitness.
  2. Add "list folder" permissions on c:\home for IIS_IUSRS. You can use the "Advanced" permissions control to apply the permission to "This folder only". Caution: If you're hosting multiple applications for various customers you might need to make further security considerations.
    • This assumes that you're using the default site path of 'C:\Home\domain.tld' that we configure on Windows VPS servers. If you have a custom setup, then you'll need to be sure that the 'IIS_IUSRS' group has "list folder" permissions for all directories leading up to your site's webroot.

Running Your First Node.js Application

Configure your site for iisnode

For your Node.js application to work with IIS, you will need to configure the site for use with iisnode. You can accomplish this with some web.config options, or a web.config option as well as a .yml config file. For the sake of simplicity and getting started quickly, we've provided a couple of examples below.

The only changes you'll probably need to make in the example yaml config are the paths to the node.exe executable and the interceptor.

web.config:

<configuration>
<system.webServer>
 
    <handlers>
      <add name="iisnode" path="node_app.js" verb="*" modules="iisnode" />
    </handlers>
 
    <rewrite>
      <rules>
        <rule name="nodejs">
          <match url="(.*)" />
          <conditions>
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
          </conditions>
          <action type="Rewrite" url="/node_app.js" />
        </rule>
      </rules>
    </rewrite>
 
    <security>
      <requestFiltering>
        <hiddenSegments>
          <add segment="node_modules" />
          <add segment="iisnode" />
        </hiddenSegments>
      </requestFiltering>
    </security>
 
  </system.webServer>
</configuration>

iisnode.yml:

# The optional iisnode.yml file provides overrides of   
# the iisnode configuration settings specified in web.config.  
  
node_env: production  
nodeProcessCommandLine: "C:\Program Files\nodejs\node.exe"  
interceptor: "C:\Program Files\iisnode\interceptor.js"  
nodeProcessCountPerApplication: 1  
maxConcurrentRequestsPerProcess: 1024  
maxNamedPipeConnectionRetry: 24  
namedPipeConnectionRetryDelay: 250  
maxNamedPipeConnectionPoolSize: 512  
maxNamedPipePooledConnectionAge: 30000  
asyncCompletionThreadCount: 0  
initialRequestBufferSize: 4096  
maxRequestBufferSize: 65536  
watchedFiles: *.js;iisnode.yml  
uncFileChangesPollingInterval: 5000  
gracefulShutdownTimeout: 60000  
loggingEnabled: true  
logDirectory: iisnode  
debuggingEnabled: true  
debuggerPortRange: 5058-6058  
debuggerPathSegment: debug  
maxLogFileSizeInKB: 128  
maxTotalLogFileSizeInKB: 1024  
maxLogFiles: 20  
devErrorsEnabled: false  
flushResponse: false  
enableXFF: false  
promoteServerVars:

Create your application

For the most part, your Node.js application should work as expected. It's important to note that there are some differences. For example, the express .listen() method works differently with iisnode apps, which you can see later in the wiki. If necessary, you can find a handful of example applications in the iisnode github repo: https://github.com/Azure/iisnode/tree/master/src/samples/

In our example, we've created a very simple express application. You'll need to use npm to install the "express" node module. To do this, navigate to your site's web root in command prompt or powershell and then run the following command:

npm install express --save

Here is our example application:

node_app.js:

var express = require('express');
var app = express();
app.get('/', function (req, res) {
	res.send('Hello World!');
});
// This is REQUIRED for IISNODE to work
app.listen(process.env.PORT, () => {
	console.log('listening')
})

If you browse to your site, you should see the text "hello world".

If you need a simpler example that requires no 3rd party modules, then you can use this one from the iisnode github repo: https://github.com/Azure/iisnode/blob/master/src/samples/helloworld/hello.js

Troubleshooting Your Node.js Application

If you followed this wiki, then logging should be enabled for your application. The standard output and standard error messages should be logged to their own respective log files in the "iisnode" directory.

Common Errors

Error: EPERM: operation not permitted, lstat 'C:\home'

This means that your site's web user doesn't have permission to list the folder contents. Double-check the permissions of your site's web user and make sure that it can list the contents of all directories leading up to your site's web root.