Help:Toolforge/Node.js

Overview

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

Conventions

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

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');
}).listen(port);

Save the web server as $HOME/www/js/server.js.
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.
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.

Deploying a Vue JS Application using Node JS and Vite

SSH into your instance and become your tool.
Clone your project into the $HOME/www/js directory. If the directory doesn't exist, feel free to create it using the mkdir command. Ensure that the project is cloned such that the package.json is in the www/js directory using git clone https://YOUR_PROJECT_URL .
Add a start script to your package.json file to install dependencies, build the static assets of your application, and run the server. For example:
```
"start": "npm install && npm run build && node server.js"
```
You'd also need to add "express" as a dependency to your package.json
Create a node.js webserver in the $HOME/www/js directory using nano server.js.

By default when the build process is completed, vite would create a directory named dist with your static files. These are the files we would be serving over the server. Hence, the basic server configuration to do this would be:

import express from "express";
const app = express();
const PORT = parseInt(process.env.PORT, 10); // IMPORTANT!! You HAVE to use this environment variable as port!

app.use(express.static("dist"));

app.listen(PORT, () => console.log(`Server listening on port: ${PORT}`));

To initialize the webserver use: webservice --backend=kubernetes node18 start
To check the logs/build process, use: webservice --backend=kubernetes node18 logs
Once the build process is complete and the server begins listening, you can view your Vue application by visiting: https://YOUR_TOOL_NAME.toolforge.org

Kubernetes Configuration

The webservice command accepts the following parameters:

webservice --backend=kubernetes node18 start|stop|restart|shell

Put your node application in $HOME/www/js in your tool's home directory.
Start the web service with the following webservice --backend=kubernetes node18 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 node18 restart.
Find your pod's name by running kubectl get pods.
Use the pod name to check your pod's logs kubectl logs -f $MY_POD_NAME.
PROFIT! :)

Running npm with webservice shell

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

webservice --backend=kubernetes node18 shell
cd $HOME/www/js
npm install

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"}.

Troubleshooting

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

Chat in real time in the IRC channel #wikimedia-cloud ^connect or the bridged Telegram group
Discuss via email after you have subscribed to the cloud@ mailing list

Stay aware of critical changes and plans

Subscribe to the cloud-announce@ mailing list (all messages are also mirrored to the cloud@ list)
Read the News wiki page

Track work tasks and report bugs

Use a subproject of the #Cloud-Services Phabricator project to track confirmed bug reports and feature requests about the Cloud Services infrastructure itself

Read stories and WMCS blog posts

Read the Cloud Services Blog (for the broader Wikimedia movement, see the Wikimedia Technical Blog)