Skip to content

Commit

Permalink
Update readme (#24)
Browse files Browse the repository at this point in the history 
* Adding the subdomain to avoid confusion on the lti url

* Making the apartment tenant consistent with the lti_key so it doesn’t break

* Editing the README to be more organized

* Changing client_application_name to match settings entries for the admin_app

* Setting the tenant to be the same as the lti_key to fix errors

* Removing changes to the Readme to push this branch along

* Reorganizing the Readme in hope it will make more sense.

* Making all the lines consistent

* Adding NodeJS as a requirement

* Removing extra lines
  • Loading branch information
@kamijean @jbasdf
kamijean authored and jbasdf committed Feb 14, 2017
1 parent e3a4fae commit 8f9290f
Showing 1 changed file with 98 additions and 137 deletions.
235 changes: 98 additions & 137 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,164 +1,112 @@
# LTI Starter App [![Build Status](https://travis-ci.org/atomicjolt/lti_starter_app.svg?branch=master)](https://travis-ci.org/atomicjolt/lti_starter_app) [![Coverage Status](https://coveralls.io/repos/github/atomicjolt/lti_starter_app/badge.svg?branch=master)](https://coveralls.io/github/atomicjolt/lti_starter_app?branch=master)
-----------------------
There are many starter kits that will help you get started with React and Redux.
This is the one created by, maintained by and used by [Atomic Jolt](http://www.atomicjolt.com).
Atomic Jolt uses this as application as a starting place for Ruby on Rails applications that
utilize React.
There are many starter kits that will help you get started with React and Redux. This is the one created by, maintained by and used by [Atomic Jolt](http://www.atomicjolt.com). Atomic Jolt uses this as application as a starting place for Ruby on Rails applications that utilize React.


## Build a new application using the LTI Starter App Rails application template:
## Getting Started

### Build a new application using the LTI Starter App Rails application template:
-----------
`rails new my_app -m https://raw.githubusercontent.com/atomicjolt/lti_starter_app/master/template.rb`
```
rails new my_app -m https://raw.githubusercontent.com/atomicjolt/lti_starter_app/master/template.rb
```

## Running LTI Starter App
### Prerequisites
-----------
See [Setting up React Rails Starter App](#setup) below to configuration the application.
Once setup Start Rails and the webpack server:
This application requires:

- Ruby
- Rails
- PostGreSQL
- NodeJS
- yarn

Learn more about:
- [Installing Rails](http://railsapps.github.io/installing-rails.html).
- [Installing PostGreSQL](https://wiki.postgresql.org/wiki/Detailed_installation_guides).
- [Installing Yarn](https://yarnpkg.com/lang/en/docs/install).

#### Canvas Developer ID and Key
You will need to [obtain a Developer ID and Key from an Account Admin for the instance of Canvas the tool will be installed in](#canvas_developer_key).

#### Default LTI Application
You will also need to setup a default lti application and lti application instance. See the [sections below](#setup) for information on setting up the default account.


## Running LTI Starter App
-----------
After [setting up the LTI Starter App](#setup), start Rails and the webpack server:
```
rails server
yarn hot
```


## <a name="setup"></a>Setting up LTI Starter App
-----------

### File Modifications
-----------

#### Change bin/bootstrap
In bin/bootstrap change the following line to point to a dropbox folder
containing the correct config files for the project:
DROPBOX_FOLDER=aj-dev/lti_starter_app

#### Setup .env
-----------
Rename `.env.example` to `.env` and configure it to your liking.

Note: the App and Assets subdomains must be different.

#### Modify application name
1. Open application.rb and change `ltistarterapp` to the name you choose.
2. Do a global search and replace for `lti_starter_app` and change it to the
name you choose.
3. Do a global search and replace for `ltistarterapp` (use only letters or
numbers for this name. Special characters like '_' will result in errors).
2. Do a global search and replace for `lti_starter_app` and change it to the name you choose.
3. Do a global search and replace for `ltistarterapp` (use only letters or numbers for this name. Special characters like '_' will result in errors).

### Setup script
Run the setup script to configure your local nginx and to setup symlinks to your
configuration files (database.yml, etc)
#### Setup config files with bin/setup script (optional)

##### Change bin/bootstrap
In bin/bootstrap change the following line to point to a dropbox folder containing the correct config files for the project. For example:
```
$ ./bin/setup
DROPBOX_FOLDER=aj-dev/lti_starter_app
```

## Canvas API
-----------
The LTI Starter app makes working with the Canvas API simple. See
[Canvas](Canvas.md) for more information. Note that working with the Canvas API
will require a server side proxy that is not part of this project.

#### Secrets file
-----------
Rename `config/secrets.example.yml` to `config/secrets.yml`. Open the file and change each entry to values that are relevant for your application.

*This file should not be committed to your repository.*

You will need to [obtain a Developer ID and Key from an Account Admin for the
instance of Canvas the tool will be installed in](#canvas_developer_key).

You will also need to setup a default lti application and lti application
instance. See the [seeds](#seeds) section below for information on setting
up the default account.

### Project Dependencies
-----------

#### Requirements
-----------
This application requires:

- Ruby
- Rails
- PostGreSQL
- npm
- yarn

Learn more about [Installing Rails](http://railsapps.github.io/installing-rails.html).

### <a name="seeds"></a>Setting up Database
-----------
Setup an admin user with:
##### Setup script
Run the setup script to configure your local nginx and to setup symlinks to your configuration files (database.yml, secrets.yml, etc)
```
$ rake db:setup
$ ./bin/setup
```

### <a name="developer_key"></a>Setting up OAuth
-----------
**Oauth2 Redirect URI:**
https://reactrailsstarterapp.atomicjolt.xyz/auth/[provider]/callback
#### Secrets file
Rename `config/secrets.example.yml` to `config/secrets.yml` and rename `config/database.example.yml` to `config/database.yml`.

**Icon URL:**
https://reactrailsstarterapp.atomicjolt.xyz/oauth_icon.png
Note: If you ran ./bin/setup it calls to the ./bin/bootstrap script which symlinks the files located in the path that was specified as the DROPBOX_FOLDER. If the database.yml and secrets.yml are located in that location then you won't need to rename them from .example.yml.

Once your request is approved you will receive a Key and Secret. Add these credentials to `config/secrets.yml` and
then add those values to devise.rb. It will look something like this:
Open the files and change each entry to values that are relevant for your application.

config.omniauth :github, Rails.application.secrets.github_developer_id, Rails.application.secrets.github_developer_key, scope: 'user,public_repo'
*These files should not be committed to your repository*

## Development
-----------

### Client
### <a name="database"></a>Setting up the Database
-----------

#### Webpack
-----------
Webpack is used to build the client side application. Configure the client application in client/config/settings.js

#### React
-----------
The React Rails Starter App uses React. All client side code can be found in the "client" directory.
This project contains the code required to launch a React application. index.html.erb contains the following
code which will launch a React application whose entry point is 'app.jsx'

Setup an admin user and the default lti application with:
```
<% content_for :head do -%>
<%= webpack_styles_tag 'styles' %>
<% end -%>
<%= render 'shared/default_client_settings' %>
<%= webpack_manifest_script %>
<div id="main-app"></div>
<%= webpack_bundle_tag 'app' %>
$ rake db:setup
```

### <a name="seeds"></a>Setting up Database

If you have setup .env and the secrets.yml file then the seeds file shouldn't need to be changed. However,
if you need to customize the values in the database or add addition records to the database,
open db/seeds.rb and configuration a default account for development and production.
Here's a summary of the values and their purpose:
If you have setup .env and the secrets.yml file then the seeds file shouldn't need to be changed. However, if you need to customize the values in the database or add addition records to the database, open db/seeds.rb and configuration a default account for development and production. Here's a summary of the values and their purpose:

- **code:** Uniquely identifies the account. This is used for the subdomain when running
applications on a single domain. By default this will be set to APP_SUBDOMAIN from the .env file.
- **domain:** Custom domain name. By default this is set to application_url from the secrets.yml file.
- **name:** Name the account anything you'd like. By default this is set to application_name from the secrets.yml file.
- **lti_key:** A unique key for the LTI application you are building. This will be provided to Canvas. By default this will be set to APP_SUBDOMAIN from the .env file.
- **lti_secret:** The shared secret for your LTI application. This will be provided to Canvas
and will be used to sign the LTI request. Generate this value using `rake secret`. Alternatively if you leave this field empty an LTI secret will be automatically generated for the account.
- **lti_secret:** The shared secret for your LTI application. This will be provided to Canvas and will be used to sign the LTI request. Generate this value using `rake secret`. Alternatively if you leave this field empty an LTI secret will be automatically generated for the account.
- **canvas_uri:** The URI of the Canvas institution to be associated with a specific account.

### <a name="canvas_developer_key"></a>Obtain a Canvas Developer Key
-----------
Only a Canvas Account Admin can create a developer key for your LTI Application. To create a key, go to Accounts, Developer Keys and enter the info described below below. Be sure to replace `ltistarterapp.atomicjolt.xyz` with your domain. (atomicjolt.xyz will only work for AtomicJolt employees). Also, note that 'ltistarterapp' is the subdomain specified in the .env file.

Only a Canvas Account Admin can create a developer key for your LTI Application. To create a key, go to
Accounts, Developer Keys and enter the info described below below. Be sure to replace `lti.atomicjolt.xyz` with your domain.
(atomicjolt.xyz will only work for AtomicJolt employees). Also, note that 'lti' is the subdomain specified in the .env file
You will need an ID and secret for development and for production. The development URI will use atomicjolt.xyz while the
production URI will use your domain (e.g. ltistarterapp.herokuapp.com).
You will need an ID and secret for development and for production. The development URI will use atomicjolt.xyz while the production URI will use your domain (e.g. ltistarterapp.herokuapp.com).

**Oauth2 Redirect URI:**
https://lti.atomicjolt.xyz/auth/[provider]/callback
https://ltistarterapp.atomicjolt.xyz/auth/[provider]/callback
**Key Name:**
Can be anything you choose (e.g. LTI Starter App)

Expand All @@ -169,27 +117,48 @@ Address that will receive email about technical issues related to the tool.
Unique ID for the tool (e.g. ltistarterapp)

**Redirect URI:**
https://lti.atomicjolt.xyz/users/auth/canvas/callback
https://ltistarterapp.atomicjolt.xyz/users/auth/canvas/callback
OR
https://ltistarterapp.herokuapp.com/users/auth/canvas/callback

**Icon URL:**
https://lti.atomicjolt.xyz/images/icon.png
https://ltistarterapp.atomicjolt.xyz/images/icon.png
OR
https://ltistarterapp.herokuapp.com/images/icon.png

Once you press Save Key, a Developer ID and Key will be generated and displayed in the Details column of the Developer Keys table when you mouse over the row. Add these credentials to your .env file or `config/secrets.yml` file under CANVAS_DEVELOPER_ID and CANVAS_DEVELOPER_KEY (in .env) or `canvas_developer_id` and `canvas_developer_key` (in secrets.yml).


## Canvas API
-----------
The LTI Starter app makes working with the Canvas API simple. See [Canvas](Canvas.md) for more information.
The LTI Starter app makes working with the Canvas API simple. See [Canvas](Canvas.md) for more information. Note that working with the Canvas API will require a server side proxy that is not part of this project.

#### Assets

## Development
-----------
Any files added to the assets directory can be used by in code and assigned to a variable. This
allows for referring to assets using dynamically generated strings. The assets will be built according to
the rules specified in your webpack configuration. Typically, this means that in production the names will
be changed to include a SHA.

### Client
-----------

#### Webpack
Webpack is used to build the client side application. Configure the client application in client/config/settings.js

#### React
The React Rails Starter App uses React. All client side code can be found in the "client" directory. This project contains the code required to launch a React application. index.html.erb contains the following code which will launch a React application whose entry point is 'app.jsx'

```
<% content_for :head do -%>
<%= webpack_styles_tag 'styles' %>
<% end -%>
<%= render 'shared/default_client_settings' %>
<%= webpack_manifest_script %>
<div id="main-app"></div>
<%= webpack_bundle_tag 'app' %>
```

#### Assets
Any files added to the assets directory can be used by in code and assigned to a variable. This allows for referring to assets using dynamically generated strings. The assets will be built according to the rules specified in your webpack configuration. Typically, this means that in production the names will be changed to include a SHA.

First importing the assets:
`import assets from '../libs/assets';`
Expand All @@ -206,23 +175,14 @@ The value can then be used when rendering:
}`

#### Static
-----------
Files added to the static directory will be copied directly into the build. These files will not be renamed.


#### Tests
-----------
Karma and Jasmine are used for testing. To run tests run:


`yarn test`


#### Check for updates
-----------
Inside the client directory run:

`yarn upgrade-interactive`
```
yarn upgrade-interactive
```


## Deployment
Expand All @@ -248,11 +208,11 @@ $ git push heroku master
By default `config/unicorn.rb` is setup to deploy to Heroku. Open that file, comment out the Heroku section and uncomment the other configuration to setup unicorn for deployment to another service like AWS.

## Examples

-----------
Atomic Jolt has built a number of applications based on this source.

### Demo Arigato

-----------
This project was created for the Sales team at Instructure. It makes it simple to populate a sample Canvas course using values from Google Drive Spreadsheets.

Source Code: [https://github.com/atomicjolt/demo_arigato](https://github.com/atomicjolt/demo_arigato)
Expand All @@ -271,20 +231,21 @@ You may need to install chromedriver if you haven't already.
$ brew install chromedriver
```

To run tests:
To run Ruby tests:

```
$ rake spec
```

## TODO

If an admin changes the developer key and secret then existing authentications are invalid.
This will result in a 500 error. You will see the following in the log:
LMS::Canvas::InvalidRequestException (Status: 400 Error: ....

To fix this remove all entries in the Authentications table. In the future we should detect an
invalid api token and then remove the db record forcing a new OAuth dance.
To run Karma and Jasmine tests run:

```
$ yarn test
```

## TODO
-----------
If an admin changes the developer key and secret then existing authentications are invalid. This will result in a 500 error. You will see the following in the log:
LMS::Canvas::InvalidRequestException (Status: 400 Error: ....

To fix this remove all entries in the Authentications table. In the future we should detect an invalid api token and then remove the db record forcing a new OAuth dance.

0 comments on commit 8f9290f

Please sign in to comment.