Help:Toolforge/Quickstart
This page outlines the steps to get access to Toolforge and start working with files in a tool account.
Get access
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:
- Wikimedia Cloud Services Terms of Use
- Toolforge rules
- Code of Conduct for Wikimedia technical spaces
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:You should see the command prompt change to:$ become <toolname>
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.
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:
- Help:Toolforge/My first Django OAuth tool
- Help:Toolforge/My first Flask OAuth tool
- Help:Toolforge/My first NodeJS OAuth tool
- Help:Toolforge/Pywikibot
- Help:Toolforge/My first Rust tool
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:
- 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
- Subscribe to the cloud-announce@ mailing list (all messages are also mirrored to the cloud@ list)
- Read the News wiki page
Use a subproject of the #Cloud-Services Phabricator project to track confirmed bug reports and feature requests about the Cloud Services infrastructure itself
Read the Cloud Services Blog (for the broader Wikimedia movement, see the Wikimedia Technical Blog)