Portal:Toolforge/Tool Accounts

Overview

If you want to create a tool or collaborate with others to create and maintain tools, you'll need to create a Tool Account.

This page will help you understand what a Tool Account is, the first steps to create a Tool Account/tool, and how to add and remove maintainers.

What is a Tool Account?

The Tool Account is a group account associated with a tool. The Tool Account can have one or more maintainers. You'll create a separate Tool Account for each new tool you develop on Toolforge, and you'll join an existing Tool Account when you're invited to work on or maintain the tool. A note about terms: Tool Accounts and tools are sometimes used interchangeably throughout Toolforge documentation.

Each Tool Account includes:

• A home directory on shared storage: /data/project/<TOOL NAME>
• The ability to run a Web service which is visible at https://tools.wmflabs.org/<TOOL NAME>/
• Database access credentials: $HOME/replica.my.cnf, which provide access to the production database replicas as well as to project-local databases
• Access to the continuous and task queues of the compute grid
• Credentials and a namespace for running containers on the Kubernetes cluster

Maintainers

People who have access to a Tool Account are called maintainers. Maintainers have access to the Tool Account's code and data.

Maintainers can:

• Create Tool Accounts/tools
• Join existing Tool Accounts/tools
• Leave Tool Accounts/tools in the care of others
• Sudo to the Tool Account/tools

Join an existing Tool Account

All Tool Accounts hosted in Toolforge are listed on the tools list.

Contact the maintainer to join an existing Tool Account.

Add or remove maintainers

To add or remove maintainers, use the 'manage maitainers' link found beneath the tool name on the Toolforge home page.

Create tools with Tool Accounts

Members of the ‘tools’ project can create tool accounts using toolsadmin:

1. Go to https://toolsadmin.wikimedia.org/tools/
2. Click the "Create new tool" link at the bottom of the "Your tools" sidebar
3. Follow the instructions in the Tool Account creation form
4. Once the Tool Account is created, log off, then back in before you can access the new tool account

Name a Tool Account/tool

The Tool Account and tool will have the same name. This name will be included in the URL for the final Web service. Make sure the name is appropriate and is spelled correctly.

Note: Do not prefix the tool name with tools.. This will cause problems during account creation.

Rename a Tool Account/tool

Tools can't be renamed. You can create a new tool with a new name and copy the code over from the old tool.

Switch to / become a Tool Account

maintainer@tools-login:~$ become <TOOL NAME>
tools.toolname@tools-login:~$

Manage files in Toolforge

Take ownership of files

The take command allows you to change ownership of the file(s) and directories to the calling user.

Take ownership of files as your Tool Account

1. become your Tool Account:

yourshellaccountname@tools-login:~$ become toolaccount
tools.toolaccount@tools-login:~$

2. As your Tool Account, take ownership of the files:

tools.toolaccount@tools-login:~$ take FILE

Add a description to your Tool Account/Tool

1. Become your Tool Account:

maintainer@tools-login:~$ become <TOOL NAME>
tools.toolname@tools-login:~$

2. Create a .description file in the Tool Account’s home directory.

Note:This file must be HTML:

tools.toolname@tools-login:~$ vim .description

3. Add a description, and save the file.

4. Your Tool Account description should appear beside your Tool Account name in the Tools list

Delete a Tool Account

Maintainers can't delete Tool Accounts. You can delete the content of your directories and make an existing tool inaccessible by shutting down the Web service (webservice stop).

If you want to permanently delete a Tool Account, please follow the steps described at Toolforge (Tools to be deleted). It may take some time for the Tool Account to be deleted.

Troubleshoot a Tool Account

$ become <TOOL NAME>
become: no such tool '<TOOL NAME>'

• Wait a few minutes for the Tool Account creation to complete.
• Check that the spelling of the tool name is correct.

$ become <TOOL NAME>
You are not a member of the group tools.<TOOL NAME>.
Any existing member of the tool's group can add you to that.

• If you are already logged in via SSH when you create the a new tool, log out, and log in again to activate your new permissions.

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)

Backup Toolforge data

There are no user-accessible backups in Toolforge.

You should use a source or version control tool to preserve your code and make regular backups of data. Learn more.

See also

Visit the Toolforge portal to learn more about Toolforge and to explore more how-tos, tutorials, and developer stories.