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 wikis like Wikipedia, MediaWiki.org, MetaWiki, and Wikitech (this wiki). | Create Wikimedia account |
Wikimedia developer account |
|
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. Most operating systems come with OpenSSH built in. Another popular client is PuTTY.
- Generate an SSH key pair. Each key pair consists of a public key and a corresponding private key. SSH uses public-key cryptography to securely authenticate you to servers.
- If you are using OpenSSH, follow these instructions to generate a new key pair.
- If you are using PuTTY, follow these instructions instead.
- Add your public key to your developer account on this page of the Toolforge admin console. To do so, paste the content of your public key into the "New SSH Key" field and click "Add SSH key".
- If you are using OpenSSH, you can find your public key in the file
~/.ssh/id_rsa.pub
. - If you are using PuTTY, you can find your public key in the PuTTYgen window under "Public key for pasting into OpenSSH authorized_keys file".
- If you are using OpenSSH, you can find your public key in the file
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 one of the current key fingerprints for login.toolforge.org.
- 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
The bastion servers do not have compiler tools such as gcc installed. If you want to compile something, see Help:Toolforge/Troubleshooting#There_are_no_C/C++_compiler. |
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.
The Toolforge Build Service is the currently recommended way to deploy new tools to Toolforge. Follow a tutorial to help you get started:
- My first Buildpack Python tool
- My first Buildpack Django tool
- My first Buildpack PHP tool
- Help:Toolforge/Running Pywikibot scripts
Tutorials for the older prebuilt image method are also available:
- Toolforge/My first Django OAuth tool
- Toolforge/My first Flask OAuth tool
- Toolforge/My first NodeJS OAuth tool
- Toolforge/My first Rust tool
Some languages don't have yet a tutorial, but they are also supported. So in case this list gets out of sync, the updated list is the build service section for tutorials.
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 or the bridged Telegram group
- 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)