Manual:Pywikibot/Workshop Materials/How to host a bot on Toolforge

For details of the past workshop on this subject, including the recording and the slides, see meta:Small_wiki_toolkits/Workshops.

TODO: Link to any general tips and tricks for workshop organizers if they exist somewhere.

Prerequisites

 * Familiarity with Pywikibot
 * Familiarity with Toolforge
 * Understanding of how to run Pywikibot on Toolforge

Organizer
To prepare to run this workshop, follow the steps below.


 * 1) Create or choose an existing Pywikibot script that you want to run on Toolforge.
 * 2) Ensure you have access to Toolforge.
 * 3) Create a new Toolforge tool using the Toolforge admin console.
 * 4) Prepare your tool on Toolforge based on wikitech:Help:Toolforge/Pywikibot.
 * 5) Upload or copy and paste your Pywikibot script to the tool's home directory and make sure it works correctly.
 * 6) * You can copy and paste it into nano or vim (in edit mode) directly from your clipboard.
 * 7) * You can place the script in a git repository (for example on https://gitlab.wikimedia.org) and clone it from there directly to your tool's home on Toolforge.
 * 8) * You can use  or a similar command to copy a file from your computer to your Toolforge account. For example:.
 * 9) Make the following decisions on how you want to run the workshop
 * 10) * Do you want the participants to follow along and perform the described activities immediately as you talk about them, or wait until a designated time to perform the activities?
 * 11) * Do you want the participants to interrupt you to ask questions, or wait for the designated time instead?
 * 12) * Do you want to record the workshop? If so, ask the participants if they consent to being recorded.
 * 13) * Are there any prerequisites or preparations required from the participants before the workshop? Look at the list in the section below and communicate these in an e-mail sent before the workshop.
 * 14) Share your decisions during the introduction to the workshop.
 * 15) Consider if there are any prerequisites or preparations required from the participants.

Participants
Be sure to inform workshop participants about the following points they need to consider to prepare for this workshop.


 * Participants will create their developer accounts (if they don't have them yet). To do this, they will have to come up with:
 * a developer account username
 * a shell username (required to log in to Toolforge)
 * a unique password
 * Each participant needs their own SUL account (regular Wikipedia account) to create a developer account as well.

It will also be helpful for participants to have basic familiarity with the concepts listed below before attending this workshop:


 * Terminal or command line usage
 * SSH and SSH authentication keys
 * Shared hosting concepts

Introduction
Start sharing your screen, ensure the recording is enabled if you planned to record.

Introduce yourself and the topic of the workshop. Explain the organizational choices and rules you've decided upon (for example, whether the participants should ask questions immediately or later, try to follow along or not - see for details).

What is Toolforge?


Explain that Toolforge is a shared hosting platform supported by Wikimedia Foundation staff and volunteers. It provides users with a small Linux machine that runs alongside similar machines set up for others. As a user, you can use this machine, for example, to run bots or host a website.

Present the wikitech:Portal:Toolforge page - explain that this is where the participants can find a lot of additional materials if they ever need help.

Source: wikitech:Portal:Toolforge/About_Toolforge

Differences between SUL and developer account


Explain the difference between SUL and the developer account. The former is used to log in to different wikis. The latter - to log in to Wikitech, Toolforge, Gerrit, and other services.

Explain that participants need to have the SUL account to create a developer account in the way used in this workshop.

Clarify that the developer account grants users access to Wikitech, Gerrit, Phabricator, in addition to Toolforge.

Sources:


 * meta:Help:Unified_login
 * wikitech:Help:Create_a_Wikimedia_developer_account

Creating a developer account


Explain how to create a developer account in the Toolforge admin console. Mention that it is also possible to create a developer account on Wikitech, so if any participant already did this, they will not be able to create a new account with the same username.

Iterate over the list of information required during account creation. Make it clear that a developer account requires a SUL account, a username, shell username, and a password. Note that some people might have trouble coming up with these during the workshop, so it is a good idea to include these in communication sent to participants beforehand (see [#Participants]).

Clarify that the UNIX shell username is used to access Toolforge so it is a good idea to make it simple and memorable.

Source: wikitech:Help:Create_a_Wikimedia_developer_account

Requesting access to Toolforge and creating a tool
Explain that creating the account does not immediately grant access to Toolforge. Demonstrate how to log in to the Toolforge admin console and create a new membership request.

Clarify that the request might be declined. You need to provide a valid reason to use Toolforge.

Once the request is approved, which can take a couple of days because it is done manually, you can create a new tool.

Explain how to create a new tool using the tool creation option in the admin console. Explain that what this does is actually create a tool account and a place on Toolforge for you to host and work with the tool.

Sources:


 * wikitech:Help:Create_a_Wikimedia_developer_account
 * wikitech:Portal:Toolforge/Tool_Accounts

Creating an SSH key


Explain what SSH is, what is an SSH key, and what is the difference between a private and public SSH key.

Mention that the process of creating an SSH key pair might be a bit different on different operating systems.

Clarify that participants might already have their own ssh keys created for another purpose. These keys are typically in.

Note that the two most popular SSH key types are RSA (most popular and compatible) and Ed25519 (more modern, equally secure, usually faster). If you don't specify a type using the  flag, it will default to using RSA.

Create the key while explaining each step of the creation process. Mention that it is possible to create a key without a password. If you don't want to have to type it in every time you use the key, do not provide a password when creating it.

Point out that the files are created inside the  directory.

Sources:


 * Secure_Shell
 * Public-key_cryptography
 * RSA_(cryptosystem)
 * EdDSA

Adding your SSH key to Toolsadmin
Demonstrate how to add the SSH key to your account in the admin console. Display the content of the public key file, for example by issuing the  command. Copy the public key to the text field on Admin console > Settings (in user menu) > SSH Keys.

Explain that this tells Toolforge to expect the private key matching this public key when you try to authenticate. You can have more than one key pair that you use to connect with Toolforge. It is a good practice to have a separate key pair for each computer you use.

Logging in to Toolforge


Explain how to log in to Toolforge by executing. Emphasize that you are using the shell username (not the developer account name), and the password you used when creating the key (and not the developer account password).

After successfully logging in, use the  command to switch to the tool account. Clarify that the name must match the name of the tool previously created in the admin console. Highlight that the prompt in the terminal changes when the  command is successful.

Running the bot


...