Help:Toolforge/Quickstart

Toolforge is a hosting environment, also known as Platform as a Service. Toolforge makes it easy for you to perform analytics, administer bots, run webservices, and create tools. Tools help project editors, technical contributors, and other volunteers who work on Wikimedia projects. Toolforge is part of the Wikimedia Cloud Services (WMCS) suite of services. It is supported by Wikimedia Foundation staff and volunteers. This page contains instructions on how to get started using Toolforge.

Get access

In order to use Toolforge, you must create a Wikimedia developer account and request access to the Toolforge project.

You must read and agree to the following to use Toolforge and other Wikimedia Cloud Services products:
Unless you have already created one, create a Wikimedia developer account (also known as a LDAP account or a Wikitech account). Go to the registration page on the Toolforge admin console and follow the instructions to create one.
If you already have an existing developer account, ensure that you have linked your Wikimedia and Phabricator accounts to the Toolforge admin console in the settings page.
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.
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.

Connect to Toolforge servers using SSH

You can use SSH to log in to Toolforge servers.

Set up an SSH client and a key

Install an SSH client, if you do not have one already. Windows 10 since version 1803 comes with OpenSSH built in. Popular clients include OpenSSH and PuTTY.
Generate an SSH key. SSH uses public-key cryptography to securely authenticate you to the server. Follow these instructions to generate one.
Add your public SSH key to your developer account on this page of the Toolforge admin console.

Log in to Toolforge

Use your SSH client to connect to Toolforge through a bastion host. Remember to use the shell username you picked when creating your Wikimedia developer account. You can see your username here. There are two bastion hosts to choose from:
login.toolforge.org

user login to access tools interactively

dev.toolforge.org

functionally identical, please use this for heavy processing such as compiles
```
$ ssh -i <path-to-ssh-private-key> username@login.toolforge.org
```
On your first connection, your SSH client will ask you to verify the "fingerprint" of the server. Ensure that the fingerprint shown matches ones shown on Help:SSH Fingerprints.
Once connected, you will see a prompt which displays your user name and the internal name of the host you are connected to.
```
username@tools-sgebastion-10:~$ become my-tool-name
tools.my-tool-name@tools-sgebastion-10:~$
```

Get familiar with the command line

This section is currently a draft.
Material may not yet be complete, information may presently be omitted, and certain parts of the content may be subject to radical, rapid alteration. More information pertaining to this may be available on the talk page.

Currently, the only way to interact with Toolforge is through a command line interface.

File permissions

Toolforge is a shared environment, and by default all files you create will be public. This means that when you create files containing passwords or other secret information, you need to set correct file permissions to ensure it stays private. You can use the following command to create a new blank file that only you can read or edit:

$ install -m 600 /dev/null FILE_NAME

Create or join a tool account

Once your Toolforge membership has been approved, you can create new tool accounts or be added to existing ones. A member of a tool account is called a maintainer. A single tool account can have multiple maintainers with access to the account, and a single Toolforge member can maintain multiple tool accounts. You should create a new tool account for each individual bot, web service or other tool.

Create a new tool account

Log in to the Toolforge admin console.
Navigate to the tool listing and click the "Create new tool" link at the bottom of the left sidebar.
Follow the instructions in the Tool Account creation form.

Join an existing tool account

Existing maintainers can follow these instructions to add new maintainers to a tool account:

Log in to the Toolforge admin console.
Navigate to the tool listing and select the tool you want to manage from the left sidebar.
Click "Manage maintainers". Add the new maintainers and click "Update".

Host your first tool on a tool account

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, the bridged Telegram group, or the bridged Mattermost channel
Discuss via email after you subscribed to the cloud@ mailing list

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)