Wikimedia Apps/Team/RESTBase services for apps/Testing instance setup

This page describes the process for setting up a new Cloud VPS instance to serve as a standalone, self-updating testing instance of a Node.js service.

Create the Cloud VPS instance

In a Cloud VPS project in which you have admin privileges, create a new instance from the latest available base image (currently Debian Buster). Choose the x1.small flavor unless you are certain that you will need additional computing resources.

Our practice is to name the instance with exactly the service it will be running, e.g., "wikifeeds" or "mobileapps."

It may take a short while for the instance to come online and accept SSH connections. If your connection attempts are at first rejected, wait 10 minutes and try again.

Install the service

Install basic dependencies

First, install some dependencies:

sudo apt install nodejs npm build-essential

Clone the service repository and install project-specific dependencies

Next, clone the service into /srv and install its node modules:

cd /srv
sudo git clone https://gerrit.wikimedia.org/r/mediawiki/services/<service>
sudo chown -R $(id -u):$(id -g) <service>
cd <service>
npm install

Run the service under systemd

Consider updating these instructions to use the systemd init file template provided as part of the Node.js service template.

In /etc/systemd/system/, create a unit file that describes the service and tells systemd how to run it.

For example, the following are the contents of /etc/systemd/system/wikifeeds.service on wikifeeds.eqiad.wmflabs:

[Unit]
Description=Featured wiki content in structured form

[Service]
ExecStart=/srv/wikifeeds/server.js -c /srv/wikifeeds/config.yaml

[Install]
WantedBy=multi-user.target

Now start the service and ensure that it runs as expected.

sudo systemctl start <service>
sudo systemctl status <service>

If something is wrong, troubleshoot as needed. If the service status looks good and the service responds to requests as expected, configure it to run on startup:

sudo systemctl enable <service>

Enable automatic updating

The mobileapps and wikifeeds services use a shell script to detect changes to the repo's master branch, and to pull changes and restart the service if any are found. The script is run frequently via cron. See scripts/puller.sh in the mobileapps or wikifeeds repository, and update with your service name as needed.

If the script file is newly created, you will need to make it executable:

chmod +x scripts/puller.sh

After the script file is in place and executable, create a new file in /etc/cron.d/ containing an entry directing cron to run the script regularly:

*/3 * * * * root /srv/<service>/scripts/puller.sh 1>/var/log/puller 2>&1

The example line above will run the puller script every three minutes, sending output to /var/log/puller.

Expose the service publicly

The final step is to expose your new, auto-updating service instance to the world.

Compute / Instances + Network / Security Groups

You will need to configure a security group to open the port on which your service is listening to incoming traffic. Create a new security group with a descriptive name (such as the name of your service). Once created, add a rule to the service to allow incoming traffic on the port on which your service is listening. (All of the fields except the port number will be pre-filled for this by default; simply enter the port number and create the rule.) Once the rule is added to your security group, add the security group to your instance.

DNS / Web Proxies

Finally, create a web proxy to expose the service to the web. Enter your desired wmflabs.org subdomain (again, the name of your service will work well), specify the port to which to proxy requests (this should be the port for which you just created a rule to allow incoming requests); and create the web proxy.

Congratulations!

You should now have an instance of your service available at https://<service>.wmflabs.org. Service-runner based projects could be checked using https://<service>.wmflabs.org/?doc and https://<service>.wmflabs.org/_info.