Running The Odin Project Locally

Running TOP Locally

This page assumes that you have already forked and cloned The Odin Project (TOP) repo. If you have not, follow the instructions for setting up a local clone from our contributing guide before continuing.

Table of Contents

• Initial Installations
• Set Up DotEnv
• Instal Gems and Migrate the Database
• Install JavaScript Modules
• Create the Database
• Get a GitHub API Token
• Run the Tests
• Seed the Database and Populate the Lesson Content
• Start the Server
• Optional Steps
  • Github OAuth
  • Google OAuth

Initial Installations

• Install Ruby by following the instructions in our Installing Ruby lesson.
• Install NodeJS by following the instructions in our Installing NodeJS lesson.
• Install Rails by following steps 1.1 and 1.2 in your first Rails app from our Installing Rails project.
• Follow the instructions from one of the following operating system specific guides:
  • Linux Installation Guide
  • Mac Installation Guide

Set Up DotEnv

TOP uses the dotenv gem to manage secrets. We will need to make a copy of the env.sample file (name it .env) and add all our secrets to the new file.

cp env.sample .env

Then edit the newly created .env file to include your Postgres Username and Password.

#------------------------#
# DATABASE CONFIGURATION #
#------------------------#
POSTGRES_USERNAME: 'your-username'
POSTGRES_PASSWORD: 'your-password-here'

Install Gems and Migrate the Database

Next, install the project's gems:

bundle install

Note

If you are using Postgres.App, you may encounter an error installing the pg gem. This is likely due to a PATH issue where your pg_config is unable to be found. If you receive an error stating that this gem was not installed, you will need to run the following.

find /Applications -name pg_config

Then save the path it returns, and then run:

gem install pg -- --with-pg-config=YOUR_PATH_HERE

Note

If bundle install doesn't work and you get a "rbenv version" error of some kind, try running the following command to set your Ruby version in the project.

rbenv local x.x.x

Where x.x.x is replaced by the version number named in the .ruby-version file in the app's root.

Install JavaScript Modules

These JavaScript modules (npm packages) are required by esbuild:

yarn install

Create the Database

When bundle and yarn have finished installing everything, it's time to get the TOP database set up. To create the database and load the schema:

rails db:create
rails db:environment:set RAILS_ENV=development
rails db:schema:load

Get a Github API Token

You will need a Github API Token when running TOP locally to update the curriculum. Without the token you will encouter rate-limiting errors and won't be able to create all the lessons.

You can obtain an API Token by going to personal access tokens in your Github user account settings and click the "generate new token" button. This will bring you to a new page. Give your token a description in the box provided, Something like "Odin " will do. Once that is done click the "generate token" button at the bottom of the page. The token highlighted in green is your new Github API token.

Copy your Github API token and edit your .env file with the content below, making sure to paste your API token in place of <your api token here>. Note that the APP_ID and SECRET are commented out. These are used in production and are not needed locally.

GITHUB_API_TOKEN: <your api token here>
#GITHUB_APP_ID: 1234
#GITHUB_SECRET: 1234

Run the Tests

You can now run all the tests, they should all be green

To run the rspec unit tests:

bin/rspec

Note

If you get an error stating Cliver::Dependency::NotFound and Could not find an executable and don't have Google Chrome installed, try installing Chrome.

Note

If ALL of your tests fail, check to make sure bundle install completed without error. You may need to allocate more space to your partition.

Seed the Database and Populate the Lesson Content

Next you need to seed the database with the course and lesson data:

rails db:seed

We pull in the lesson content from the Odin curriculum repository on Github. We have created a rake task to do this easily:

rails curriculum:update_content

Start the Server

You can now run the app on your local machine. First, start the server:

bin/dev

This command will run the processes listed in the Procfile.dev file. This includes the Rails server, a background worker for processing async jobs, and "watch" scripts for esbuild and CSS bundling. The watch scripts will allow you to make edits to the app's JS and CSS files and have those changes take effect without having to rerun bin/dev.

After running bin/dev, visit http://localhost:3000 to view TOP in your browser!

Note

You may be used to tools like nodemon that allow for hot reloads. There is not currently a solution for this configured for this app. So while your changes will immediately update the app's code, you'll have to manually refresh your browser to see the effect of your changes.

Optional Steps

Github OAuth

We allow users to create an account on the site with Github OAuth. To get this feature working locally follow the instructions in this section.

Go to OAuth Applications in your Github user account settings and click the "register a new application" button.

Fill in the form fields with the following:

Application Name odin

Homepage URL http://localhost:3000

Application Description the odin project

Authorization callback URL http://localhost:3000/users/auth/github/callback

Click the "Register application" button. This will display your Client ID and Client Secret which is what you will use to get OAuth working on your local machine.

Go to .env in your local project directory for The Odin Project and fill in the following:

GITHUB_API_TOKEN: <your api token here>
GITHUB_APP_ID: <your client ID here>
GITHUB_SECRET: <your client secret here>

To test all this is working correctly, run the app locally and try to sign up with Github.

Google OAuth

We also allow users to create an account on the site with Google OAuth. To get this feature working locally follow the instructions in this section.

Visit the Google API Console to obtain OAuth credentials and agree to terms of service.

1. Click "Select a Project" drop down

2. Click "New Project" button on top right

   1. Set project name to odin
   2. Location can be default No Organization
   3. Click "Create" button

3. Click "Credentials" in left nav.

   1. Navigate to "OAuth Consent Screen" on top nav.
      1. Set Application name odin
      2. Scroll to bottom and click "Save" button

4. Click "Create Credentials" drop down

   1. Select "OAuth Client ID"
   2. Select "Web Application" for Application type
   3. Fill in the form fields with the following:
      1. Name: odin
      2. Authorized Javascript Origins: http://localhost:3000 make sure to press Enter to add it
      3. Authorized redirects URIs: http://localhost:3000/users/auth/google/callback make sure to press Enter to add it
      4. Click "Create" button. This will display your Client ID and Client Secret which is what you will use to get OAuth working on your local machine.

5. Go to .env in your local project directory for The Odin Project and fill in the following:

   GOOGLE_CLIENT_ID: <your client ID here>
   GOOGLE_CLIENT_SECRET: <your client secret here>
   

To test all this is working correctly, run the app locally and try to sign up with Google.

Need Help with Anything Here?

If you run into any problems with the above instructions or have suggestions on how to improve them, please let us know by creating an issue.