You are browsing a read-only backup copy of Wikitech. The live site can be found at


From Wikitech-static
< Help:Toolforge‎ | Web
Revision as of 08:49, 25 February 2022 by imported>Majavah (advertise node12 instead of node10 container)
Jump to navigation Jump to search


Node.js can run fairly well on Toolforge including with websocket support by running the following steps.


The Toolforge webservice command starts node.js web servers using convention rather than configuration. These conventions are expected by the Toolforge tooling:

  • A $HOME/www/js/package.json file must exist as part of your tool's application code.
  • Running npm start from the tool's $HOME/www/js directory must start the web server.
    • This will happen automatically if your main script is found at $HOME/www/js/server.js [1]
  • The PORT environment variable will be set to the port that your web server is expected to listen on. When using the Kubernetes backend, PORT will always be 8000.

Create a node.js web server

  1. Create a node.js web server. For example:
    var http = require('http');
    var port = parseInt(process.env.PORT, 10) ; // IMPORTANT!! You HAVE to use this environment variable as port!
    http.createServer(function (req, res) {
    	res.writeHead(200, {'Content-Type': 'text/plain'});
    	res.end('Hello World\n');
  2. Save the web server as $HOME/www/js/server.js.
  3. Make sure your node.js web server starts up properly when npm start is executed. The default way to do this is to name your main script server.js.
  4. Your server should bind to a port that is passed in as an environment variable (PORT). You can access this via process.env.PORT. Without this, your tool will not be found by the Nginx proxy.

The toolforge-node-app-base template repository is available on GitHub which has the above-mentioned setups already done and some further boilerplate code, which can be used to get started quickly.

Kubernetes Configuration

The webservice command accepts the following parameters:

webservice --backend=kubernetes node12 start|stop|restart|shell
  1. Put your node application in $HOME/www/js in your tool's home directory. It is a dictionary path hardcoded.[2]
  2. Start the web service with the following webservice --backend=kubernetes node12 start.
    • If the start fails you may need to create $HOME/www/js/package.json containing the text:
        "scripts": {
            "start": "node server.js"
    • To restart after a code change, run webservice --backend=kubernetes node12 restart.
  3. Find your pod's name by running kubectl get pods.
  4. Use the pod name to check your pod's logs kubectl logs -f $MY_POD_NAME.
  5. PROFIT! :)

Running npm with webservice shell

To use an up-to-date version of node, e.g. for installing dependencies, run:

  1. webservice --backend=kubernetes node12 shell
  2. cd $HOME/www/js
  3. npm install

Grid Engine Configuration

This is a legacy configuration and currently unsupported for new Tools accounts.

The webservice command accepts the following parameters:

webservice --backend=gridengine nodejs start|stop|restart

The Grid Engine backend provides node version v8.11.1 (as of November 2019).

  1. Put your node application in $HOME/www/js in your tool's home directory. It is a dictionary path hardcoded.[3]

Using other versions of node

If you need to use other versions of node, you can use nvm or a similar tool to install node versions locally.

To activate the version, define the start property of the scripts object in your package.json file to activate the needed version before starting your app. In its simplest form it could look like "scripts": {"start":"nvm run node server.js"}.


  • If you run into errors doing npm install, try LINK=g++ npm install
  • If you can't access the kubectl executable, could it be that you started a webservice shell and didn't exit it?

Communication and support

Support and administration of the WMCS resources is provided by the Wikimedia Foundation Cloud Services team and Wikimedia movement volunteers. Please reach out with questions and join the conversation:

Discuss and receive general support
Receive mail announcements about critical changes
Subscribe to the cloud-announce@ mailing list (all messages are also mirrored to the cloud@ list)
Track work tasks and report bugs
Use the Phabricator workboard #Cloud-Services for bug reports and feature requests about the Cloud VPS infrastructure itself
Learn about major near-term plans
Read the News wiki page
Read news and stories about Wikimedia Cloud Services
Read the Cloud Services Blog (for the broader Wikimedia movement, see the Wikimedia Technical Blog)

See also