How to Set Up Your Python Development

Environment on

Ubuntu 14.04

Prepared By: Stephanie Chan, John Dennert, & Anastasia Khudoyarova

Last Edited: July 30, 2014

Version: 1.1

1

Table of Contents

Introduction 3

Formatting Conventions Used 4

Prerequisites 5

Set Up Process 6

● Open the terminal 6

● Check your Python installation 6

● Set up your virtual environment 7

● Setup version control 9

● Set up SSH with Github 9

● Run the code 11

Summary 13

Troubleshooting 14

Additional Resources 15

2

Introduction

The following instructions detail how to set up a Python development

environment on Ubuntu 14.04. As a new software engineer at the company, this

knowledge will give you the initial setup necessary to begin contributing and

learning about the technologies we use.

Although these instructions strive to be as thorough as possible, it is not

intended to be a comprehensive tutorial for the wide variety of tools and knowledge

required to start contributing code. Instead, we will link to various other resources

throughout the instructions should you require more background information on

certain topics. However, reading the additional resources will not be necessary to

complete these instructions.

3

Formatting Conventions Used

We use a number of different visuals throughout the instructions. This section

will explain each visual and how to use them.

● Keystrokes are shown in the following format: CTRL+ALT+T

● Commands that are typed in the terminal window are shown in the

dark sections with white text. The commands can be copied and

pasted from these sections.

$ python

● Tips and other resources are shown in the sections with light bulbs. They will provide additional information and warnings.

●

●●

● Screenshots will have a figure number and a caption describing its contents.

Figure 1: The Python interactive shell showing Python version 2.7.6

● Yellow text should be replaced with your information (name, e-mail

address, etc.).

4

This is a tip.

Prerequisites

● A clean installation of Ubuntu 14.04

● Minimal programming experience and moderate computer proficiency

Ubuntu is a Debian-based Linux operating system. Although experience with Ubuntu is not necessary to complete these

instructions, you may choose to familiarize yourself with it on their website: http://www.ubuntu.com/

5

Set Up Process

● Open the terminal

To open the terminal, press the following keys: CTRL+ALT+T

Alternatively, you can open the terminal through the GUI. Go to the sidebar

and click the Unity button on the side bar. In the search prompt, type

"terminal". It will bring up the Terminal icon under "Applications". Click

the icon to open the terminal.

Learning to use the command line can be tricky and can take a while to get really good at it. However, learning even the basics can significantly boost your productivity. For a good command line tutorial visit:

http://cli.learncodethehardway.org/book/

● Check your Python Installation

○ Python should already be installed by default with your operating

system. We will be using Python version 2.7.6 but any 2.x.x version will

work. To check the default version of Python currently installed, type

the following command in the terminal:

$ python

This command will launch the Python interactive shell which shows the

default version of Python installed. The output should look similar to

Figure 1 below:

6

Figure 1: The Python interactive shell showing Python version 2.7.6

○ To close the Python interactive shell, type:

>>>

exit()

To learn more about Python, visit: http://www.python.org and check out the official documentation.For a great tutorial that covers Python from the ground up, visit: http://learnpythonthehardway.org/

● Set up your virtual environment

When working on multiple projects, it is important to keep your Python

installations separate for each project. One project might use one version of a

package while another project might use another version of the same

package. This would be a problem if you just had one version of the package

installed globally that all of the projects used. Instead, you will use what’s

called a virtual environment.

○ Install pip

pip is a tool we will use to install and manage Python packages. To

install pip, type:

$ sudo apt-get install -y python-pip

Now we can start installing Python packages.

Installing software requires root permissions. sudo is a commonly used tool for granting users other than root permissions to do things like install software. You will be prompted for the same password you use to log into your

7

Ubuntu user account. You will not be asked for your password again when using sudo if you have used it in the last 5 minutes.

○ Install virtualenv and virtualenvwrapper

virtualenv is a Python package that allows us to create self-contained

virtual environments in which we can install packages without

conflicting with other environments on our system. virtualenvwrapper

is another package that adds additional functionality to virtualenv in

order to make it easier to use.

■ To install virtualenvwrapper, which will also install virtualenv,

type:

$ sudo pip install virtualenvwrapper

■ Then, we need to set some environment variables to tell

virtualenvwrapper where to store, find, and run information.

Open up ~/.bashrc by typing:

$ gedit ~/.bashrc

