You are browsing a read-only backup copy of Wikitech. The primary site can be found at wikitech.wikimedia.org

User:SRodlund/Tool accounts (staging): Difference between revisions

From Wikitech-static
Jump to navigation Jump to search
imported>SRodlund
 
imported>SRodlund
No edit summary
 
Line 27: Line 27:
== What is a Tool Account? ==
== What is a Tool Account? ==


The Tool Account is a group account which can have one or more maintainers at a time. 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.
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:
Each Tool Account includes:
* A home directory on shared storage: <code>/data/project/&lt;TOOL NAME&gt;</code>
* A home directory on shared storage: <code>/data/project/&lt;TOOL NAME&gt;</code>
* The ability to run a [[Help:Toolforge/Web|web service]] which is visible at <code><nowiki>https://tools.wmflabs.org/&lt;TOOL NAME&gt;/</nowiki></code>
* The ability to run a [[Help:Toolforge/Web|web service]] which is visible at <code><nowiki>https://tools.wmflabs.org/&lt;TOOL NAME&gt;/</nowiki></code>
Line 36: Line 37:
* Credentials and a namespace for running containers on the [[Help:Toolforge/Kubernetes|Kubernetes cluster]]
* Credentials and a namespace for running containers on the [[Help:Toolforge/Kubernetes|Kubernetes cluster]]


== Roles ==
== Maintainers ==


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


The Tool Account is a group account which can have one or more maintainers at a time. The Tool Account exists independently of its maintainers, which makes it easy for individuals of the group to come and go.
Maintainers can:
 
=== Maintainers ===
 
People who have access to a Tool Account are called ''maintainers'' Maintainers have access to tool account's code and data. Maintainers can:


* create Tool Accounts/tools
* create Tool Accounts/tools
Line 52: Line 49:


== 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]]. If you would like to be added to an existing account, you must contact the maintainer(s) directly.


