Help:Toolforge/Quickstart

This page outlines the steps to get access to Toolforge and start working with files in a tool account.

Get access

If you already have one of these accounts, see the following sections of this page for how to proceed with Toolforge setup.

To access Toolforge, Cloud VPS, or other Wikimedia developer tools, you need the following two types of accounts:

Account Type	Description	Where to sign up
Wikimedia account	Also known as "Wikimedia single user login (SUL)" account. Allows you to log into general wikis like Wikipedia, MediaWiki, and MetaWiki.	Create Wikimedia account
Wikimedia developer account	Username (also called LDAP username) is used to log in on Wikitech (this wiki), Gerrit, and the Toolforge admin console. In GitLab it is your displayed name, so you may want it to be your full name. You will not be able to change this later! Shell username is used to log into Toolforge, other Wikimedia VPS or Wikimedia production hosts using SSH.	Create Wikimedia developer account

You need both of these types of accounts to use Toolforge.

If you already have a Wikimedia account but no developer account

You can create a developer account through the Toolforge admin console (Toolsadmin):

Go to the registration page on Toolsadmin.
In the first box press the Login using Wikimedia account button.
You will be taken to a "Wikimedia account login" screen. Enter your Wikimedia account username and password.
Once you are logged into your Wikimedia account, you will return to Toolsadmin. You will be prompted to create an LDAP username, a UNIX shell username, and password. You will also be prompted to enter your email address and agree to the terms of service and code of conduct for technical spaces.
- The LDAP username will be used to log in to Wikitech, Gerrit and the Toolforge admin console.
- The UNIX shell username will be used to interact with servers via ssh and for git with Gerrit.
Submit the form to finish creating your Wikimedia developer account.

Because you used Toolsadmin to create your developer account, you don't need to complete any additional steps to link your accounts. Continue to request Toolforge membership.

If you already have both a Wikimedia account and a developer account

Go to the the Toolforge admin console (Toolsadmin).
In the first box press the Login using Wikimedia account button.
You will be taken to a "Wikimedia account login" screen. Enter your Wikimedia account username and password.
Go to the settings page in Toolsadmin to link your Wikimedia and Phabricator accounts to Toolforge.

Read and agree to terms of use

You must read and agree to the following terms to use Toolforge and other Wikimedia Cloud Services products:

Request Toolforge membership

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.
After you are added as a Toolforge member, log out and then log in again at 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 (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. Copy the contents of ~/.ssh/id_rsa.pub into the New SSH Key field and click Add SSH key.

Log in to Toolforge

Use your SSH client to connect to Toolforge through the login.toolforge.org bastion host. Remember to use the shell username you picked when creating your Wikimedia developer account. You can see your username at toolsadmin.
```
$ ssh -i <path-to-ssh-private-key> <shell-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.
After you connect, the command prompt displays your username and the internal name of the host to which you are connected:
```
<shell-username>@tools-sgebastion-10:~$
```

Create or join a tool account

After your Toolforge membership has been approved, create new tool accounts or ask other maintainers to add you to existing tool accounts. Each individual bot, web service or other tool should have a tool account.

Login and "become" your tool

After you create your tool account or join an existing tool account, and you have completed all the above setup steps:

Log in to Toolforge
From the command line, use the become command to switch to the tool account for the tool you want to work on:
```
$ become <toolname>
```
You should see the command prompt change to:
```
tools.<toolname>@tools-sgebastion-10:~$
```

Refer to Help:Toolforge/Tool Accounts to learn more about what you can do when you have "become" your tool.

Create and manage files

Currently, the only way to interact with Toolforge is through a command-line interface. If you prefer to develop using IDEs like Visual Studio Code or Eclipse, you can mount the home directory of your tool onto your local Linux machine or virtual machine (VM) Learn more at Help:Toolforge/Tool Accounts.

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.

Build and host your first tool

Now that you can connect to Toolforge and your tool account, you can proceed to build your tool in your preferred programming language. Follow a tutorial to help you get started:

Need some inspiration? Use Toolhub to explore existing tools and get ideas.

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 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)