Help:Getting Started: Difference between revisions

From Wikitech
Browse history interactively
← Older editNewer edit →
Content deleted Content added
VisualWikitext
Use "developer account" term per phab:T179461
Simplifying page -- more changes to follow.
Line 5: Line 5:
==Overview==
==Overview==


Cloud Services provides tools, services, and support for technical collaborators who want to contribute to Wikimedia software projects. This page outlines basic first steps to making contributions to this wiki and Wikimedia's technical spaces.
Cloud Services provides tools, services, and support for technical collaborators who want to contribute to Wikimedia software projects. This page outlines basic first steps to making contributions to this wiki and Wikimedia's technical spaces, including:


* Toolforge
'''This guide will teach you to:'''
* Cloud VPS
* Gerrit


You will learn how to:
* Create a Wikimedia developer account for Toolforge, Cloud VPS, and general use
* Begin using Gerrit for code review
* Access an existing project or begin a new project


* Join an existing project or begin a new project.
=={{anchor|Create_a_User_Account}} Step 1: Create a Wikimedia developer account==
* Create and configure instances within a project.
* Add members or admins to projects.
* Use and troubleshoot SSH for Cloud Services projects.
* Find help and ways to participate.


== Prerequisites ==
Most of Wikimedia's technical spaces use a Wikimedia developer account. A developer account is required to:


