Run a Node.js application

Configure and start a Node.js application on your website.

A Node.js application runs on your website behind the web server: the HttpPlatform handler starts the node process for you and forwards requests to it. You upload the application together with a small web.config file — there is no command line to run on the server.

The two rules

  • Listen on the port from the PORT environment variable. The web server assigns the port dynamically, so a fixed port (3000, 5000, 8080) does not work:

    app.listen(process.env.PORT || 3000)
    
  • Upload a web.config into /wwwroot that tells the web server how to start your application.

Run a sample application

  1. Create a website

    Create a website in the Control Panel — see Create your first website.

  2. Create server.js

    Save this sample script as server.js. It prints information about the server, the request and the environment:

    var http = require('http');
    var os = require('os');
    var url = require('url');
    
    http.createServer(function (req, res) {
        res.writeHead(200, { 'Content-Type': 'text/html' });
    
        let currentPath = process.cwd();
        let scriptPath = __dirname;
    
        let protocol = req.headers['x-forwarded-proto'] || 'http';
        let currentUrl = protocol + '://' + req.headers.host + req.url;
    
        const envVariables = [
            "PORT",
            "HTTP_PLATFORM_IIS_APP_POOL_ID",
            "HTTP_PLATFORM_IIS_SITE_ID",
            "HTTP_PLATFORM_IIS_SITE_NAME",
            "HTTP_PLATFORM_IIS_VERSION",
            "HTTP_PLATFORM_IIS_HTTPAUTH",
            "HTTP_PLATFORM_PORT",
            "HTTP_PLATFORM_TOKEN",
            "HTTP_PLATFORM_APPL_PATH",
            "HTTP_PLATFORM_IIS_WEBSOCKETS_SUPPORTED"
        ];
    
        let html = `
            <h1>Server Information:</h1>
            <ul>
                <li><strong>Node version:</strong> ${process.version}</li>
                <li><strong>Environment:</strong> ${process.env['NODE_ENV']}</li>
                <li><strong>Working Directory:</strong> ${currentPath}</li>
                <li><strong>Script Path:</strong> ${scriptPath}</li>
            </ul>
    
            <h2>Request URL:</h2>
            <ul>
                <li><strong>Current URL:</strong> ${currentUrl}</li>
                <li><strong>Host:</strong> ${req.headers.host}</li>
                <li><strong>Original URL:</strong> ${req.headers['x-original-url'] || 'Not set'}</li>
                <li><strong>Rewrite URL:</strong> ${req.headers['x-rewrite-url'] || 'Not set'}</li>
                <li><strong>Protocol:</strong> ${req.headers['x-forwarded-proto'] || 'http'}</li>
            </ul>
    
            <h2>Environment Variables:</h2>
            <ul>
        `;
    
        envVariables.forEach(variable => {
            html += `<li><strong>${variable}:</strong> ${process.env[variable] || 'Not set'}</li>`;
        });
    
        html += `
            </ul>
    
            <h2>Request Headers:</h2>
            <ul>
        `;
    
        for (let header in req.headers) {
            html += `<li><strong>${header}:</strong> ${req.headers[header]}</li>`;
        }
    
        html += `
            </ul>
        `;
    
        res.end(html);
    }).listen(process.env.PORT || 3000);
    
  3. Create web.config

    Save this configuration as web.config. It is required — without it the web server does not start Node.js at all:

    <configuration>
      <system.webServer>
    
        <handlers>
          <add name="httpPlatformHandler" path="*" verb="*" modules="httpPlatformHandler" resourceType="Unspecified" />
        </handlers>
    
        <httpPlatform processPath="node" arguments=".\server.js" startupTimeLimit="20" stdoutLogEnabled="false" stdoutLogFile=".\logs\node">
          <environmentVariables>
            <environmentVariable name="PORT" value="%HTTP_PLATFORM_PORT%" />
            <environmentVariable name="NODE_ENV" value="production" />
          </environmentVariables>
        </httpPlatform>
    
      </system.webServer>
    </configuration>
    
  4. Upload both files

    Upload server.js and web.config into the /wwwroot folder of your website, for example over FTP or SFTP. /wwwroot is the website root and both files must be located directly in it.

  5. Open the website

    Open the address of your website in a browser. The sample script shows the Node.js version, the request URL, the environment variables and the request headers.

Your own application

  • In web.config, change arguments=".\server.js" to the entry script of your application.
  • You do not run npm or node on the server. Install all required modules locally with npm and upload the node_modules directory together with your application.
  • An application with node_modules has a lot of small files. Deploy from the command line or from a ZIP file is much faster than FTP.

Tip

If your project is on GitHub, Git deploy with the Node.js SSR app type builds the application on our server and generates the web.config for you.

The application does not start

Turn on the HttpPlatform debug log to see the output of the node process, including startup exceptions. See Node.js debug logging (HttpPlatform).

Still stuck? Our support team is happy to help.
Ask the community Open a support ticket