Skip to content

Commit b63f93f

Browse files
authored
Merge pull request #16 from sivakumar-kailasam/detailed-readme
Add info on setting up cloudant for development & production. [ci skip]
2 parents b4a63f2 + 0816d9b commit b63f93f

File tree

1 file changed

+49
-35
lines changed

1 file changed

+49
-35
lines changed

README.md

Lines changed: 49 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,64 @@
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-
[![Build Status](https://travis-ci.org/ember-learn/ember-jsonapi-docs.svg?branch=master)](https://travis-ci.org/ember-learn/ember-jsonapi-docs)
1+
# Ember JSON API Docs [![Build Status](https://travis-ci.org/ember-learn/ember-jsonapi-docs.svg?branch=master)](https://travis-ci.org/ember-learn/ember-jsonapi-docs)
32

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.
54

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.
97

10-
1. Clone or Fork/Clone ember-jsonapi-docs from github: https://github.com/ember-learn/ember-jsonapi-docs
118

12-
2. Install the latest release of CouchDB: http://couchdb.apache.org/
9+
## Setting up a local CouchDB instance
1310

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+
```
2421

25-
6. Set up AWS access
2622

27-
One way to do this is to set the following environment variables
23+
## Setting up a CouchDB on cloudant
2824

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.
3331
34-
These values can be for any valid AWS account. The process accesses builds.emberjs.com in read-only mode, which is public.
3532
36-
7. Set up cors for CouchDB
33+
## Running the app
3734
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:
3938
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
4048
```
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.
4458
45-
8. Finally run `node --max_old_space_size=8192 index` from the root of th repo.
4659
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

Comments
 (0)