To access and contribute to Cloud Services projects and tools, you will need the following accounts. Please note, these are two distinct accounts:
* Edit this wiki
* Work with [[toollabs:openstack-browser/project/|Cloud VPS Projects]]
* Request access to [[Portal:Toolforge|Toolforge]]
* Login to [https://horizon.wikimedia.org/auth/login/?next=/ the Cloud VPS management console (Horizon)]
* Login to [[phab:| the bug tracking system used for Wikimedia projects (Phabricator)]]
* Commit code to Wikimedia’s [[w:Git_(software)|Git]] repositories via [[w:Gerrit_(software)|our code review system (Gerrit)]]
* Access other protected Wikimedia services, after signing a [[Volunteer NDA]] and being approved for access.


* Wikimedia account - this account is used to contribute to Wikipedia and its sister projects.
==={{anchor|Tools Users}} Toolforge users ===
** When you create your Wikimedia account, you will create a username and password.
==== Creating an account ====
* [[Help:Create_a_Wikimedia_developer_account|Wikimedia developer account]] - this account is used to log into this wiki, Toolforge, Cloud VPS, Gerrit and other protected Wikimedia Services.
# Use the '''Toolforge admin console''' to [https://toolsadmin.wikimedia.org/register/ create a new developer account].
#* Make careful note of the ''LDAP username'' and ''UNIX shell username'' you choose
** When you create your Wikimedia developer account, you will create a username (sometimes called LDAP username), UNIX shell username, and password.
#** Your LDAP username and password will be used to login here on Wikitech and on [[:mw:Gerrit|Gerrit]] and the [https://toolsadmin.wikimedia.org/ Toolforge admin console].
#** Your shell name will be used when you interact with servers via [[Help:Access|ssh]] and when using [[:mw:Gerrit/Getting_started|git with Gerrit]].
# [https://toolsadmin.wikimedia.org/tools/membership/apply Fill out an access request to join the Toolforge project].
# [[:mw:Gerrit/Tutorial#Generate_a_new_SSH_key|Generate an SSH key]] that you will use along with your ''shell'' account name to log into the Toolforge servers if you do not already have one.
# Associate your SSH public key with your developer account using the [[Special:Preferences#mw-prefsection-openstack|Preferences > OpenStack tab]] or [https://toolsadmin.wikimedia.org/profile/settings/ssh-keys Toolforge admin console].
# Wait for your access request for the Tools project to be processed (you should receive messages on your [[Special:MyTalk | Wikitech talk page]]).


==== After account creation ====
== Get started with Toolforge ==
* Use SSH to login to Toolforge. In a command-line terminal, enter: <kbd>ssh -i ~/.ssh/id_rsa ''username''@login.tools.wmflabs.org</kbd> (''username'' is the "Instance ''shell'' account name" you specified when you created an account. If you are running Windows you will need to use an ssh client like [[Help:Access to Toolforge instances with PuTTY and WinSCP|puTTY]].
* Use SSH-based utilities such as scp and sftp to transfer files between Toolforge and your computer.
* Access MySQL from SSH (e.g. <kbd>sql enwiki</kbd> is a shortcut command to connect to the copy of English Wikipedia)
* Create tools (see {{section link|Help:Toolforge|Creating a new Tool account}}).


# Submit a [https://toolsadmin.wikimedia.org/tools/membership/apply Toolforge project membership request].
==== Common issues ====
# Wait for membership approval.
* Your LDAP username and your shell login username may be different. Visit [https://toolsadmin.wikimedia.org/profile/settings/accounts Settings > Linked accounts in the Toolforge admin console] and check your "Shell account name".
#* Your request will be reviewed, and you will receive confirmation within a week. You will be notified through your Wikitech user account that you have been added to the project [[Nova Resource:Tools]].
* The passwords you chose for your developer account and SSH key may be different.
# Access the Toolforge project.
* When you login with SSH you are in your personal folder. To quickly go to your tool account enter: <kbd>become ''tool_name''</kbd>
#* Use your "UNIX shell username" provided when creating your developer account and the SSH private key matching the public key you supplied for authentication.
* If you login with WinSCP you will transfer files as yourself, not as your tool. The UNIX group for both accounts is the same so you can make files editable by all maintainers of the tool with:
:<syntaxhighlight lang="shell-session">
$ become TOOL_NAME
$ chmod --recursive g+rw .
</syntaxhighlight>
* The web service for your tool is not started by default. To start it enter: <kbd>webservice start</kbd>
* When doing file system intensive tasks (like <code>git clone</code>), it may be useful to perform the task on a host-local filesystem (like <code>/tmp</code>) to avoid the speed penalty of NFS. For example, cloning git repositories in <code>/tmp</code> and then moving it to the location you actually need it in can be much faster than cloning it in the original location.
** Note: the speed penalty can be severe. For example, running ''wc -l'' on a 285 MB text file took 0:01 on /tmp and 3:14 over NFS.
* If you need to use the server for a long time, and want to execute a task even when you're not connected to the ssh, you can use <code>screen</code>. Note that screen needs to be run before <code>become TOOL_NAME</code>. Screen '''should not''' be used to run long running scripts. These should be [[Help:Toolforge/Grid|run as grid jobs]] instead.
* You might need to use <code>ssh-add</code> on your local computer after creating a new key.


For more information about accessing the project, please see
==== Using multiple ssh agents ====
[[Help:Toolforge#Using_Toolforge_and_managing_your_files|Using Toolforge and managing your files]].
If you use multiple <tt>ssh-agent</tt>s (to connect to your personal or company system, for example), see [[SSH access]] for more information about setting up a primary and a Cloud VPS agent.


=== VPS and General Users ===
== Get started with Cloud VPS Projects ==
==== Creating an account ====
Create a Wikimedia developer account on Wikitech [https://wikitech.wikimedia.org/w/index.php?title=Special:UserLogin&returnto=Help%3AGetting+Started&type=signup using the account creation form].


=== Create a new project ===
==== Uploading an SSH key {{anchor|Upload_your_SSH_key}} ====
Wikimedia Cloud Services products and [[gerrit:|Wikimedia Code Review]] use an [[w:Secure_Shell|SSH key]] to authenticate you. If you already have an SSH key you can use that one, or [[mw:Git/Tutorial#Set_Up_SSH_Keys_in_Gerrit|generate a new one]] specifically for Wikimedia use; the default public key name generated by [[w:Ssh-keygen|ssh-keygen]] is typically <tt>id_rsa.pub</tt>.


# Follow the instructions on the [[phab:project/view/2875/|"Cloud-VPS (Project-requests)" phabricator task]].
Upload the generated public key from the [[Special:Preferences#mw-prefsection-openstack|'{{MediaWiki:Prefs-openstack}}' tab in your Preferences]] '''or''' use [https://toolsadmin.wikimedia.org/profile/settings/ssh-keys the toolsadmin interface].


=== Join an existing project ===
See Also: [[Help:SSH|SSH Help]]


# Choose a project to join with [[toollabs:openstack-browser/|OpenStack browser]].
You can test your key by attempting to connect to the <code>bastion</code> VPS project: <code>ssh -v bastion.wmflabs.org</code>.
# Request membership by [[phab: maniphest/task/edit/form/1/ | creating a Phabricator task]] and assigning it directly to the project administrator(s).
#*You can find the list of project admins by going to <kbd><nowiki>http://tools.wmflabs.org/openstack-browser/project/<project-name></nowiki></kbd>.


=== Add members and admin users to a project ===
{{note|You will only be able to ssh to <code>bastion</code> '''after''' you have been added as a member of at least one VPS project (e.g. Toolforge). Users can verify their project membership via OpenStack Browser at <code>https<nowiki>:</nowiki>//tools.wmflabs.org/openstack-browser/user/<shellname></code>}}


Project admins can use the following steps to add new members or grant administrative permissions to members.
==== Uploading your key to Wikimedia's Gerrit (Code Review) ====
Upload your public key to [https://gerrit.wikimedia.org Gerrit (Wikimedia's code review tool)].
# “Sign In” with your Wikimedia Developer Account
# Click “Settings” link in drop down menu under your username at page top right
# Click “SSH Public Keys” in left sidebar
# Paste your public key into the text field and click “Add” button. Thereafter, the form presents "Add key ..." button instead, for if you have more keys you want to add.


# Go to [[Special:NovaProject]].
=== Gerrit/Git committers ===
# Use '''Add member''' link to add new members.
If you are just simply getting an account for committing into [[w:Gerrit_(software)|Gerrit]], read some detailed documentation about it
# Use '''Add member''' link for the '''projectadmin''' role in the '''Role''' column.
* [[mw:Gerrit]] - mediawiki.org's guide to using Gerrit
#* Log at {{irc|wikimedia-cloud}} that you added/granted admin to the member.
* [[Help:Git rebase]] - Because the importance of using fetch and rebase (instead of pull or merge) can't be over-emphasized.


=== Project Instances ===
== Getting started with Toolforge ==
=== Requesting access ===
Once you have created a developer account, you must request access to the [[Portal:Toolforge|Toolforge]] project by submitting a [https://toolsadmin.wikimedia.org/tools/membership/apply Toolforge project membership request].


To learn more about project instances, read the [[Help:Instances|project instances documentation]].
Requests for access are generally dealt with within days, though response-time may be longer depending on admin availability. If you need immediate assistance, please contact us on the {{freenode|wikimedia-cloud}} IRC channel.


=== Receiving access to the 'tools' project ===
=== Log your actions ===
Once your 'tools' project access request has been processed, you will become a member of the [[Portal:Toolforge|Toolforge]] Cloud VPS project, and will be able to access it using the "UNIX shell username" provided when creating your developer account and the SSH private key matching the public key you supplied for authentication. For more information about accessing the project, please see [[Help:Toolforge#Using_Toolforge_and_managing_your_files|Using Toolforge and managing your files]].


It is best practice to log changes to all instances of your project.
You will be notified on Wikitech that your user rights were changed and that you have been added to the project [[Nova Resource:Tools]]. In other words, your Toolforge account is ready for you to use!


Wikimedia Cloud Services provides a [[Server Admin Log]] for users to log their project server administration actions on.
== Getting started with VPS Projects ==
=== Join a Project ===
In order to work on a Cloud VPS project you need to be granted project membership by a project administrator.


You can add a log entry in the {{irc|wikimedia-cloud}} channel on [[:en:Freenode|Freenode]] by using the sending a message like: <code>!log <projectname> <message></code>
* Find the project you wish to join using [[toollabs:openstack-browser/|OpenStack browser]].
** To join Toolforge, see the instructions in [[Help:Getting Started#Getting_started_with_ToolForge|Getting started with Toolforge]]
** If you want to join another project, ask a project administrator for that project. You can find the list of project admins by going to <kbd><nowiki>http://tools.wmflabs.org/openstack-browser/project/<project-name></nowiki></kbd>


See [[Tool:Stashbot]] for more information.
=== Add members and admin users to a Project ===
* Project admins can go to [[Special:NovaProject]] and add people by clicking the 'Add member' link.
* Project admins can also grant other members admin rights from the [[Special:NovaProject]] page by clicking the 'Add member' link for the 'projectadmin' role in the Role column.
* Log at {{irc|wikimedia-cloud}} that you added/granted admin to the user. See [[Help:Getting Started#Log_your_actions]] for how to add to the admin log from irc.


== Help ==
=== Request creation of a new Project ===
If you need to create a new project go to the [[phab:project/view/2875/|"Cloud-VPS (Project-requests)" phabricator task]] and follow the instructions it provides.


# Use the Wikimedia Cloud Services [[Help:IRC|IRC channel]] at {{irc|wikimedia-cloud}} on [[:en:Freenode|Freenode]].
=== Project Instances ===
# Use the keyword <kbd>!help</kbd>.
==== Creating Instances ====
To create instances within a project, see [[Help:Instances]]


==== Access Project Instances ====
== Learn more ==
After you have been [[#Projects|added to or created a project]] and successfully [[#Upload_your_SSH_key|added your SSH key]] to Wikitech and Gerrit, read the [[Help:Access]] manual.

===== Using ProxyCommand for SSH =====
The easiest way to access your project instance is using the <code>ProxyCommand</code> ssh option to directly connect to your instance.

* Follow the steps at [[Help:Access#Accessing_instances_with_ProxyCommand_ssh_option_.28recommended.29|set up the ProxyCommand ssh option]] first
* Connect to your instance using the following command from your local computer
:<syntaxhighlight lang="shell-session">
$ ssh <instance-name>.<project-name>.eqiad.wmflabs
</syntaxhighlight>

The instance name is given in the "Instance name" column in [[Special:NovaInstance]]. Logging in to the instance is just like logging into any computer using SSH. You have complete root access to it, and you can install relevant programs that benefit your project's purpose, and do work that comply with our Terms of Use.

See [[Help:Putty]] for using PuTTY with Windows.

==== Configuring Project Instances ====
See [[Help:Instances#Configuring_Instances]]

=== Log your actions ===
WMCS provides a [[Server Admin Log]] which all users can log their project server administration actions on. You can add a log entry in the {{irc|wikimedia-cloud}} channel on [[:en:Freenode|Freenode]] by using the sending a message like: <code>!log <projectname> <message></code>

It's best to log all changes to the instances in your project. Doing so makes it easier for others to follow your progress, and to more easily join your project and help out. See [[Tool:Stashbot]] for more information.


== Read the documentation and Rules ==
== Read the documentation and Rules ==
Line 147: Line 86:
* [[Help:Rules]] - rules you need to follow when using Wikimedia Cloud Services projects
* [[Help:Rules]] - rules you need to follow when using Wikimedia Cloud Services projects
* [[mw:Code of Conduct|Code of Conduct]] - code of conduct for Wikimedia technical spaces
* [[mw:Code of Conduct|Code of Conduct]] - code of conduct for Wikimedia technical spaces

== Help and Participation ==
If you encounter any problems, drop by our [[Help:IRC|IRC channel]] at {{irc|wikimedia-cloud}} on [[:en:Freenode|Freenode]]. Use the keyword <kbd>!help</kbd> to call attention.


Join our mailing lists: [https://lists.wikimedia.org/mailman/listinfo/cloud-announce announcements], and [https://lists.wikimedia.org/mailman/listinfo/cloud discussion].
Join our mailing lists: [https://lists.wikimedia.org/mailman/listinfo/cloud-announce announcements], and [https://lists.wikimedia.org/mailman/listinfo/cloud discussion].

Revision as of 19:10, 10 April 2018

Overview

Cloud Services provides tools, services, and support for technical collaborators who want to contribute to Wikimedia software projects. This page outlines basic first steps to making contributions to this wiki and Wikimedia's technical spaces, including:

  • Toolforge
  • Cloud VPS
  • Gerrit

You will learn how to:

  • Join an existing project or begin a new project.
  • Create and configure instances within a project.
  • Add members or admins to projects.
  • Use and troubleshoot SSH for Cloud Services projects.
  • Find help and ways to participate.

Prerequisites

To access and contribute to Cloud Services projects and tools, you will need the following accounts. Please note, these are two distinct accounts:

  • Wikimedia account - this account is used to contribute to Wikipedia and its sister projects.
    • When you create your Wikimedia account, you will create a username and password.
  • Wikimedia developer account - this account is used to log into this wiki, Toolforge, Cloud VPS, Gerrit and other protected Wikimedia Services.
    • When you create your Wikimedia developer account, you will create a username (sometimes called LDAP username), UNIX shell username, and password.

Get started with Toolforge

  1. Submit a Toolforge project membership request.
  2. Wait for membership approval.
    • Your request will be reviewed, and you will receive confirmation within a week. You will be notified through your Wikitech user account that you have been added to the project Nova Resource:Tools.
  3. Access the Toolforge project.
    • Use your "UNIX shell username" provided when creating your developer account and the SSH private key matching the public key you supplied for authentication.

For more information about accessing the project, please see Using Toolforge and managing your files.

Get started with Cloud VPS Projects

Create a new project

  1. Follow the instructions on the "Cloud-VPS (Project-requests)" phabricator task.

Join an existing project

  1. Choose a project to join with OpenStack browser.
  2. Request membership by creating a Phabricator task and assigning it directly to the project administrator(s).
    • You can find the list of project admins by going to http://tools.wmflabs.org/openstack-browser/project/<project-name>.

Add members and admin users to a project

Project admins can use the following steps to add new members or grant administrative permissions to members.

  1. Go to Special:NovaProject.
  2. Use Add member link to add new members.
  3. Use Add member link for the projectadmin role in the Role column.

Project Instances

To learn more about project instances, read the project instances documentation.

Log your actions

It is best practice to log changes to all instances of your project.

Wikimedia Cloud Services provides a Server Admin Log for users to log their project server administration actions on.

You can add a log entry in the #wikimedia-cloud connect channel on Freenode by using the sending a message like: !log <projectname> <message>

See Tool:Stashbot for more information.

Help

  1. Use the Wikimedia Cloud Services IRC channel at #wikimedia-cloud connect on Freenode.
  2. Use the keyword !help.

Learn more

Read the documentation and Rules

  • Help:Contents - help table of contents
  • Help:Access - contains information on how to access lab instances
  • Help:Rules - rules you need to follow when using Wikimedia Cloud Services projects
  • Code of Conduct - code of conduct for Wikimedia technical spaces

Join our mailing lists: announcements, and discussion.

Retrieved from "https://wikitech.wikimedia.org/w/index.php?title=Help:Getting_Started&oldid=1788064"