Difference between revisions of "Workflow"

From CSE330 Wiki
Jump to navigationJump to search
(Added information on WSL)
Line 7: Line 7:
 
=== Running Commands ===
 
=== Running Commands ===
  
''Mac OS X:'' You will be running commands on your local machine using '''Terminal''', which you can find in your Applications -> Utilities folder.  You will be connecting to your server via SSH also in Terminal.
+
''Mac OS X:'' You will be running commands on your local machine using '''Terminal''', which you can find in your Applications -> Utilities folder.  You will be connecting to your server via SSH.
  
''Windows:'' You will be running commands on your local machine using '''Cygwin''', which you will install in the next section.  You will be connecting to your server via SSH also in Cygwin.
+
''Windows:'' You will be running commands on your local machine using '''WSL''' or '''Cygwin''', which you will install in the next section.  You will be connecting to your server via SSH.
  
 
=== Version Control ===
 
=== Version Control ===
Line 17: Line 17:
 
=== Text Editing ===
 
=== Text Editing ===
  
You will be using '''Komodo Edit''' as your text editing tool.
+
You may use '''Komodo Edit''' as your text editing tool, but don't have to. Other excellent programs include '''Sublime Text''', '''Notepad++''' (for Windows), and '''TextWrangler''' (for Mac). You can also use an IDE, like '''PHPStorm''', if you prefer.
  
 
=== File Transfer ===
 
=== File Transfer ===
  
You will be using '''FileZilla''' as your tool for uploading files from your local working directory to your remote server.
+
You may use '''FileZilla''' as your tool for uploading files from your local working directory to your remote server. Another excellent option is '''Cyberduck'''.
  
 
=== Flowchart ===
 
=== Flowchart ===
Line 33: Line 33:
 
In the flowchart, your ''Git Client'' is SourceTree and your ''Text Editor'' is Komodo.  The ''SFTP Client'' could be FileZilla.
 
In the flowchart, your ''Git Client'' is SourceTree and your ''Text Editor'' is Komodo.  The ''SFTP Client'' could be FileZilla.
  
== Cygwin ==
+
== Installing a Terminal Emulator ==
 +
{{RequiredInstructions|content=
 +
 
 +
Windows is based on a fundamentally different architecture than Linux, meaning that, if you want to run Linux programs on Windows, you'll have to enable or install a special terminal emulator for it. Mac users do not need to install a terminal emulator since MacOs itself is a derivative of Unix, which is an ancestor of Linux.  The Terminal utility is all you need.
 +
 
 +
=== Windows Subsystem for Linux ===
 +
 
 +
Starting in Windows 10, Windows has the ability to emulate Linux, meaning that you can run Linux commands on Windows, without having to install Cygwin. To enable WSL, follow {https://msdn.microsoft.com/en-us/commandline/wsl/install_guide|these instructions}. Once those instructions are complete, you can open a shell by clicking on the Start menu, typing "Bash", then clicking on the entry labeled "Bash on Ubuntu on Windows".
  
{{RequiredInstructions|content=
+
=== Cygwin ===
  
 
'''Cygwin''' is a Linux Terminal emulator for Windows.
 
'''Cygwin''' is a Linux Terminal emulator for Windows.
  
Mac OS X users do not need to install Cygwin since OS X itself is a derivative of Unix, which is an ancestor of Linux.  The Terminal utility is all you need.
+
==== Installation ====
 
 
=== Installation ===
 
  
 
The CEC lab machines already have Cygwin installed.  Follow these instructions to get Cygwin up and running on your personal PC.
 
The CEC lab machines already have Cygwin installed.  Follow these instructions to get Cygwin up and running on your personal PC.
Line 58: Line 63:
 
# Allow the installation to complete.
 
# Allow the installation to complete.
  
Throughout the rest of this course, when we say to "open a terminal", if you are on Windows, we mean to "open Cygwin".
+
Throughout the rest of this course, when we say to "open a terminal", if you are on Windows, we mean to "open WSL/Cygwin".
 
 
 
 
  
 
}}
 
}}

Revision as of 17:13, 24 August 2017

The few minutes it takes to optimize your workflow will be the best few minutes you will spend in CSE 330 and your career. It is remarkable how many hours you can save just by using the best interface for text editing and deployment.

Overview

There are going to be several aspects to our workflow in CSE 330, and we will be switching between multiple different programs. Here is how they all fit together.

Running Commands

Mac OS X: You will be running commands on your local machine using Terminal, which you can find in your Applications -> Utilities folder. You will be connecting to your server via SSH.

Windows: You will be running commands on your local machine using WSL or Cygwin, which you will install in the next section. You will be connecting to your server via SSH.

Version Control

You will be using SourceTree as a frontend to the Git version control system. Git enables you to keep track of changes to your source code.

Text Editing

You may use Komodo Edit as your text editing tool, but don't have to. Other excellent programs include Sublime Text, Notepad++ (for Windows), and TextWrangler (for Mac). You can also use an IDE, like PHPStorm, if you prefer.

File Transfer

You may use FileZilla as your tool for uploading files from your local working directory to your remote server. Another excellent option is Cyberduck.

Flowchart

If you are more visual, this flowchart might help:

CSE-330-Workflow.png

The flowchart illustrates 3 methods to copy files to your cloud instance: via your text editor, via an external SFTP client, and by cloning your remote Git repository. We will be primarily using Option 2 in CSE 330 this semester.

In the flowchart, your Git Client is SourceTree and your Text Editor is Komodo. The SFTP Client could be FileZilla.

Installing a Terminal Emulator

Windows is based on a fundamentally different architecture than Linux, meaning that, if you want to run Linux programs on Windows, you'll have to enable or install a special terminal emulator for it. Mac users do not need to install a terminal emulator since MacOs itself is a derivative of Unix, which is an ancestor of Linux. The Terminal utility is all you need.

Windows Subsystem for Linux

Starting in Windows 10, Windows has the ability to emulate Linux, meaning that you can run Linux commands on Windows, without having to install Cygwin. To enable WSL, follow {https://msdn.microsoft.com/en-us/commandline/wsl/install_guide

Bitbucket

Bitbucket is a service that enables you to store your code for free in the cloud. It is similar in spirit to Github, but with a different mission statement.

Creating a Bitbucket Account

Go to Bitbucket.org to create an account.

Important: Use your @wustl.edu e-mail address to create your account. This will put your account on the "educational plan", which removes some limitations of the free account.

Note: If you know someone who uses Bitbucket, you can ask them to invite you as a friend. This will increase the member limit on the inviter's private repos.

Adding Your Key to Bitbucket

  1. First make sure that you've finished the SSH guide configuration instructions.
    We will use the same key for connecting to your remote server as for connecting to Bitbucket. (This is completely valid practice.)
  2. Go to the "SSH keys" section of the settings panel (Manage Account -> SSH Keys)
  3. Add a new key.
    • I recommend naming it after the computer you're using; if you're in the CEC, for example, you could name it "Warehouse Cygwin".
    • The contents of your key is the contents of your id_rsa.pub. It looks like ssh-rsa AAAAB3blahblahblahblah yourname@somedomain. It is exactly the same thing that you had to paste into the authorized_keys file on your EC2 instance.

You will now be able to push code to your Bitbucket repository using your personal SSH key.

SourceTree

SourceTree is a tool that enables you to perform version control using a graphical user interface. It is free and available for Windows 7+ and Mac OS X 10.6+.

SourceTree is available on the Mac App Store. Windows users (and OS X users who don't like the App Store) may install it from http://sourcetreeapp.com/

Git

Git is a distributed version control system that enables you to track changes to your code and work with collaborators on the same code base. In CSE 132, you used Subversion (SVN), which is also version control system.

Git, like SVN, is a command-line tool. However, SourceTree enables you to use Git without having to pull up a Terminal window every time you need to perform an action.

In Module 5, you will learn more advanced techniques for using Git. However, for Modules 2-4, you will be using Git primarily as a method to push your changes to your remote repository.

Configuring Git/SourceTree

Once you install SourceTree, you need to tell it your name so that it knows how to tag changes you make.

  1. Open the SourceTree Preferences (SourceTree->Preferences on OS X or Tools->Options on Windows).
  2. Check the box that says "Allow SourceTree to modify your global Mercurial and Git configuration files".
  3. Enter your name and e-mail address.
    Note: This actually does the same thing as running git config --global user.name <NAME HERE> and git config --global user.email <EMAIL HERE> from the command line.
  4. Go to the "Git" tab, and make the following changes:
    • Uncheck "Use the staging area". You will learn about staging in Git in Module 5, but for Modules 2-4 we will skip the staging area.
    • Check "Disable SSL certificate validation". This is necessary for the git repos hosted in the CEC. (Note: this semester we are using BitBucket repos instead of CEC repos, so you can leave this box unchecked if you prefer.)
  5. Close the preferences window.

Cloning a Repository

Screenshot of cloning a repository in SourceTree

We will start by cloning a remote Git repository.

"Cloning" in Git is much like "checking out" in SVN: a remote copy of the repository is copied down to a local working directory. Word of Caution: Git uses the term "checkout" to mean something different (which you will learn in Module 5), so do not use the words "clone" and "checkout" interchangeably.

If you wanted to clone a repository on the command line, the command would be:

$ git clone git://www.example.com/url-of-repo destination-path

In SourceTree, go to File->New, enter the remote repository URL and the destination path, and press "Clone". The destination path is where you want the repository's files to be copied on your personal computer; the path should point to either an empty or a nonexistent directory on your personal computer. In the screenshot, I am cloning the repository for the Fedora Linux kernel.

The remote repository will now be cloned onto your personal computer and all ready to use.

Committing

Screenshot of committing to a repository in SourceTree

When you make changes to files or add new files, you need to commit them to your working repository. Note: When you "commit" something in SVN, it means that you are sending your changes to the remote repository. This is not the case in Git, as we will see shortly.

To prepare your commit, press the "Commit" button in the SourceTree toolbar. See the screenshot for an example.

Select the files you want to commit, and enter a commit message summarizing the changes you've made since your last commit. When you're ready, press "Commit".

The command line equivalent of this would be:

$ git add --all # adds untracked files to the repository and stages them for the commit
$ git commit -am "This is an example commit"

What happens now is that your changes are recorded in your own local working copy of the Git repository. The changes have not been saved in the remote repository. You need to do this by pushing them.

Pushing

Git is different from SVN in that you can use it completely independently from a remote repository. Thus, in Git, you need to perform the "commit" and "push" steps separately.

After you perform a commit, you need to push your commit to your remote repository. To do this, press the "Push" button in SourceTree, and then press "OK". The command line equivalent is:

$ git push master # assuming your branch is still named the default "master"

Note: You do not need to push after every commit. You could have 4 or 5 commits before you actually perform the push. When you push, all commits will be pushed.

Pulling

In SVN, if you want to download changes from your remote repository, you performed an update. In Git, you perform a pull.

Pulling is (usually) as simple as pressing the "Pull" button in SourceTree. The command line equivalent is:

$ git pull master

Note: If you want to download the changes from the remote repository but not overwrite your current working copy, you can perform a fetch instead.

Pageant and PuTTYgen: SSH Keys for Windows

Pageant is a Windows utility that enables applications like SourceTree and Komodo Edit (which we will install in the next step) to be able to use your SSH keys when authenticating on remote services (like Bitbucket and your EC2 instance). PuTTYgen is a utility that converts SSH keys into a format that Pageant can understand.

Mac OS X and Linux users may skip this section.

Installing Pageant and PuTTYgen

Pageant and PuTTYgen both come bundled with SourceTree, so you do not need to install them separately. However, if you weren't using SourceTree, you could install them from: http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html

Using PuTTYgen

We will use PuTTYgen to convert our SSH keys into Pageant's format, *.ppk.

  1. Launch PuTTYgen. If you downloaded puttygen.exe, just open it; if you are using the SourceTree version, you can find it under the Tools menu:
    LaunchPuTTYgen.jpg
  2. Inside PuTTYgen, click "Load" next to "Load an existing private key file". We want to load the private key we generated in the SSH guide using ssh-keygen.
    • If you are using a CEC machine, the key will be at: H:\.ssh\id_rsa
    • If you are using your own computer, the key should be at: C:\cygwin\home\<your name>\.ssh\id_rsa
    Note that you might need to choose "All Files (*.*)" in order to see the file.
  3. When the key gets loaded, click "Save private key"
    FileZilla, which will also need this *.ppk key, does not play nicely with passphrases, so leave the passphrase blank.
    A good place to save the file would be back in Cygwin's .ssh directory:
    • CEC lab machines: H:\.ssh\id_rsa.ppk
    • Personal machines: C:\cygwin\home\<your name>\.ssh\id_rsa.ppk
  4. Close PuTTYgen.

Using Pageant

To launch Pageant, either run pageant.exe or select it from the Tools menu in SourceTree:

LaunchPageant.jpg

The first time you launch pageant, it will ask you to select a key. Select the *.ppk file you saved in the previous section.

If you wish to add more keys to Pageant, right-click on its icon down in the start bar:

UsePageant.jpg

Adding Pageant as a Startup Item

If you are using your own computer, it may be convenient to add Pageant as a startup item so that you don't need to go into SourceTree and turn it on every time you reboot your computer.

  1. Download pageant.exe if you were using SourceTree
  2. Open your Startup Items folder, located at Start Menu -> All Programs -> Startup (right-click and say "Open")
  3. Right-click inside the folder and say "New -> Shortcut". For the location, enter:
    "C:\path\to\pageant.exe" "c:\path\to\key.ppk"
    
    This will cause Pageant to open and automatically load your key.
  4. Press "Next". Enter a name and press "Finish".

Thanks to the University of Alberta for this tip.

FileZilla

You can use SFTP from the command line, or you can use any GUI file transfer client. All FTP clients I have seen also support SFTP. One popular FTP client is Filezilla.

  1. Download and install FileZilla from http://filezilla-project.org/download.php?type=client
    If you are using a lab computer, you can save it to your H drive.
  2. When you launch FileZilla, go to Edit→Settings or FileZilla→Preferences, and go to the SFTP options (under Connection). Click "Add keyfile…".
    • Windows users: Choose the *.ppk file that you made earlier using Puttygen.
    • Unix users:
      1. Choose your id_rsa file. OS X Tip: Press Shift+Command+Period to reveal hidden files in the file chooser window.
      2. FileZilla will want to make a *.ppk file. A good place to save it would be the .ssh directory as id_rsa.ppk.
    When finished, press OK (not the red ×) to save your changes.
  3. Back on the main FileZilla screen, there are four fields: Host, Username, Password, and Port. Fill them in as follows:
    • Hostname: sftp://ec2-xxx-xx-xx-xxx.compute-1.amazonaws.com/
    • Username: The username you created on your server.
    • Password: Since you are using a key, you may leave this blank.
      If you changed your SSH settings to allow password-based authentication, then you could put your password in here.
    • Port: 22
  4. Then click Quickconnect. If everything is configured correctly, FileZilla should log into your server.

FileZilla.png

On the left and right of the FileZilla window, you can drag files between your computer and your server. Thus, you can edit a file in a text editor like Notepad++ on your decktop, and then upload it to your server by simply dragging it from the left pane to the right pane in FileZilla.

Komodo Edit

Komodo.png

This semester in CSE 330, we will be using Komodo Edit as our editor of choice. We chose this editor because:

  1. It is free for everyone.
  2. It runs on Windows, Mac OS X, and Linux.
  3. It supports all of the languages we will be using in this class.
  4. It has a decent amount tools like auto-completion that will speed up your workflow.

Installation

Komodo Edit is already installed on the CEC lab machines. If you prefer to use your personal computer, download it from the web site: http://www.activestate.com/komodo-edit

SSH Access

You can configure Komodo Edit to connect to your EC2 instance (to implement option 1 in the flowchart above) . However, because of a buggy and incomplete implementation in Komodo, this is not recommended or required for the purposes of CSE 330. For the brave-hearted, instructions can be found here: Komodo Edit with SSH Access

Starting a Project

Start a new Komodo Project whenever you start a new assignment.

  1. Create a repo on Bitbucket and clone it to your local machine.
  2. In Komodo, choose Project -> New Project (or press shift-ctrl-N).
  3. Navigate to the cloned directory, enter a name for the project (e.g., Module2Group.komodoproject), and press "Save".
  4. You should now see a window like this:
    Workflow-1.png
  5. Press ctrl-N (or cmd-N) to create a new file. Save it in your project. For example, you could create a page named index.html with the Quick and Easy Page Layout:
    Workflow-2.png

Tip: To change between files without using a mouse, press ctrl-PageUp and ctrl-PageDown (cmd instead of ctrl on OS X). Many computers without explicit PageUp and PageDown buttons bind them to fn-Up and fn-Down. For example, on a MacBook Pro, to change to the next tab, you would press three keys: fn+cmd+down.

When you are ready, use FileZilla to upload your files to your server via SFTP.