|Please read the Wikimedia Cloud Services Introduction.|
- 1 Overview
- 2 Step 1: Create an LDAP account
- 3 Getting started with Toolforge
- 4 Getting started with VPS Projects
- 5 Read the documentation and Rules
- 6 Help and Participation
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.
This guide will teach you to:
- Create an LDAP account for Toolforge, VPS, and general users
- Begin using Gerritt for code review
- Access an existing project or begin a new project
Step 1: Create an LDAP account
Most of Wikimedia's technical spaces use LDAP. An LDAP account is required to:
- Edit this wiki
- Work with Cloud VPS Projects
- Request access to Toolforge
- Login to the Cloud VPS management console (Horizon)
- Login to the bug tracking system used for Wikimedia projects (Phabricator)
- Commit code to Wikimedia’s Git repositories via our code review system (Gerrit)
- Access other protected Wikimedia services, after signing a Volunteer NDA and being approved for access.
Creating an account
- Use the Toolforge admin console to create a new LDAP account.
- Fill out an access request to join the Toolforge project.
- 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 Wikitech account using the Preferences > OpenStack tab or Toolforge admin console.
- Wait for your access request for the Tools project to be processed (you should receive messages on your Wikitech talk page).
After account creation
- Use SSH to login to Toolforge. In a command-line terminal, enter: ssh -i ~/.ssh/id_rsa email@example.com (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 Putty.
- Use SSH-based utilities such as scp and sftp to transfer files between Toolforge and your computer.
- Access MySQL from SSH (e.g. sql enwiki is a shortcut command to connect to the copy of English Wikipedia)
- Create tools (see Help:Toolforge § Creating a new Tool account).
- Your LDAP username and your shell login username may be different. Visit Settings > Linked accounts in the Toolforge admin console and check your "Shell account name".
- The passwords you chose for your LDAP account and SSH key may be different.
- When you login with SSH you are in your personal folder. To quickly go to your tool account enter: become tool_name
- 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:
$ become TOOL_NAME $ chmod --recursive g+rw .
- The web service for your tool is not started by default. To start it enter: webservice start
- When doing file system intensive tasks (like
git clone), it may be useful to perform the task on a host-local filesystem (like
/tmp) to avoid the speed penalty of NFS. For example, cloning git repositories in
/tmpand 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
screen. Note that screen needs to be run before
become TOOL_NAME. Screen should not be used to run long running scripts. These should be run as grid jobs instead.
- You might need to use
ssh-addon your local computer after creating a new key.
Using multiple ssh agents
If you use multiple ssh-agents (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
Creating an account
Create an LDAP account on Wikitech using the account creation form.
Uploading an SSH key
Wikimedia Cloud Services products and Wikimedia Code Review use an SSH key to authenticate you. If you already have an SSH key you can use that one, or generate a new one specifically for Wikimedia use; the default public key name generated by ssh-keygen is typically id_rsa.pub.
See Also: SSH Help
You can test your key by attempting to connect to the
bastion VPS project:
ssh -v bastion.wmflabs.org.
| You will only be able to ssh to
Uploading your key to Wikimedia's Gerrit (Code Review)
Upload your public key to 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.
If you are just simply getting an account for committing into Gerrit, read some detailed documentation about it
- mw:Gerrit - mediawiki.org's guide to using Gerrit
- Help:Git rebase - Because the importance of using fetch and rebase (instead of pull or merge) can't be over-emphasized.
Getting started with Toolforge
Requests for access are generally dealt with within the day (often faster), though response-time may be longer depending on admin availability. If you need immediate assistance, please contact us on the #wikimedia-cloud connect IRC channel.
Receiving access to the 'tools' project
Once your 'tools' project access request has been processed, you will become a member of the Toolforge Cloud VPS project, and will be able to access it using the "Instance shell account name" provided when creating your LDAP 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.
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!
Getting started with VPS Projects
Join a Project
In order to work on Cloud VPS projects you need to be granted membership in them by a project administrator.
- Find the project you wish to join using OpenStack browser.
- To join Toolforge, see the instructions in 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 http://tools.wmflabs.org/openstack-browser/project/<project-name>
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 #wikimedia-cloud connect 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.
Request creation of a new Project
If you need to create a new project go to the "Cloud-VPS (Project-requests)" phabricator task and follow the instructions it provides.
To create instances within a project, see Help:Instances
Access Project Instances
Using ProxyCommand for SSH
The easiest way to access your project instance is using the
ProxyCommand ssh option to directly connect to your instance.
- Follow the steps at set up the ProxyCommand ssh option first
- Connect to your instance using the following command from your local computer
$ ssh <instance-name>.<project-name>.eqiad.wmflabs
See Help:Putty for using PuTTY with Windows.
Configuring Project 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 #wikimedia-cloud connect channel on Freenode by using the sending a message like:
!log <projectname> <message>
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
- 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