isabella232 / doc-portal

df

Documentation Portal - Multiple Deliverable Version

This is a documentation portal written in Ruby, using Sinatra for routing and CouchDB for content storage and searching. The UI is controlled by Twitter Bootstrap.

Quick hosting using Heroku

1. Create a Heroku Account

2. Create a Cloudant Account

3. 

4. Answer questions on that web page. Use your own Cloudant database URL, please. It should be something like this: http://<username>:<password>@sanderson.cloudant.com You can use the default for initial testing, but please update it to use your Cloudant URL.

5. When the app is deployed, click View It. Sign in with username redsofa-qa password doc123456

Setting up the project to configure and customize

1. Set up git

2. Install Ruby 2.1.2 (I suggest using - RVM)

3. Clone this project

4. Install the gems in the Gemfile (I suggest using bundle)

Run it locally

1. Set up your database

   1. Set up couchdb
   2. Add lucene to couchdb

2. Set the CLOUDANT_URL environment variable

   • For a local database, do something like this: export CLOUDANT_URL=http://admin:admin@localhost:5984
   • For a hosted database, do something like this: export CLOUDANT_URL=http://<username>:<passcode>:<cloudant-host>.cloudant.com

3. Create a file named .env.development and add your CLOUDANT_URL export command to it (ie, export CLOUDANT_URL=http://admin:admin@localhost:5984)

4. Then run rake update_local_db

5. Review the log in log/upload_*.txt

6. Then run rake start_local

7. If you want to auto-load local changes, instead of start_local, use rake start_local_debug

8. Open your web browser and look at [http://localhost:5000]

   • If you are prompted to login, the username is redsofa-qa, password doc123456

Deploy it to heroku - manual

1. Create a Heroku Account

2. Install the Heroku toolbelt

3. Create a Cloudant Account

4. One time, initialize the project on heroku

rake initialize_heroku[app_name,CLOUDANT_URL ]

where *app_name* is the name you want for your app, and *CLOUDANT_URL* is the URL to your hosted database.  *Note*: Don't put spaces around the comma between *app_name* and *CLOUDANT_URL*.  If you do, you'll get an error.

1. Push your content to the remote database rake update_remote_db

2. Review the log in log/upload_*.txt

3. Validate it's working

   heroku open

   Username: redsofa-qa

   Password: doc123456

Customizing the look and feel

The project depends on Twitter Bootstrap for its look and feel. To customize, you need to do the following:

1. Install lessc and uglifyjs installed (the best way is to install them with npm, then npm install -g less uglify-js)

2. Customize the files in less/. See http://lesscss.org/ for details on less.

3. Due to an issue with less v2 (see http://stackoverflow.com/questions/26628309/less-v2-does-not-compile-twitters-bootstrap-2-x), modify vendor/twitter-bootstrap/less/navbar.less by changing

   .navbar-static-top .container,
   .navbar-fixed-top .container,
   .navbar-fixed-bottom .container {
      #grid > .core > .span(@gridColumns);
   }
   

   to

   .navbar-fixed-top .container,
   .navbar-fixed-bottom .container {
      width: (@gridColumnWidth * @gridColumns) + (@gridGutterWidth * (@gridColumns - 1));
   }
   

4. Run rake bootstrap:make

Updating the content with your own

The content in content/sample is there for example purposes. To serve up your own content, you need to do the following:

1. Move the content directory to content-bak (save the files for refernece)

2. Add your html files to content/lang-local/deliverable_name

3. Copy deliverable_metadata.json from the sample files and update it for your needs.

4. Copy sample.toc and update it for your needs. Copy it to deliverable_name.toc in content/lang-local/deliverable_name

5. If you have specific metadata requirements update lib/db/db_transaction.rb

Customizing the username and password

The username and password are stored in config/app_config.yaml. Update that file to change the username or password.

To turn off the required login, uncomment (remove the # character) the line that begins with LOGIN_REQUIRED.

© Copyright 2013 salesforce.com, inc.