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 instanceEdit

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 serviceEdit

Install basic dependenciesEdit

First, install some dependencies:

sudo apt install nodejs npm build-essential

Clone the service repository and install project-specific dependenciesEdit

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

Create a systemd unit fileEdit

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 updatingEdit

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 publiclyEdit

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

Compute / Instances + Network / Security GroupsEdit

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 ProxiesEdit

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!Edit

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.