-
Notifications
You must be signed in to change notification settings - Fork 2.1k
Running The Odin Project Locally
This page assumes that you have already installed Ruby, Rails and PostgreSQL. Please go back to the Linux Installation Instructions or Mac Installation Instructions if you haven't already.
The very first thing you need to do is fork the repo to your own Github, similar to when contributing or adding your student solutions to the curriculum. Once that's done, make sure you clone your forked copy onto your machine.
$ git clone <ssh:url>
Now that you have the repo locally, we can start getting set up.
First, make sure you're in the theodinproject
directory. All instructions should be followed while inside of that directory.
$ cd theodinproject
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 .env
to include your Postgres Username and Password.
#------------------------#
# DATABASE CONFIGURATION #
#------------------------#
POSTGRES_USERNAME: 'your-username'
POSTGRES_PASSWORD: 'your-password-here'
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 2.6.5
Install JavaScript modules (npn packages) required by Webpacker:
$ yarn install
Note: If you get an error about yarn and are on a flavor of Ubuntu, follow the steps here to install yarn on your machine. Once that's done, run the command Rails suggests and try re-running the above commands.
When bundle and yarn have finished installing everything, it's time to get the TOP database set up.
Create the database and load the schema:
$ rails db:create
$ rails db:environment:set RAILS_ENV=development
$ rails db:schema:load
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
You can now run all the tests, they should all be green
To run the rspec unit tests:
$ rspec
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
You can now run the app on your local machine. First, start the server:
$ rails server
and then visit http://localhost:3000 to view TOP in your browser!
Note for macOS 10.13 and above: You may need to run export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES
before rails server
. See this blog post for more information.
Mailchimp integration is setup to add newly registered users to a specified mailing list. This is done via the Mailchimp API and gem Gibbon. In order to enable this functionality in your local development and test environments you'll need to:
- Create a Mailchimp account
- Get a Mailchimp API key
- Create a list to which development/test members will be added
- Get the list ID
Finally, you need to add the API key and list ID to your .env
:
MAILCHIMP_API_KEY: <your api key here>
MAILCHIMP_LIST_ID: <your list id here>
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.
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.
-
Click "Select a Project" drop down
-
Click "New Project" button on top right
- Set project name to
odin
- Location can be default
No Organization
- Click "Create" button
- Set project name to
-
Click "Credentials" in left nav.
- Navigate to "OAuth Consent Screen" on top nav.
- Set Application name
odin
- Scroll to bottom and click "Save" button
- Set Application name
- Navigate to "OAuth Consent Screen" on top nav.
-
Click "Create Credentials" drop down
- Select "OAuth Client ID"
- Select "Web Application" for Application type
- Fill in the form fields with the following:
- Name:
odin
- Authorized Javascript Origins:
http://localhost:3000
make sure to press Enter to add it - Authorized redirects URIs:
http://localhost:3000/users/auth/google/callback
make sure to press Enter to add it - Click "Create" button. This will display your
Client ID
andClient Secret
which is what you will use to get OAuth working on your local machine.
- Name:
-
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.
If you have any problems getting anything set up in this guide please let us know in our Admin room in Discord
Wiki Home | Odin Web App Home | Odin Site Home | Odin Org Home
Want to contribute to this wiki? Open an issue to suggest changes and improve these docs 🚀