Skip to content

Local Setup

Jump to bottom
Ronak Roy edited this page Mar 18, 2020 · 12 revisions

This guide explains how to set up your local computer for developing and deploying changes to our website.

Prerequisites

In order to edit the website, you need a GitHub account and to be a part of our team's GitHub organization. You can create an account at github.com, and talk to the current Head of Controls to add you to the organization.

This guide will likely take anywhere from 0.5 to 2.0 hours, depending on the speed of your computer and your experience level with computers.

Necessary Applications

In order to develop/deploy locally, you need two applications.

  • GitHub Desktop. As you've probably seen by now, our website is hosted by GitHub. GitHub is an online service that hosts git repositories. git is a version control system, which lets programmers collaborate on and track the history of projects. For the purposes of the website, GitHub will serve as a place to upload the HTML/CSS/JS files that builds up our website (like Google Drive, but fancier).
  • Visual Studio Code. Visual Studio Code is an open-source IDE developed by Microsoft. It is incredibly fast and lightweight, and it's essentially a glorified text editor. It's the IDE we use for all of the robot code development on the team, but it makes organizing/editing files and photos incredibly easy.

Installing GitHub Desktop

First, we'll install GitHub desktop.

  1. Go to desktop.github.com
  2. Click the purple Download for macOS or Download for Windows button (depends on your OS)
  3. Follow the instructions for installing GitHub Desktop
  4. Open the GitHub Desktop app and follow the setup steps

Installing Visual Studio Code

Next, we'll install Visual Studio Code

  1. Go to code.visualstudio.com
  2. Click the green Download for Mac or Download for Windows button (depends on your OS)
  3. Follow the instructions for Installation in the setup guide for macOS or Windows
  4. Ensure that you can open the Visual Studio Code app

Cloning and Editing the Website

Cloning the team3128.github.io repository

Now that you have both GitHub Desktop and VS Code installed, you can "clone" the repository for our website to your computer. This means that all of the files for the website will be downloaded; with GitHub desktop, you can download any changes that have been made elsewhere (this is known as a git "pull") and upload changes you've made (this is known as a git "push").

  1. Open GitHub Desktop
  2. Click the Clone Repository button. (If you can't see it, open the File menu and click Clone Repository...)
  3. In the tab bar at the top of the Clone a Repository popup, click GitHub.com
  4. in the Filter... text field, type team3128.github.io
  5. At the bottom of the window, in the Local Path section, click Choose...
  6. Navigate to and select the directory in which you want the website files to be stored on your computer
  7. Click Clone...

Editing the website in Visual Studio Code

Now that you've cloned our team's website, you can edit it in Visual Studio Code. While you can edit the files of the website in any text editor, I'd recommend that you follow the steps to open it in Visual Studio Code.

  1. Open VS Code
  2. In the application menu, click File > Open...
  3. Navigate to where you cloned the team3128.github.io repository, and open that folder

You can navigate the files and folders in the website's repository using the sidebar on the left. To learn which files and folders do what, and which specific files to edit to accomplish whatever goals, check out the Website Structure page.

Downloading/Uploading Changes

Now that you've downloaded the website and can edit it on your computer, there are two more important things to worry about: downloading changes whenever other people (or you, from another computer) makes them, and uploading the changes that you make.

Downloading changes

In order to download changes, all you need to do is click the rightmost button on the toolbar of GitHub Desktop. The button will either read Fetch origin or Pull origin (when there are changes that GitHub Desktop has detected).

IMPORTANT: Before you start working on the website, make sure to pull changes so your edits do no conflict with those others have made. If you do end up with this problem, you'll have to manually fix merge conflicts (if this happens, and you don't know what to do, ask someone from Controls).

Uploading your changes

Uploading your changes is a two-step process.

Commit. git is a version control system, meaning that when you save a file, they don't automatically go anywhere. In order to make the changes semi-permanent, you need to "commit" the files, or tell git that you'd like to save the current state of your project. In order to commit,

  1. Navigate to the team3128.github.io repository in GitHub Desktop
  2. On the tab bar under the Current Repository dropdown, click the left tab labelled Changes
  3. Near the bottom of the left sidebar, in the Summary (required) field, type a short description of the changes you made
  4. At the bottom of the left sidebar, click the blue Commit to master button

Push. Once you've made your changes locally, you need to upload them to GitHub. Do this by clicking the rightmost button on the upper toolbar, which will now say Push origin.

Previewing the Website Locally

The best part about all of this is that you can edit files and automatically generate the website (with all of those changes applied) on your computer before you push the changes to GitHub. To do this, we're going to need to install Jekyll, which is the magic code library that converts all of our website files into an actual website.

This process is a little involved (and requires administrator access), so make sure you have some time (and maybe some water and a snack).

Installation

macOS

  1. Install Xcode. You also have to open it once to accept the License Agreement.
  2. Open Terminal (Applications/Utilities/Terminal.app)
  3. Run xcode-select --install. This installs command-line tools so you can do fun Terminal hackery.
  4. Run /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)". This installs Homebrew, a package manager for macOS. It actually does a lot of cool things, so if you're interested in software development (working with openCV, python, heroku, and a whole slew of UNIX/Linux things), definitely read more about it.
  5. Run brew install ruby. This installs the latest version of Ruby.
  6. Run
    macOS High Sierra (10.14) and earlier: echo 'export PATH=/usr/local/opt/ruby/bin:$PATH' >> ~/.bash_profile
    macOS Catalina (10.15) and later: echo 'export PATH=/usr/local/opt/ruby/bin:$PATH' >> ~/.zshrc
  7. Close the Terminal window
  8. Open a new Terminal window
  9. Run gem install --user-install bundler jekyll. This actually installs Jekyll.
  10. Run version=$(ruby -v); version=${version:5:3}; cmd='export PATH=$HOME/.gem/ruby/'; cmd+=$version; cmd+='.0/bin:$PATH'
  11. Run
    macOS High Sierra (10.14) and earlier: echo $cmd >> ~/.bash_profile
    macOS Catalina (10.15) and later: echo $cmd >> ~/.zshrc
  12. Run gem install jekyll-redirect-from

You did it!

Windows

  1. Go to RubyInstaller Downloads and download the recommended version. This installs the latest version of Ruby.
  2. Run the downloaded installer with the default options
  3. At the last step of the installer, run the ridk install step
  4. Open a new command prompt window from the Start menu
  5. Run gem install jekyll bundler. This actually installs Jekyll.
  6. Run gem install jekyll-redirect-from

You did it!

Hosting the website locally

Now that you've installed Jekyll, you can actually run the website server on your own computer. To start the server:

  1. Open up the website project in VS Code
  2. In the application menu, click Terminal > New Terminal
  3. In the Terminal window at the bottom of the screen, run jekyll serve (if that doesn't work, try bundler jekyll serve)
  4. After the initial build is successful, the output have a line that looks like the following: Server address: http://127.0.0.1:5000 or Server address: http://localhost:4000. command+click (macOS) or control+click (Windows) that link.

Finally, after who know how long, you're ready to go. From now on, any time you want to preview the version of the website with all of the edits you've made on your computer, just open the VS Code terminal window and execute the serve command.

Every time you save, the website will automatically rebuild, and can be previewed at that address. However, only you will be able to see that website preview. None of your changes will actually appear on the website until you complete the steps to upload them.

team3128.github.io

Documentation Home

Basic Tutorials

Intermediate Guides

Advanced Documentation

Clone this wiki locally