|
1 |
| -ember-jsonapi-docs is a script for turning ember API doc build output into jsonapi compliant data for use in various applications seeking to use the Ember API. |
2 |
| -[](https://travis-ci.org/ember-learn/ember-jsonapi-docs) |
| 1 | +# Ember JSON API Docs [](https://travis-ci.org/ember-learn/ember-jsonapi-docs) |
3 | 2 |
|
4 |
| -The script pulls yuidoc build output from all Ember versions from Amazon S3, converts it to json-api, and pushes it to CouchDB. |
| 3 | +This app is for turning ember API doc build output into [json api](http://jsonapi.org/) compliant data for use in various applications seeking to use the Ember API. |
5 | 4 |
|
6 |
| -# Setting up a local API Data Environment |
7 |
| -Follow these steps to get this project generating Ember API data into a local pouch db environment. |
8 |
| -You can use this environment for testing out the ember-api-docs app locally, as well as for development on this project. |
| 5 | +The script pulls yuidoc build output from all Ember versions from Amazon S3, converts it to json api format and pushes it to CouchDB. |
| 6 | +You can setup a CouchDB instance either [locally](#setting-up-a-local-couchdb-instance) or [on cloundant](#setting-up-a-couchdb-on-cloudant) for testing out changes to this app. |
9 | 7 |
|
10 |
| -1. Clone or Fork/Clone ember-jsonapi-docs from github: https://github.com/ember-learn/ember-jsonapi-docs |
11 | 8 |
|
12 |
| -2. Install the latest release of CouchDB: http://couchdb.apache.org/ |
| 9 | +## Setting up a local CouchDB instance |
13 | 10 |
|
14 |
| -3. Once installed, visit http://localhost:5984/_utils. From the top navigation section, Click "Create Database" and type in "docs". |
15 |
| - |
16 |
| -4. Create a couchdb admin user. Got to the section in the left nav called "Admin Party!", and supply a username and password. |
17 |
| - |
18 |
| -5. Set the following environment variables: |
19 |
| - ``` |
20 |
| - COUCH_URL=http://127.0.0.1:5984/docs |
21 |
| - COUCH_USERNAME=<your admin couchdb username> |
22 |
| - COUCH_PASSWORD=<your admin couchdb password> |
23 |
| - ``` |
| 11 | +1. Install the latest release of [CouchDB](http://couchdb.apache.org/). |
| 12 | +1. Once installed, visit the [CouchDB UI](http://localhost:5984/_utils). From the top navigation section, Click "_Create Database_" and type in "*ember-api-docs*". |
| 13 | +1. Create a CouchDB admin user. Got to the section in the left nav called "_Admin Party!_", and supply a username and password. |
| 14 | +1. Set up CORS for CouchDB |
| 15 | + An easy way to do this is to use the script at https://github.com/pouchdb/add-cors-to-couchdb |
| 16 | + |
| 17 | + ```shell |
| 18 | + npm install -g add-cors-to-couchdb |
| 19 | + add-cors-to-couchdb -u <your admin couchdb username> -p <your admin couchdb password> |
| 20 | + ``` |
24 | 21 |
|
25 |
| -6. Set up AWS access |
26 | 22 |
|
27 |
| - One way to do this is to set the following environment variables |
| 23 | +## Setting up a CouchDB on cloudant |
28 | 24 |
|
29 |
| - ``` |
30 |
| - AWS_ACCESS_KEY_ID |
31 |
| - AWS_SECRET_ACCESS_KEY |
32 |
| - ``` |
| 25 | +1. A [cloudant](https://cloudant.com/) account is neccessary before proceeding with the following steps. |
| 26 | +1. Create a new Database and give it the name "*ember-api-docs*". |
| 27 | +1. Goto the "_Permissions_" tab in the nav. |
| 28 | +1. Click on "_Generate API Key_", save the credentials showed on the UI as we'll be using this in the next section as the CouchDB credentials. |
| 29 | +1. Click on the _"_writer"_ checkbox for the API user so that it can push docs to cloudant. |
| 30 | +1. Navigate to your account settings & in the "_CORS_" tab ensure that its enabled for all domains. |
33 | 31 |
|
34 |
| - These values can be for any valid AWS account. The process accesses builds.emberjs.com in read-only mode, which is public. |
35 | 32 |
|
36 |
| -7. Set up cors for CouchDB |
| 33 | +## Running the app |
37 | 34 |
|
38 |
| - An easy way to do this is to use the script at https://github.com/pouchdb/add-cors-to-couchdb |
| 35 | +1. Fork/Clone [ember-jsonapi-docs](https://github.com/ember-learn/ember-jsonapi-docs) |
| 36 | +1. Run `npm install` or `yarn` |
| 37 | +1. Set the following environment variables: |
39 | 38 |
|
| 39 | + ```shell |
| 40 | + export COUCH_URL=http://localhost:5984/ember-api-docs # or COUCH_URL=https://user-name.cloudant.com/ember-api-docs |
| 41 | + export COUCH_USERNAME=<your couchdb username> |
| 42 | + export COUCH_PASSWORD=<your couchdb password> |
| 43 | + ``` |
| 44 | +1. Set up AWS access |
| 45 | + ```shell |
| 46 | + export AWS_ACCESS_KEY_ID=xxxxxx |
| 47 | + export AWS_SECRET_ACCESS_KEY=xxxxx |
40 | 48 | ```
|
41 |
| - npm install -g add-cors-to-couchdb |
42 |
| - add-cors-to-couchdb -u <your admin couchdb username> -p <your admin couchdb password> |
43 |
| - ``` |
| 49 | + The app accesses builds.emberjs.com (an Amazon S3 bucket) in read-only mode, which is public. This requires any valid AWS credentials. |
| 50 | +
|
| 51 | + You can get your credentials by logging into your [AWS console](https://console.aws.amazon.com) and navigating to "_My Security Credentials_" under your profile name. You can generate a new pair under the "_Access Keys (Access Key ID and Secret Access Key)_" section. |
| 52 | +1. To test your changes in the app run, |
| 53 | + ```node index.js 2.11``` |
| 54 | + This will run the app only for the specified version of the docs. Once complete, if no errors you should see your doc database |
| 55 | + populated with data from your CouchDB admin ui. When no version is passed, the app will try to process all |
| 56 | + ember versions since 1.0 which takes high memory & time to complete. If you intend it, then run `node --max_old_space_size=8192 index.js`. |
| 57 | + You are setting your node max heap space to 8GB, so make sure you have that much space available on your machine. |
44 | 58 |
|
45 |
| -8. Finally run `node --max_old_space_size=8192 index` from the root of th repo. |
46 | 59 |
|
47 |
| - This will take a long time if its your first time. |
48 |
| - You are setting your node max heap space to 8GB, so make sure you have that much space available on your machine. |
49 |
| - Once complete, if no errors you should see your doc databse populated with data from your couchdb admin ui. |
50 |
| - |
| 60 | +## Setting up a new production instance |
| 61 | +
|
| 62 | +1. Follow the steps from [setting up a CouchDB on cloudant section](#setting-up-a-couchdb-on-cloudant) |
| 63 | +1. Run `npm start` or `yarn start` from your local. This is required since travis kills a build if [a task crosses 50mins](https://docs.travis-ci.com/user/customizing-the-build#Build-Timeouts), & the first run will take 50+ mins to complete. |
| 64 | +1. On Travis UI [enable cron jobs](https://docs.travis-ci.com/user/cron-jobs/) for daily/hourly basis so that newer docs get indexed incrementally. |
0 commit comments