If you would like to add (or remove) maintainers to a tool account that you manage, you may do so with the 'manage maintainers' link found beneath the tool name on the Toolforge home page.  
All Tool Accounts hosted in Toolforge are listed on the [[toolforge:admin/tools|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
* Include screenshot  


== Create tools with Tool Accounts ==
== Create tools with Tool Accounts ==
* Include screenshots
* Include screenshots
* Link to info about picking a license: https://choosealicense.com/ (and info about license)
* Link to info about picking a license: https://choosealicense.com/ (and info about license)
Line 65: Line 68:
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 (if you don't see this and you were recently added to the 'tools' project, try to logoff and login again)
# 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
#* The new tool will need a unique name. The name will become part of the URL for the final webservice, so choose wisely!
# Once the Tool Account is created, log off, then back in before you can access the new tool account


Do ''not'' prefix your tool name with <code>tools.</code>. The system will do so automatically where appropriate, and there is a known issue that will cause the account to be created improperly if you do.
== Naming a Tool Account/tool ==


:'''Note:''' If you have only recently been added to the 'tools' project, you may get an error about not being a member. Simply log out and back in to toolsadmin to fix this.
The Tool Account and tool will have the same name. This name will be included in the URL for the final webservice.


The Tool account will be created and you will be granted access to it within a minute or two. If you were already logged in to a Toolforge bastion through SSH, you will have to log off then back in before you can access the new tool account.
* Make sure the name is appropriate and spelled correctly.
* Do ''not'' prefix your tool name with <code>tools.</code>. This will cause the account to be created improperly if you do.


== Using a Tool account ==
== Rename a Tool Account ==
A simple way for maintainers to switch to the tool account is with <code>become</code>:
 
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 ==
 
<code>become</code>:
<syntaxhighlight lang="shell-session">
<syntaxhighlight lang="shell-session">
maintainer@tools-login:~$ become <TOOL NAME>
maintainer@tools-login:~$ become <TOOL NAME>
Line 83: Line 92:
</syntaxhighlight>
</syntaxhighlight>


== Customize a Tool account ==
== Delete a Tool Account ==
Once you have created a tool account, there are a few things that you can customize to make the tool more easily understood and used by other users. These include:


* Adding a tool account description (the description will appear on the Tools home page beside the tool name)
{{tracked|T170355}}
* Creating a web page for your tool (it will be linked from the Tools home page automatically)
 
=== Create a Tool web page ===
{{See also|Help:Toolforge/Web}}
To create a web page for your tool account, simply place an index.html file in the tool account's <tt>~/public_html/</tt> directory.  The page can be a simple description of the tool or bot with basic information on how to set it up or shut it down, or it contain an interface for the web service. To see examples of existing tool web pages, click any of the linked tool names on the [https://tools.wmflabs.org?list Tools list].
 
Note that some files, such as PHP files, will give a 500 error unless the owner of the file is tool account.
 
You will also need to start a webservice for your tool.
 
1. Log into the Tool environment and become your tool account:
 
<syntaxhighlight lang="bash">maintainer@tools-login:~$ become toolname</syntaxhighlight>
 
2. Start the web service:
 
<syntaxhighlight lang="bash">tools.toolname@tools-login:~$ webservice start</syntaxhighlight>
 
=== {{anchor|create-description}} Creating a Tool description ===
To create a tool description:
 
1. Log into a Toolforge bastion using your Wikimedia developer account and become your tool account:
 
<syntaxhighlight lang="bash">
$ ssh tools-login.wmflabs.org
maintainer@tools-login:~$ become toolname
</syntaxhighlight>


2. Create a <code>.description</code> file in the tool account’s home directory. Note that this file must be HTML:
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 (<code>webservice stop</code>).  If you really want a tool account to be deleted, please file a [https://phabricator.wikimedia.org/maniphest/task/create/?projects=Toolforge&parent=T133777&title=Delete+tool+MY_TOOL_NAME task in Phabricator] requesting that the  
 
tool be deleted eventually.
<syntaxhighlight lang="bash">
tools.toolname@tools-login:~$ vim .description
</syntaxhighlight>
 
3. Add a brief description (no more than 25 words or so) and save the file. You can use basic HTML markup in the file.
 
4. Navigate to the [https://tools.wmflabs.org/admin/tools Tools list]. Your tool account description should now appear beside your tool account name.
 
=== Configuring Tools ===
Tools and bot code should be stored in your tools account, where it can be managed by multiple users and accessed by all execution hosts. Specific information about configuring [[#Web server|web services]] and [[Help:Toolforge/Developing|bots]], along with information about licensing, package installation, and shared code storage, is available at the {{section link||Developing on Toolforge}} section.
 
Note that bots and tools should be run via the grid, which finds a suitable host with sufficient resources to run each. Simple, one-off jobs can be submitted to the grid easily with the [[#Submitting, managing and scheduling jobs on the grid|jsub command]]. Continuous jobs, such as bots, can be submitted with [[#Submitting, managing and scheduling jobs on the grid|jstart]].


==Troubleshoot your new Tool Account ==
==Troubleshoot your new Tool Account ==
Line 145: Line 114:
</syntaxhighlight>
</syntaxhighlight>
* 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.
* 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.
== 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.
== Delete a Tool Account ==
{{tracked|T170355}}
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 (<code>webservice stop</code>).  If you really want a tool account to be deleted, please file a [https://phabricator.wikimedia.org/maniphest/task/create/?projects=Toolforge&parent=T133777&title=Delete+tool+MY_TOOL_NAME task in Phabricator] requesting that the tool be deleted eventually.


{{:Help:Cloud Services communication}}
{{:Help:Cloud Services communication}}


[[Category:Toolforge| ]]
[[Category:Toolforge| ]]

Latest revision as of 23:35, 6 August 2019

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

Screenshot about creating a new tool..png

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

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:

Discuss and receive general support
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 the Phabricator workboard #Cloud-Services for bug reports and feature requests about the Cloud VPS 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)