Skip to content

Latest commit

 

History

History
293 lines (229 loc) · 18.5 KB

SETUP.md

File metadata and controls

293 lines (229 loc) · 18.5 KB
Raw

Setup

This document describes how to set up your workstation to develop for Code.org.

You can do Code.org development using OSX, Ubuntu, or Windows (running Ubuntu in a VM). Setup for Windows is more complicated and relatively few developers use it. Make sure you follow the instructions for your platform in the subsections below.

Overview

  1. Install OS-specific prerequisites

    • See the appropriate section below: OSX, Ubuntu, Windows

    • When done, check for correct versions of these dependencies:

      ruby --version  # --> ruby 2.5.0
node --version  # --> v8.15.0
yarn --version  # --> 1.16.0

  2. If using HTTPS: git clone https://github.com/code-dot-org/code-dot-org.git, if using SSH: git@github.com:code-dot-org/code-dot-org.git

  3. gem install bundler -v 1.17

  4. rbenv rehash

  5. cd code-dot-org

  6. bundle install (Problems running this step? See tips below.)

  7. bundle exec rake install:hooks

    Troubleshoot: `rake aborted!..` 
     If you have issue "rake aborted! Gem::LoadError: You have already activated rake 12.3.0, but your Gemfile requires rake 11.3.0. Prepending `bundle exec` to your command may solve this."
     * Follow the instructions and make sure you added `bundle exec` in front of the `rake install:hooks` command
    Troubleshoot: wrong version of rake 
     You might get a message at some point about having the wrong version of rake. If so, try:
 $> gem uninstall rake
 $> bundle update rake

  8. bundle exec rake install

  • This can take a LONG time. You can see if progress is being made by opening up a second shell and starting mysql -u root. Run the following command twice, with approximately a 5-10 second delay between each run select table_schema, table_name, table_rows from information_schema.tables where table_schema like 'dashboard_development' order by table_rows; If you see a change in the last couple of rows, the install is working correctly.
  1. bundle exec rake build
  • This may fail if your are on a Mac and your OSX XCode Command Line Tools were not installed properly. See Bundle Install Tips for more information.
  1. (Optional, Code.org engineers only) Setup AWS - Ask a Code.org engineer how to complete this step
    1. Some functionality will not work on your local site without this, for example, some project-backed level types such as https://studio.code.org/projects/gamelab. This setup is only available to Code.org engineers for now, but it is recommended for Code.org engineers.

After setup, read about our code styleguide, our test suites, or find more docs on the wiki.

OS-specific prerequisites

