<commit_before>.. _getting-started-chapter:

=================
 Getting started
=================

.. contents::
   :local:

This guide walks through getting a development environment set up
to allow you to contribute to Fjord.

.. Note::

   This definitely works for Mac OSX and Linux and probably works for
   Windows, too. If you have issues, please let us know.


Getting the requirements
========================

1. Download and install git if you don't have it already:
   http://git-scm.com/

   .. Note::

      **Windows users:** When you install git, make sure to choose
      "Checkout as-is, commit Unix-style line endings". If you don't,
      then you'll end up with Windows-style line endings in your
      checkout and Fjord won't work in the virtual machine.

2. Download and install VirtualBox if you don't have it already:
   https://www.virtualbox.org/

3. Download and install Vagrant if you don't have it already:
   http://www.vagrantup.com/


Download Fjord
==============

If you have a GitHub account, you should fork the Fjord repository and
then clone your fork::

    git clone https://github.com/<USERNAME>/fjord.git

If you do not have a GitHub account, that's ok! Clone the official
Fjord repository this way::

    git clone https://github.com/mozilla/fjord.git

This creates a directory called ``fjord/``. We'll call that the "Fjord
repository top-level directory".

Building a vm and booting it
============================

This will build a VirtualBox vm using Vagrant. The vm will have Ubuntu
Linux 14.04 installed in it. Fjord works in this environment.

Run this commands in the Fjord repository top-level directory::

    vagrant up


It takes a while the first time you do this since it has to create the
virtual machine and provision it. First it downloads an Ubuntu Linux
14.04 image (~300mb), then it installs some software in this image
like MySQL and Elasticsearch. Then it sets things up so that Fjord
runs in this VM using the files on your machine. This allows you to
use whatever editor you like on your machine to edit code that runs in
the VM without having to copy files around.


Setting up Fjord
================

After you've created a vm, we have some minor setup to do::

    # Create a shell on the guest virtual machine
    vagrant ssh

    # Change into the fjord/ directory
    cd ~/fjord


First we download all the product detail data::


    # Update product details
    ./manage.py update_product_details -f


Then we set up the database::

    # Create the database and run migrations<commit_msg>Fixes to getting started docs<commit_after>.. _getting-started-chapter:

=================
 Getting started
=================

.. contents::
   :local:

This guide walks through getting a development environment set up
to allow you to contribute to Fjord.

.. Note::

   This definitely works for Mac OSX and Linux and probably works for
   Windows, too. If you have issues, please let us know.


Getting the requirements
========================

1. Download and install git if you don't have it already:
   http://git-scm.com/

   .. Note::

      **Windows users:** When you install git, make sure to choose
      "Checkout as-is, commit Unix-style line endings". If you don't,
      then you'll end up with Windows-style line endings in your
      checkout and Fjord won't work in the virtual machine.

2. Download and install VirtualBox if you don't have it already:
   https://www.virtualbox.org/

3. Download and install Vagrant if you don't have it already:
   http://www.vagrantup.com/

   .. Note::

      You might have to close your terminal and start a new one to
      pick up changes to PATH or other things in the environment after
      installing these so that they're available.


Download Fjord
==============

If you have a GitHub account, you should fork the Fjord repository and
then clone your fork::

    git clone https://github.com/<USERNAME>/fjord.git

If you do not have a GitHub account, that's ok! Clone the official
Fjord repository this way::

    git clone https://github.com/mozilla/fjord.git

This creates a directory called ``fjord/``. We'll call that the "Fjord
repository top-level directory".


Building a vm and booting it
============================

This will build a VirtualBox vm using Vagrant. The vm will have Ubuntu
Linux Trusty 14.04 installed in it. Fjord works in this environment.

.. Note::

   Setting up Fjord in Vagrant takes at least 15 minutes and possibly
   more depending on your network connection.

   Plan to kick off a command and then go do something else for a
   while.


Run this command in the Fjord repository top-level directory::

    vagrant up


It takes a while the first time you do this since it has to create the
virtual machine and provision it.

First it downloads an Ubuntu Linux 14.04 image (~300mb), then it
installs some software in this image like MySQL and
Elasticsearch. Then it sets things up so that Fjord runs in this VM
using the files on your machine. This allows you to use whatever
editor you like on your machine to edit code that runs in the VM
without having to copy files around.


Setting up Fjord
================

After you've created a vm, we have some minor setup to do::

    # Create a shell on the guest virtual machine
    vagrant ssh

    # Change into the fjord/ directory
    cd ~/fjord


First we download all the product detail data::


    # Update product details
    ./manage.py update_product_details -f


Then we set up the database::

    # Create the database and run migrations
{'fraction_non_alphanumeric': 0.09487870619946091, 'fraction_numerical': 0.005390835579514825, 'mean_word_length': 3.4315286624203822, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 6, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 12, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3915514', 'n_tokens_mistral': 1576, 'n_tokens_neox': 1453, 'n_words': 798}