gedit is simple text editor to use, but it is not fully featured. Consider getting familiar with a more robust text editor like Emacs (http://www.gnu.org/software/emacs/) or Vim (http://www.vim.org/).

The .bashrc file contains all the configuration settings for the terminal. Any settings added to this file will be loaded every time you open a terminal window.

■ At the end of the file, add the following lines:

$$$

export WORKON_HOME=~/Envsmkdir -p $WORKON_HOMEsource /usr/local/bin/virtualenvwrapper.sh

8

■ Save the file by pressing CTRL+S. Close the file. Then, reload the

terminal window by typing:

$ source ~/.bashrc

○ Start a virtualenv

■ To create a new virtualenv, type:

$ mkvirtualenv test_env

■ The command line should now be prefaced with (test_env),

indicating that you’re working inside a virtual environment.

Figure 2: Terminal window inside of a test_env virtual environment

When you open a new command terminal window, you can enter

an existing virtualenv (in this case test_env) by typing:

$ workon test_env

For the official virtualenv documentation, visit:http://virtualenv.readthedocs.org/en/latest/

● Setup version control

Version control allows us to work on multiple versions of our code at the

same time. We use git as our source management system.

Git Immersion is a great tutorial for becoming familiar with using Git: http://gitimmersion.com/Github also has a detailed help section: https://help.github.com/

○ To install git, type:

$ sudo apt-get install -y git

9

○ Then, set up your git configuration with your name and email

information. This information will show up in the git logs and on Github.

Type:

$$

git config --global user.name "YOUR NAME"git config --global user.email "YOUR EMAIL"

● Set up SSH with Github

Github is a web-based service that allows us to host our code in a centralized

location. By using git locally, we can pull changes, push updates, and review

our code on Github. Github uses SSH keys to securely identify trusted

computers without the need for passwords.

SSH stands for Secure Shell. It is an encrypted network protocol that allows two networked computers to securely connect to one another and authenticate each other’s identities. Github uses SSH to identify users and to transmit data securely

between users’ local machines and their servers.

○ If you do not have a Github account already, sign up for one at: https://github.com/

○ Then, add your newly generated SSH key to your Github account. On

the menu bar, click on the Account Settings icon (it is in the upper

right-hand corner of the screen).

Figure 3. Github account settings

○ To generate an SSH key, type:

$ ssh-keygen -t rsa -C "your_email@example.com"

10

The command prompt will ask for the file to store the key in. Press

Enter to store the key at the default location. The prompt will also ask

for a passphrase. Enter a passphrase that you will remember. It should

be at least 12 characters long contain upper and lowercase letters,

numbers and symbols.

Figure 3: Output of ssh-keygen command

○ Next, add the SSH key to the ssh-agent by typing:

$$

eval "$(ssh-agent -s)"ssh-add ~/.ssh/id_rsa

○ Copy the contents of the key to your clipboard by typing:

$$

sudo apt-get install -y xclipxclip -sel clip < ~/.ssh/id_rsa.pub

The clipboard may time out after about 10 minutes. If so, you will need to recopy the contents of the key using the above command.

○ Then, click the SSH keys option on the left sidebar. Click Add SSH

Key, which will open a new form. Add a title that describes the

computer you’re working on. Afterwards, paste the key into the Key

field. Finally, click the add key button.

11

Figure 4. Adding SSH key

○ Test that you can connect to Github via SSH by typing:

$ ssh -T git@github.com

○ The first time you run this code, you will see a warning:

Figure 5. Testing connection to Github via SSH

Simply type yes. There will be a confirmation message letting you

know that you have authenticated with Github.

Figure 6. Response upon successful authentication to Github

● Run the code

○ The code for our company website is stored on Github. In this section

we will pull the code from the website to our local machine and run it

locally. To retrieve the code, it must be cloned from the Github

repository. First, make sure you are in your home directory by typing:

$ cd ~

○ To retrieve the code, type:

$ git clone git@github.com:stemchan/google-flask.git

○ A new folder should show up in your home directory containing the

new project. Change folders directory by typing :

$ cd ~/google-flask

12

○ Then, install the packages required for the project. The packages and

their versions are stored in the requirements.txt file. Type the

following:

$ pip install -r requirements.txt

○ Once the packages have installed successfully, you can now run the

project and view the website that the code generates. To start the

server, type:

$ python google-flask.py

○ To test that the project is running successfully, go to a web browser

and go to the url: localhost:5000. The company homepage should

appear (see Figure 6).

Figure 6. Company homepage

○ The terminal should display the following information:

Figure 7. Terminal output when running the server

○ To stop the server, press: CTRL+C in the terminal.

Summary

13

After completing these instructions, you should have a Python development

environment setup on your computer. Now that you have this environment, you will

be able to write, run, and contribute to the company’s codebase.

14

Troubleshooting

● pip error: permission denied

○ A common error many people make when first using their development

environment is not paying attention to their use of their virtual

environment. If you receive an error saying you do not have permissions

to install a package with pip, it means that you are not in your virtual

environment.

Solution:Make sure you run this command every time you start work on the

dev environment in a new terminal window:

$ workon test_env

● Permission Denied (publickey)

○ There are a number of things that could potentially go wrong when

creating a secure connection with Github.

Solution: Make sure to read the Section 5 carefully to ensure that you have

properly set up SSH. If the issue still persists, refer to this help page by

Github: https://help.github.com/articles/error-permission-denied-publickey

15

Additional Resources

● Python Documentation - https://www.python.org/

● Python Tutorial - http://learnpythonthehardway.org/

● Command Line - http://cli.learncodethehardway.org/book/

● Virtualenv - http://virtualenv.readthedocs.org/en/latest

● Virtualenvwrapper - http://virtualenvwrapper.readthedocs.org/en/latest/

● Git - http://gitimmersion.com/

● Github - https://github.com/

16