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


From Wikitech-static
< Help:Toolforge‎ | Web
Revision as of 20:07, 23 April 2021 by imported>BryanDavis (→‎Using other versions of node: oops, that was supposed to be an H2 section label)
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 node10 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 node10 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 node10 restart.
  3. Find your container's name by running kubectl get pods.
  4. Use the container name to check your container's logs kubectl logs -f $MY_CONTAINER_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 node10 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

We communicate and provide support through several primary channels. Please reach out with questions and to join the conversation.

Communicate with us
Connect Best for
Phabricator Workboard #Cloud-Services Task tracking and bug reporting
IRC Channel #wikimedia-cloud connect
Telegram bridge
mattermost bridge
General discussion and support
Mailing List cloud@ Information about ongoing initiatives, general discussion and support
Announcement emails cloud-announce@ Information about critical changes (all messages mirrored to cloud@)
News wiki page News Information about major near-term plans
Cloud Services Blog Clouds & Unicorns Learning more details about some of our work
Wikimedia Technical Blog News and stories from the Wikimedia technical movement

See also