User:SRodlund/Tool accounts (staging)
The title of this page will change when it is moved to main. It will cover some content on the current Toolforge:Help page. This page is a very rough draft. It contains a lot of disorganized information. See Toolforge:Help for current and definitive information.
Stories
- I am a new developer and/or new to the Wikimedia ecosystem, and I want to understand what is possible to do with Toolforge
- I am a new developer and/or new to the Wikimedia ecosystem, and I want to understand what Toolforge is and how to use it to create a tool
- I am an experienced developer, and I want to onboard experienced developers who are working on or with Toolforge
- I am an experienced developer, and I want to share information about how to perform a task or complete a process with a less experienced developer
- I am an experienced developer, and I want to find information about how Toolforge works
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 and the basics of using it.
Visit Portal:Toolforge to learn more about Toolforge and to explore more how-tos, tutorials, and developer stories.
Definitions
- Tool Account (Group Account)
- maintainer (member of a tool account)
- Toolforge
- tool
- user
- Toolsadmin
- Tool Webpage
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.
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 maintaner 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.
- Include screenshot
Create tools with Tool Accounts
- Include screenshots
- Link to info about picking a license: https://choosealicense.com/ (and info about license)
Members of the âtoolsâ project can create tool accounts using toolsadmin:
- Go to https://toolsadmin.wikimedia.org/tools/
- Click the "Create new tool" link at the bottom of the "Your tools" sidebar
- Follow the instructions in the Tool Account creation form
- Once the Tool Account is created, log off, then back in before you can access the new tool account
Naming 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 webservice.
- Make sure the name is appropriate and spelled correctly.
- Do not prefix your tool name with
tools.. This will cause the account to be created improperly if you do.
Rename a Tool Account
Tools can't be renamed. However, you can work around this by creating a new tool with a new name and copying the code over from the old tool.
Switch to the Tool Account
become:
maintainer@tools-login:~$ become <TOOL NAME>
tools.toolname@tools-login:~$
Delete a Tool Account
You can't delete a tool account yourself, though you can delete the content of your directories and make an existing web tool inaccessible by shutting down the web service (webservice stop). If you really want a tool account to be deleted, please file a task in Phabricator requesting that the
tool be deleted eventually.
Troubleshoot your new Tool Account
$ become <TOOL NAME>
become: no such tool '<TOOL NAME>'
- Make sure you have typed your new tool name correctly.
- It may take a few minutes for your tool's home directory and files to be created. Wait a few minutes, and try again.
$ 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.
- An active ssh session to login.tools.wmflabs.org will not automatically be updated with new permissions when you are added as a maintainer of a tool. If you are already logged in via ssh when you create the new tool, log out and then 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:
- 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)
[[Category:Toolforge| ]]