Help:Getting Started

From Wikitech
Jump to: navigation, search

Welcome to Wikimedia Labs! Wikimedia Labs is a virtualization cluster and hosts various virtual machines (called instances) using OpenStack Compute. This is slightly different from your normal servers that you ssh to (i.e. Toolserver), as virtual machines do not exist physically, but reside inside a much bigger machine called the host machine.

Labs contains many projects, each of which contains one or more instances.

Labs contains many projects, each of which uses one or more instances. In order to participate in labs you will need to create an account and then join a project.

If you are unsure about what to do next after visiting this site, this page will walk you through getting you started on Wikimedia Labs and start your development work!

Create a User Account

If you haven’t done so, create a user account on this wiki for yourself. This account allows you to :

  • Commit code to Wikimedia’s Git repositories via Gerrit
  • Work with Wikimedia Labs projects

Request Shell Access

Shell access to virtual machines (vm) on Wikimedia Labs gives you the ability to create new vm instances, configure them, and manage them depending on the Access Rights granted to your account and the projects you have been assigned. Shell access is granted by a Cloud Admin; please submit a request here:

  • Request Shell Access
    nb: while not necessary, if you know that you want to become part of a project or create a new project, indicate that in your request.

You can see the list of outstanding and completed requests here:

Upload your SSH key

Wikimedia Labs 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.

to Wikimedia Labs

Upload your SSH key to Wikimedia Labs. You can do so under the OpenStack tab in your Preferences.

to Wikimedia's Gerrit (Code Review)

Upload your public key to Gerrit (Wikimedia's code review tool).

  1. “Sign In” with your Wikimedia Developer Account
  2. Click “Settings” link in drop down menu under your username at page top right
  3. Click “SSH Public Keys” in left sidebar
  4. 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.

Projects

Join Projects

In order to work on Wikimedia Labs projects you need to be assigned to them. By default, you have access to the bastion project so that you can view all the other instances in Wikimedia Labs, however, you need to be assigned to a project in order to work with its instances.

Create Projects

If you need to create a new project for your development work, either drop by our IRC channel ( #wikimedia-labs channel on Freenode ) to ask for it, email the labs-l mailing list or place your request here.

  • To create instances within a project, you'll need to have a projectadmin on the project, or have an admin add you to the projectadmin role for that project. In a project you can create as many instances as you'd like. The default quota limit per-project is 10 instances, but we can increase that number as much as needed.

Project Instances

Access Project Instances

After you have received shell access, been added to or created a project and successfully added your SSH key to Wikimedia Labs and Wikimedia Code Review, read the Help:Access manual.

In short, accessing your project instances involves using either Agent Forwarding, or the ProxyCommand ssh option ( requires ssh >= 5.4 ) to connect to your instance.

Using Agent Forwarding

from your local computer

eval `ssh-agent`
ssh-add ~/.ssh/your_key_file_for_labs
ssh -A <username>@bastion.wmflabs.org

#once in bastion
ssh <instancename>.eqiad.wmflabs

#or
ssh <instancename>

Using ProxyCommand

Generally, using the ProxyCommand ssh option would allow you to directly connect to your instance, skipping the portion about having to login to the bastion host and then logging in to your instance. If you have followed the steps given to set up the ProxyCommand ssh option, then this is the general command to use to login to your instance in the Terminal:
from your local computer

ssh <instancename>.eqiad.wmflabs

The instance name is given in the "Instance name" column in Special:NovaInstance, or the first-left column of that page. Logging in to the instance is just like logging in to another computer. 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.

You can also make queries for nova resources in order to get more information about current project instances; currently only Nova instances have semantic properties enabled.

See Help:Putty for using PuTTY with Windows.

Create Project Instances

see Help:Instances

Configure Project Instances

see Help:Instances#Configuring_Instances

Log your actions

Wikimedia Labs 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-labs connect channel on Freenode by using the following command:

!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.

Read the documentation and rules

Git committers

If you are just simply getting an account for committing into Gerrit, read some detailed documentation about it

  • Help:Git - (somewhat) complete documentation of using Gerrit
  • Git workflow - A lengthy page detailing all aspects of committing into Gerrit and using it.
  • Help:Git_rebase - Because the importance of using fetch and rebase (instead of pull or merge) can't be over-emphasized.

Further help

If you encounter any problems, drop by our IRC channel at #wikimedia-labs connect on Freenode. Happy hacking!