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

Portal:Toolforge/Quickstart: Difference between revisions

From Wikitech-static
Jump to navigation Jump to search
imported>Aklapper
(Move "Terms and conditions" from Help:Cloud_Services_Introduction to this page, per phab:T292811)
imported>KBach
(Page review as per phab:T307012)
 
Line 3: Line 3:
This page covers the basic steps to getting started with Toolforge.  
This page covers the basic steps to getting started with Toolforge.  


For more information and links to developer/maintainer documentation visit the [[Portal:Toolforge | Toolforge Portal]].
For more information and links to developer/maintainer documentation visit the [[Portal:Toolforge |Toolforge Portal]].


== Terms and conditions ==
==Terms and conditions==


You must review and agree to our terms and conditions. [[Help:Terminology|Account Holders]] who plan to use WMCS resources and products must read and agree to the following:
If you are an [[Help:Terminology|Account Holder]] planning to use WMCS resources and products, you must read and agree to the following:
* [[Wikitech:Cloud Services Terms of use|Wikimedia Cloud Services Terms of Use]]  
*[[Wikitech:Cloud Services Terms of use|Wikimedia Cloud Services Terms of Use]]
* [[mw:Code of Conduct|Code of Conduct for technical spaces]]
*[[mw:Code of Conduct|Code of Conduct for technical spaces]]
* [[mw:Wikimedia Labs/Agreement to disclosure of personally identifiable information|Agreement to disclosure of personally identifiable information]] (which covers [[Help:Terminology|End-Users]]).
*[[mw:Wikimedia Labs/Agreement to disclosure of personally identifiable information|Agreement to disclosure of personally identifiable information]] (which covers [[Help:Terminology|End-Users]]).
* Toolforge tools must be [[w:Open-source software|open source software]] licensed under an [http://opensource.org/licenses OSI approved license].
*Toolforge tools must be [[w:Open-source software|open source software]] licensed under an [http://opensource.org/licenses OSI approved license].
* Toolforge projects must not collect, store, or share private data or personally identifiable information, such as user names, passwords, or IP addresses, except when complying with the conditions listed in the [[Wikitech:Cloud Services Terms of use|Wikimedia Cloud Services Terms of Use]].
*Toolforge projects must not collect, store, or share private data or personally identifiable information, such as user names, passwords, or IP addresses, except when complying with the conditions listed in the [[Wikitech:Cloud Services Terms of use|Wikimedia Cloud Services Terms of Use]].


== Getting started with Toolforge - Quickstart ==
==Getting started with Toolforge - Quickstart==
<section begin=quickstart/>
<section begin="quickstart" />
# [[Help:Create a Wikimedia developer account|Create a Wikimedia developer account]].
#[[Help:Create a Wikimedia developer account|Create a Wikimedia developer account]].
# [[mw:Gerrit/Tutorial#Generate a new SSH key|Create an SSH key]] and [[Special:Preferences#mw-prefsection-openstack|add it to your Wikitech account]].
#[[mw:Gerrit/Tutorial#Generate a new SSH key|Create an SSH key]] and [[Special:Preferences#mw-prefsection-openstack|add it to your Wikitech account]].
# Submit a [https://toolsadmin.wikimedia.org/tools/membership/apply Toolforge project membership request] and wait for its approval.  
#Submit a [https://toolsadmin.wikimedia.org/tools/membership/apply Toolforge project membership request] and wait for its approval.
#* Your request will be reviewed, and you will receive confirmation within a week. You will be notified through your Wikitech user account.
#*Your request will be reviewed, and you will receive confirmation within a week. You will be notified through your Wikitech user account.
# Once you are added as a Toolforge member, you must log out and then log in again at https://toolsadmin.wikimedia.org/
# Once you are added as a Toolforge member, you must log out and then log in again at https://toolsadmin.wikimedia.org/  
#* Doing this is required for your membership to take effect.
#*Doing this is required for your membership to take effect.
# [[Portal:Toolforge/Tool Accounts|Create a new tool]] or [[Portal:Toolforge/Tool_Accounts#Join_an_existing_Tool_Account|join an existing Tool account]]
# [[Portal:Toolforge/Tool Accounts|Create a new tool]] or [[Portal:Toolforge/Tool_Accounts#Join_an_existing_Tool_Account|join an existing Tool account]].
# [[Help:Access to Toolforge instances with PuTTY and WinSCP|Access]] the Toolforge project and [[Portal:Toolforge/Tool_Accounts#Manage_files_in_Toolforge| manage files in Toolforge]].
#[[Help:Access to Toolforge instances with PuTTY and WinSCP|Access]] the Toolforge project and [[Portal:Toolforge/Tool_Accounts#Manage_files_in_Toolforge| manage files in Toolforge]].
<section end=quickstart/>
<section end="quickstart" />
=== Run new tool - Quickstart ===
===Run new tool - Quickstart===
As soon as you [[Help:Access to Toolforge instances with PuTTY and WinSCP|log in]] to username@login.toolforge.org (via ssh) and call <code>"become MY_TOOL"</code>, you get in the <code>/data/project/MY_TOOL</code> directory. This is your tool's $HOME.
When you [[Help:Access to Toolforge instances with PuTTY and WinSCP|log in]] to username@login.toolforge.org (via ssh) and call <code>"become MY_TOOL"</code>, you get in the <code>/data/project/MY_TOOL</code> directory. This is your tool's $HOME.
# Create your tool's code/html root dir: <code>mkdir public_html</code>
#Create your tool's code/html root directory: <code>mkdir public_html</code>
# Create your tool's code:
# Create your tool's code:
#* <code><nowiki>echo '<html><head></head><body>Hello world!<?php ?></body></html>' > public_html/index.php</nowiki></code>
#*<code><nowiki>echo '<html><head></head><body>Hello world!<?php ?></body></html>' > public_html/index.php</nowiki></code>
# Start the tool: <code>webservice start</code>
#Start the tool: <code>webservice start</code>
# Navigate to https://MY_TOOL.toolforge.org/ in your web browser and it should show something.
# Navigate to https://MY_TOOL.toolforge.org/ in your web browser and it should show something.


This is just an example that creates a simple PHP tool. For more details about this (and other kinds of tools), see [[Help:Toolforge/Web]] and [[Help:Toolforge/How to]]. For troubleshooting, see [[Help:Troubleshooting Toolforge]].
This is just an example that creates a simple PHP tool. For more details about this (and other kinds of tools), see [[Help:Toolforge/Web]] and [[Help:Toolforge/How to]]. For troubleshooting, see [[Help:Troubleshooting Toolforge]].


=== Manage existing tool - Quickstart ===
===Manage existing tool - Quickstart ===
As soon as you log in to login.toolforge.org (via ssh) and call <code>"become MY_TOOL"</code>, you get in the <code>/data/project/MY_TOOL</code> directory. This is your tool's $HOME. Then you can:
When you log in to login.toolforge.org (via ssh) and call <code>"become MY_TOOL"</code>, you get in the <code>/data/project/MY_TOOL</code> directory. This is your tool's $HOME. Then you can:
# Edit tool software and config files which are placed usually in any of <code>$HOME/public_html</code>, <code>$HOME/www/python</code>, <code>$HOME/www/js</code>, <code>$HOME/public_tomcat</code>, etc. For editing you can use console text editors (vi, edit, mcedit, etc.), use a version control tool like [[w:Git|Git]] or you can download/edit/upload files using [[w:Secure copy protocol|SCP]]/[[w:Secure file transfer program|SFTP]] protocol.
# Edit tool software and config files usually present in: <code>$HOME/public_html</code>, <code>$HOME/www/python</code>, <code>$HOME/www/js</code>, <code>$HOME/public_tomcat</code>, etc. For editing you can use console text editors (vi, edit, mcedit, etc.), use a version control tool like [[w:Git|Git]], or you can download, edit, or upload files using the [[w:Secure copy protocol|SCP]]/[[w:Secure file transfer program|SFTP]] protocol.
# Check if the tool is running and also its type (php/python/js/java/etc.) and selected backend (kubernetes/grid) using command: <code>webservice status</code>.
#Check if the tool is running, its type (php/python/js/java/etc.) and selected backend (kubernetes/grid) using command: <code>webservice status</code>.
# Stop the tool: <code>webservice stop</code>
#Stop the tool: <code>webservice stop</code>
# Start the tool again: <code>webservice --backend=kubernetes TYPE_OF_YOUR_TOOL start</code>
#Start the tool again: <code>webservice --backend=kubernetes TYPE_OF_YOUR_TOOL start</code>
# SSH to the tool's container: <code>webservice --backend=kubernetes TYPE_OF_YOUR_TOOL shell</code>
#SSH to the tool's container: <code>webservice --backend=kubernetes TYPE_OF_YOUR_TOOL shell</code>
{{:Help:Cloud Services communication}}
{{:Help:Cloud Services communication}}


== See Also ==
==See Also ==
* [[Portal:Toolforge]]
*[[Portal:Toolforge]]
* [[Help:Toolforge]]
*[[Help:Toolforge]]

Latest revision as of 17:18, 28 June 2022

This page covers the basic steps to getting started with Toolforge.

For more information and links to developer/maintainer documentation visit the Toolforge Portal.

Terms and conditions

If you are an Account Holder planning to use WMCS resources and products, you must read and agree to the following:

Getting started with Toolforge - Quickstart

<section begin="quickstart" />

  1. Create a Wikimedia developer account.
  2. Create an SSH key and add it to your Wikitech account.
  3. Submit a Toolforge project membership request and wait for its approval.
    • Your request will be reviewed, and you will receive confirmation within a week. You will be notified through your Wikitech user account.
  4. Once you are added as a Toolforge member, you must log out and then log in again at https://toolsadmin.wikimedia.org/
    • Doing this is required for your membership to take effect.
  5. Create a new tool or join an existing Tool account.
  6. Access the Toolforge project and manage files in Toolforge.

<section end="quickstart" />

Run new tool - Quickstart

When you log in to username@login.toolforge.org (via ssh) and call "become MY_TOOL", you get in the /data/project/MY_TOOL directory. This is your tool's $HOME.

  1. Create your tool's code/html root directory: mkdir public_html
  2. Create your tool's code:
    • echo '<html><head></head><body>Hello world!<?php ?></body></html>' > public_html/index.php
  3. Start the tool: webservice start
  4. Navigate to https://MY_TOOL.toolforge.org/ in your web browser and it should show something.

This is just an example that creates a simple PHP tool. For more details about this (and other kinds of tools), see Help:Toolforge/Web and Help:Toolforge/How to. For troubleshooting, see Help:Troubleshooting Toolforge.

Manage existing tool - Quickstart

When you log in to login.toolforge.org (via ssh) and call "become MY_TOOL", you get in the /data/project/MY_TOOL directory. This is your tool's $HOME. Then you can:

  1. Edit tool software and config files usually present in: $HOME/public_html, $HOME/www/python, $HOME/www/js, $HOME/public_tomcat, etc. For editing you can use console text editors (vi, edit, mcedit, etc.), use a version control tool like Git, or you can download, edit, or upload files using the SCP/SFTP protocol.
  2. Check if the tool is running, its type (php/python/js/java/etc.) and selected backend (kubernetes/grid) using command: webservice status.
  3. Stop the tool: webservice stop
  4. Start the tool again: webservice --backend=kubernetes TYPE_OF_YOUR_TOOL start
  5. SSH to the tool's container: webservice --backend=kubernetes TYPE_OF_YOUR_TOOL shell

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)

See Also