Portal:Toolforge/Quickstart

From Wikitech
Jump to navigation Jump to search


This page covers the basic steps to getting started with Toolforge.

For more information and links to developer/maintainer documentation visit the Toolforge Portal.

Terms and conditions

If you are an Account Holder planning to use WMCS resources and products, you must read and agree to the following:

Getting started with Toolforge - Quickstart

  1. Create a Wikimedia developer account.
  2. Create an SSH key and add it to your Wikitech account.
  3. Submit a Toolforge membership request and wait for its approval.
    • Your request will be reviewed, and you will receive confirmation within a week. You will be notified through your Wikitech user account.
  4. Once you are added as a Toolforge member, you must log out and then log in again at https://toolsadmin.wikimedia.org/
    • Doing this is required for your membership to take effect.
  5. Create a new tool or join an existing Tool account.
  6. Learn about managing files in Toolforge.

Run new tool - Quickstart

This example creates a simple PHP tool.

1. Log in to username@login.toolforge.org via ssh. To access Toolforge without using the command line, see the guide to using PuTTY and WinSCP.

ssh login.toolforge.org

2. Use the become command to access your tool's /data/project/MY_TOOL directory. This is your tool's $HOME.

become MY_TOOL

3. Create your tool's code/html root directory.

mkdir public_html

4. Create your tool's code.

echo '<html><head></head><body>Hello world!<?php ?></body></html>' > public_html/index.php

5. Start the tool.

webservice php7.4 start

6. Navigate to https://MY_TOOL.toolforge.org/ in your web browser to see your tool running.

For more details about this (and other kinds of tools), see Help:Toolforge/Web and Help:Toolforge/How to. For troubleshooting, see Help:Troubleshooting Toolforge.

Manage existing tool - Quickstart

When you log in to login.toolforge.org (via ssh) and call "become MY_TOOL", you get in the /data/project/MY_TOOL directory. This is your tool's $HOME. Then you can:

  1. Edit tool software and config files usually present in: $HOME/public_html, $HOME/www/python, $HOME/www/js, etc. For editing you can use console text editors (vi, edit, mcedit, etc.), use a version control tool like Git, or you can download, edit, or upload files using the SCP/SFTP protocol.
  2. Check if the tool is running, its type (php/python/js/java/etc.) and selected backend (kubernetes) using command: webservice status.
  3. Stop the tool: webservice stop
  4. Start the tool again: webservice --backend=kubernetes TYPE_OF_YOUR_TOOL start
  5. SSH to the tool's container: webservice --backend=kubernetes TYPE_OF_YOUR_TOOL shell

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 a subproject of the #Cloud-Services Phabricator project to track confirmed bug reports and feature requests about the Cloud Services 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