You are browsing a read-only backup copy of Wikitech. The live site can be found at wikitech.wikimedia.org
Portal:Toolforge/Tool Accounts: Difference between revisions
imported>Pavithraes (Add the navigation template) |
imported>Huji |
||
| (9 intermediate revisions by 6 users not shown) | |||
| Line 3: | Line 3: | ||
== Overview == | == Overview == | ||
If you want to create [[ | If you want to create [[About Toolforge#What is a tool?|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. | 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. | ||
See [[Portal:Toolforge/Quickstart|Toolforge quickstart]] to set up and get started with Toolforge! | |||
== What is a Tool Account? == | == What is a Tool Account? == | ||
| Line 14: | Line 16: | ||
* A home directory on shared storage: <code>/data/project/<TOOL NAME></code> | * A home directory on shared storage: <code>/data/project/<TOOL NAME></code> | ||
* The ability to run a [[Help:Toolforge/Web|Web service]] which is visible at <code | * The ability to run a [[Help:Toolforge/Web|Web service]] which is visible at <code>https://<TOOL NAME>.toolforge.org/</code> | ||
* [[Help:Toolforge/Database|Database]] access credentials: <code>$HOME/replica.my.cnf</code>, which provide access to the production database replicas as well as to project-local databases | * [[Help:Toolforge/Database|Database]] access credentials: <code>$HOME/replica.my.cnf</code>, which provide access to the production database replicas as well as to project-local databases | ||
* Access to the continuous and task queues of the [[Help:Toolforge/Grid|compute grid]] | * Access to the continuous and task queues of the [[Help:Toolforge/Grid|compute grid]] | ||
| Line 21: | Line 23: | ||
== Maintainers == | == Maintainers == | ||
People who have access to a Tool Account are called ''maintainers''. Maintainers have access to the Tool Account's code and data. | People who have access to a Tool Account are called ''maintainers''. Maintainers have access to the Tool Account's code and data. | ||
Maintainers can: | Maintainers can: | ||
| Line 32: | Line 34: | ||
== Join an existing Tool Account == | == Join an existing Tool Account == | ||
All Tool Accounts hosted in Toolforge are listed on the [[toolforge:admin/tools|tools list]]. | All Tool Accounts hosted in Toolforge are listed on the [[toolforge:admin/tools|tools list]]. | ||
Contact the maintainer to join an existing Tool Account. | Contact the maintainer to join an existing Tool Account. | ||
| Line 38: | Line 40: | ||
== Add or remove maintainers == | == Add or remove maintainers == | ||
To add or remove maintainers, use the 'manage maitainers' link found beneath the tool name on the Toolforge home page. | To add or remove maintainers, use the 'manage maitainers' link found beneath the tool name on the Toolforge home page. | ||
<!-- Include screenshot --> | <!-- Include screenshot --> | ||
== Create tools with Tool Accounts == | == Create tools with Tool Accounts == | ||
| Line 47: | Line 49: | ||
[[File:Screenshot about creating a new tool..png|thumb]] | [[File:Screenshot about creating a new tool..png|thumb]] | ||
Members of the ‘tools’ project can create tool accounts using [https://toolsadmin.wikimedia.org toolsadmin]: | Members of the ‘tools’ project can create tool accounts using [https://toolsadmin.wikimedia.org/ toolsadmin]: | ||
# Go to https://toolsadmin.wikimedia.org/tools/ | # Go to https://toolsadmin.wikimedia.org/tools/ | ||
# Click the "Create new tool" link at the bottom of the "Your tools" sidebar | # Click the "Create new tool" link at the bottom of the "Your tools" sidebar | ||
# Follow the instructions in the Tool Account creation form | # 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 | # Once the Tool Account is created, log off, then back in before you can access the new tool account | ||
| Line 72: | Line 74: | ||
== Manage files in Toolforge == | == Manage files in Toolforge == | ||
=== Transfer files === | |||
You can use <code>scp</code> (or PuTTY) to copy files from your computer to Toolforge. To make files available to a tool account, copy or move them from your home directory to the tool's home directly:<pre> | |||
yourshellaccountname@tools-login:~$ cp somefile ~tools.toolaccount/ | |||
</pre>Note that the tool account will have to <code>take</code> ownership of the file before it can use it, see below. | |||
=== Take ownership of files === | === Take ownership of files === | ||
The <code>take</code> command allows you to change ownership of the file(s) and directories to the calling user. | The <code>take</code> command allows you to change ownership of the file(s) and directories to the calling tool user. | ||
The permissions of the file(s) before <code>take</code> is run must include the tool user as either the owner or group. This prevents <code>take</code> from being abused to take over arbitrary files. | |||
To take ownership of files as your tool account: | |||
1. <code>become</code> your Tool Account: | 1. <code>become</code> your Tool Account: | ||
| Line 92: | Line 101: | ||
</pre> | </pre> | ||
== | === Mount your tools home directory onto your local machine === | ||
Modifying files on Toolforge servers may be difficult; after all, you are restricted to terminal-based editors. If you prefer to use modern IDEs such as Visual Studio Code, Eclipse, etc. you can mount the home directory of your tool onto your local Linux machine or virtual machine (VM). | |||
First, create an empty directory on which you would mount the Toolforge remote directory. In the code examples below, it is assumed that you have created a local directory at <code>~/remote</code> for this purpose. | |||
To mount, use a command like this: | |||
<pre> | |||
sshfs -o allow_other -o workaround=rename login.toolforge.org:/data/project/toolname ~/remote | |||
</pre> | |||
The <code>allow_other</code> option helps avoid permission issues, and the <code>workaround=rename</code> option helps avoid issues with overwriting existing files. | |||
To unmount, use this command: | |||
< | <pre> | ||
umount ~/remote | |||
</pre> | |||
</ | |||
In certain situations, the above command may fail to work (e.g. network issues); if you need to forcefully unmount the network file system, you can use this command: | |||
<pre> | |||
fusermount -zu ~/remote | |||
</pre> | |||
== Add a description to your Tool Account/Tool == | |||
Each tool can provide a description by creating a toolinfo record using https://toolsadmin.wikimedia.org/tools/. | |||
The legacy <code>$HOME/.description</code> system is deprecated and will stop providing any benefit at some point in the future. | |||
== Delete a Tool Account == | == Delete a Tool Account == | ||
{{Tracked|T170355}} | |||
Maintainers can | Maintainers can not delete Tool Accounts. You can delete the content of your directories and make an existing tool inaccessible by shutting down the Web service (<code>webservice stop</code>). | ||
If you want to permanently delete a Tool Account, please follow the steps described at [[phab:project/view/3975|Toolforge (Tools to be deleted)]]. It may take some time for the Tool Account to be deleted. | If you want to permanently delete a Tool Account, please follow the steps described at [[phab:project/view/3975|Toolforge (Tools to be deleted)]]. It may take some time for the Tool Account to be deleted. | ||
| Line 135: | Line 155: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
* If you are already logged in via SSH when you create | * If you are already logged in via SSH when you create a new tool, log out, and log in again to activate your new permissions. | ||
== Backup Toolforge data == | == Backup Toolforge data == | ||
There are no user-accessible backups in Toolforge. | 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. [[ | You should use a source or version control tool to preserve your code and make regular backups of data. [[Help:Toolforge/Version Control in Toolforge|Learn more]]. | ||
== See also == | == See also == | ||
Visit [[Portal:Toolforge | the Toolforge portal]] to learn more about Toolforge and to explore more how-tos, tutorials, and developer stories. | * Visit [[Portal:Toolforge|the Toolforge portal]] to learn more about Toolforge and to explore more how-tos, tutorials, and developer stories. | ||
* [[News/Toolforge.org|New toolforge.org domain]] | |||
{{:Help:Cloud Services communication}} | |||
[[Category:Toolforge| ]] | [[Category:Toolforge|Accounts]] | ||
[[Category:Documentation]] | |||
[[Category:Cloud Services]] | |||
Revision as of 03:36, 29 December 2021
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.
See Toolforge quickstart to set up and get started with Toolforge!
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://<TOOL NAME>.toolforge.org/ - 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:
- 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
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
Transfer files
You can use scp (or PuTTY) to copy files from your computer to Toolforge. To make files available to a tool account, copy or move them from your home directory to the tool's home directly:
yourshellaccountname@tools-login:~$ cp somefile ~tools.toolaccount/
Note that the tool account will have to take ownership of the file before it can use it, see below.
Take ownership of files
The take command allows you to change ownership of the file(s) and directories to the calling tool user.
The permissions of the file(s) before take is run must include the tool user as either the owner or group. This prevents take from being abused to take over arbitrary files.
To 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
Mount your tools home directory onto your local machine
Modifying files on Toolforge servers may be difficult; after all, you are restricted to terminal-based editors. If you prefer to use modern IDEs such as Visual Studio Code, Eclipse, etc. you can mount the home directory of your tool onto your local Linux machine or virtual machine (VM).
First, create an empty directory on which you would mount the Toolforge remote directory. In the code examples below, it is assumed that you have created a local directory at ~/remote for this purpose.
To mount, use a command like this:
sshfs -o allow_other -o workaround=rename login.toolforge.org:/data/project/toolname ~/remote
The allow_other option helps avoid permission issues, and the workaround=rename option helps avoid issues with overwriting existing files.
To unmount, use this command:
umount ~/remote
In certain situations, the above command may fail to work (e.g. network issues); if you need to forcefully unmount the network file system, you can use this command:
fusermount -zu ~/remote
Add a description to your Tool Account/Tool
Each tool can provide a description by creating a toolinfo record using https://toolsadmin.wikimedia.org/tools/.
The legacy $HOME/.description system is deprecated and will stop providing any benefit at some point in the future.
Delete a Tool Account
Maintainers can not 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 a new tool, log out, and log in again to activate your new permissions.
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.
- New toolforge.org domain
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 subscribed to the cloud@ mailing list