Software Instructions
- 1. 1 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
- 2. 2 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
- 3. 3 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.
- 4. 4 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.). This is a tip.
- 5. 5 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/
- 6. 6 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: Figure 1: The Python interactive shell showing Python version 2.7.6 ○ To close the Python interactive shell, type: >>> exit()
- 7. 7 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 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:
- 8. 8 $ 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=~/Envs mkdir -p $WORKON_HOME source /usr/local/bin/virtualenvwrapper.sh ■ 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
- 9. 9 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 ○ 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.
- 10. 10 ○ 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" 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 xclip xclip -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.
- 11. 11 ○ 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. 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 ~
- 12. 12 ○ 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 ○ 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.
- 13. 13 Summary 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. 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. 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/