OS X Mojave / Mavericks / Yosemite / El Capitan / Sierra

  1. Install Homebrew: ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

  2. Install Redis: brew install redis

  3. Run brew install https://raw.github.com/quantiverge/homebrew-binary/pdftk/pdftk.rb enscript gs mysql@5.7 nvm imagemagick rbenv ruby-build coreutils sqlite

    Troubleshoot: Formula.sha1 is disabled or Error: pdftk: undefined method sha1' for #<Class:...> 
     If it complains about `Formula.sha1` is disabled, removing https://raw.github.com/quantiverge/homebrew-binary/pdftk/pdftk.rb from the above command seems to not have serious side effects (it will cause `PDFMergerTest` to fail). It may be a new URL is needed in the dependency list, see https://leancrew.com/all-this/2017/01/pdftk/
    Troubleshoot: old version of `<package>` 
     If it complains about an old version of `<package>`, run `brew unlink <package>` and run `brew install <package>` again

  4. Install PhantomJS: brew cask install phantomjs

  5. Set up MySQL

    1. Force link 5.7 version: brew link mysql@5.7 --force
    2. Have launchd start mysql at login: ln -sfv /usr/local/opt/mysql/*.plist ~/Library/LaunchAgents
      1. Note, if mysql folder name is "mysql@5.7", replace the command above by ln -sfv /usr/local/opt/mysql@5.7/*.plist ~/Library/LaunchAgents. (Use ls -d /usr/local/opt/mysql* to check for folder name.)
    3. Start mysql now: launchctl load ~/Library/LaunchAgents/homebrew.mxcl.mysql.plist
      1. Note: if this fails check your plist file (ls ~/Library/LaunchAgents/) to see if it is "homebrew.mxcl.mysql@5.7.plist". If it is try: launchctl load ~/Library/LaunchAgents/homebrew.mxcl.mysql@5.7.plist instead

  6. Set up rbenv

    1. Run rbenv init
    2. Add the following to ~/.bash_profile or your desired shell: eval "$(rbenv init -)". More info here.
    3. Pick up those changes: source ~/.bash_profile

  7. Install Ruby 2.5.0

    1. rbenv install 2.5.0
    2. Set the global version of Ruby: rbenv global 2.5.0
    3. Install shims for all Ruby executables: rbenv rehash. More info here.

  8. Set up nvm

    1. Create nvm's working directory if it doesnt exist: mkdir ~/.nvm

    2. Add the following to ~/.bash_profile or your desired shell configuration file:

      # Load nvm function into the shell
export NVM_DIR=~/.nvm
source $(brew --prefix nvm)/nvm.sh

    3. Pick up those changes: source ~/.bash_profile

  9. Install Node and yarn

    1. nvm install 8.15.0 && nvm alias default 8.15.0 this command should make this version the default version and print something like: Creating default alias: default -> 8.15.0 (-> v8.15.0)
    2. npm install -g yarn@1.16.0.
    3. (Note: You will have to come back to this step after you clone your repository) Reinstall node_modules cd apps; yarn; cd ..

  10. (El Capitan only) Ensure that openssl is linked: brew link --force openssl

  11. Prevent future problems related to the Too many open files error:

    1. Add the following to ~/.bash_profile or your desired shell configuration file: 
      ulimit -n 8192
    2. close and reopen your current terminal window
    3. make sure that ulimit -n returns 8192

  12. Install the Xcode Command Line Tools:

    1. xcode-select --install
    Troubleshoot: command line tools already installed 
           If it complains

       ```xcode-select: error: command line tools are already installed, use "Software Update" to install updates```

       check to make sure XCode is downloaded and up to date manually.

  13. Install the Java 8 JDK

Ubuntu 16.04 (Download iso) Note: Virtual Machine Users should check the Windows Note below before starting

  1. sudo apt-get update
  2. sudo apt-get install -y git mysql-server mysql-client libmysqlclient-dev libxslt1-dev libssl-dev zlib1g-dev imagemagick libmagickcore-dev libmagickwand-dev openjdk-9-jre-headless libcairo2-dev libjpeg8-dev libpango1.0-dev libgif-dev curl pdftk enscript libsqlite3-dev phantomjs build-essential redis-server rbenv
    • Hit enter and select default options for any configuration popups, leaving mysql passwords blank
  3. (If working from an EC2 instance) sudo apt-get install -y libreadline-dev libffi-dev
  4. Install Node and Nodejs
    1. curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
    2. sudo apt-get install -y nodejs
  5. Ensure rbenv and ruby-build are properly installed
    1. Use the rbenv-doctor from the rbenv installation instructions to verify rbenv is set up correctly:
      1. curl -fsSL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-doctor | bash
    2. If there are any errors (they appear red), follow the [rbenv installation instructions] (https://github.com/rbenv/rbenv#basic-github-checkout) to properly configure rbenv, following steps for Ubuntu Desktop so that config changes go into .bashrc.
    3. Install ruby-build as a rbenv plugin
  6. Install Ruby 2.5.0 with rbenv
    1. rbenv install 2.5.0
    2. If your PATH is missing ~/.rbenv/shims, the next two commands might not work. Edit your .bashrc to include the following line: export PATH="$HOME/.rbenv/bin:~/.rbenv/shims:$PATH", then run source .bashrc for the change to take effect (as seen in this github issue).
    3. rbenv global 2.5.0
    4. rbenv rehash
  7. Install yarn
    1. curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
    2. echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
    3. sudo apt-get update && sudo apt-get install yarn=1.16.0-1
  8. Finally, configure your mysql to allow for a proper installation. You may run into errors if you did not leave mysql passwords blank
    1. echo "ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY '';" | sudo mysql
  9. IMPORTANT: Read the following notes, then go back up to the overview and run the commands there.
    1. If, for any reason, you are forced to interrupt the bundle exec rake install command before it completes, cd into dashboard and run bundle exec rake db:drop before trying bundle exec rake install again
    2. bundle exec rake install must always be called from the local project's root directory, or it won't work.
    3. Finally, don't worry if your versions don't match the versions in the overview if you're following this method; the installation should still work properly regardless

Windows note: use an Ubuntu VM

Many Windows developers have found that setting up an Ubuntu virtual machine is less painful than getting Ruby and other prerequisites running on Windows.

  • Option A: Use VMWare Player or Virtual Box and an Ubuntu 16.04 iso image
    1. Maximum Disk Size should be set to 30.0 GB (the default is 20 GB and it is too small)
    2. Memory Settings for the VM should be 8 GB or higher (Right click the machine -> Settings -> "Memory for this virtual machine" )
  • Option B: Use vagrant (install):
    1. First clone the code.org git repo to get the provided Vagrantfile (you will be able to skip step 1 of the common setup instructions): git clone https://github.com/code-dot-org/code-dot-org.git
    2. cd code-dot-org
    3. vagrant up
    4. vagrant ssh
    5. Goto step 2 of the common setup instructions
  • Option C: Use an Amazon EC2 instance:
    1. Request AWS access from accounts@code.org if you haven't already done so.
    2. From the EC2 Homepage, click on "Launch Instance" and follow the wizard:
      • Step 1: Choose AMI: Select Ubuntu Server 16.04
      • Step 2: Choose instance type: Choose at least 8GiB memory (e.g. t2.large)
      • Step 3: Configure Instance: Set IAM Role to DeveloperEC2
      • Step 4: Storage: Increase storage to 32GiB
    3. Launch the instance. When asked for a key pair, you can create a new key pair (be sure to download and save the .pem file) or use an existing key pair that you have the .pem file for.
    4. Connect to the instance by selecting the instance in the AWS EC2 dashboard and clicking "Connect". Follow the provided instructions in order to connect via ssh or PuTTY. Upon completing this step, you should be able to connect to your instance via a command like ssh -i <keyname>.pem <public-dns-name>.
    5. Optionally, update your ssh config so that you can connect using a shorter command:
      • move your private key to ~/.ssh/<keyname>.pem
      • add the following lines to ~/.ssh/config: 
        Host yourname-ec2
  Hostname <public-dns-name>
  User ubuntu
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/<keyname>.pem
      • run ssh yourname-ec2 to connect to your instance
    6. Go back up to the overview and run the commands there.
    7. Once you have successfully completed bundle exec rake build, you can connect to it as follows:
      • run ssh -L 3000:127.0.0.1:3000 yourname-ec2 and then ~/code-dot-org/bin/dashboard-server on your local machine. This sets up SSH port forwarding from your local machine to your ec2 dev instance for as long as your ssh connection is open.
      • navigate to http://localhost-studio.code.org:3000/ on your local machine

Enabling JavaScript builds

Note: the installation process now enables this by default, which is recommended. You can manually edit these values later if you want to disable local JS builds.

If you want to make JavaScript changes and have them take effect locally, you'll want to enable local builds of the JavaScript packages. You'll need to do this once:

  1. Edit locals.yml and enable the following options:

    # code-dot-org/locals.yml

# These enable the local apps build
build_apps: true
use_my_apps: true

  2. Run bundle exec rake package for the changes to take effect.

This configures dashboard to rebuild apps whenever you run bundle exec rake build and to use the version that you built yourself. See the documentation in that directory for faster ways to build and iterate.

If waiting around for javascript builds is making you sad, consider sending build time logs to New Relic so we can track the slowness. You can do this by copying our license key from the New Relic account page and pasting it into locals.yml:

new_relic_license_key: <license key here>

Editor configuration

We enforce linting rules for all our code, and we recommend you set up your editor to integrate with that linting.

Javascript

We use eslint to lint our Javascript; see the official integrations guide for instructions for your editor of choice.

Our lint configuration uses formatting rules provided by Prettier. You can configure your editor to auto-format your code to meet our requirements, in addition to the error highlighting provided by eslint. See the official integrations guide for instructions for your editor of choice.

Ruby

We use RuboCop to lint our Ruby; see the official integrations guide for instructions for your editor of choice.

More Information

Please also see our other documentation, including our:

Wondering where to start? See our contribution guidelines for more information on helping us out.

Bundle Install Tips

rmagick

If rmagick doesn't install, check your version of imagemagick, and downgrade if >= 7

  • convert --version
  • brew install imagemagick@6
  • brew unlink imagemagick
  • brew link imagemagick@6 --force If you continue to have issues with rmagick, after changing your imagemagick version, you may need to uninstall/reinstall the gem
  • gem uninstall rmagick
  • gem install rmagick -v 2.15.4

libv8

If you run into an error with libv8 while running bundle install

  • Uninstall libv8: gem uninstall libv8
  • Make sure the gem no longer exists with: gem list libv8
  • Install the current version used in code.org repo: gem install libv8 -v CURRENT_CODEORG_VERSION -- --with-system-v8 (you can find what to fill in for CURRENT_CODEORG_VERSION as the current version of libv8 in the Gemfile.lock).

mysql2

If you run into an issue about mysql2 while running bundle install and the error output includes "ld: library not found for -lssl" try :

  • brew install openssl
  • export LIBRARY_PATH=$LIBRARY_PATH:/usr/local/opt/openssl/lib/

(Steps from this github issue)

therubyracer

If you run into an issue about therubyracer while running bundle install try :

  • gem uninstall libv8
  • gem install therubyracer -v CURRENT_CODEORG_VERSION (you can find what to fill in for CURRENT_CODEORG_VERSION as the current version of the therubyracer in the Gemfile.lock).
  • gem install libv8 -v CURRENT_CODEORG_VERSION -- --with-system-v8 (You can find what to fill in for CURRENT_CODEORG_VERSION as the current version of libv8 in the Gemfile.lock).

(Steps from this stackoverflow question)

bundler gem

If you run into the error message can't find gem bundler (>= 0.a) with executable bundler (Gem::GemNotFoundException) while running bundle install try (as seen in this StackOverflow):

  • gem install bundler -v BUNDLED_WITH_VERSION, where the version is the BUNDLED WITH version in Gemfile.lock).
  • bundle install

Xcode Set Up

OS X: when running bundle install, you may need to also run xcode-select --install. See stackoverflow. If this doesn't work, step 9 in the overview will not run correctly. In that case run the following command in the Terminal (found from nodejs/node-gyp#569): sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

Recommended hardware

While it's possible to run the server locally without these, we've found the following hardware specifications to be best for fast development.

  • Memory: minimum of 8GB RAM for dashboard-server and yarn
  • Storage: The repository takes up 16GB