Changeset 520

Timestamp:

03/15/14 01:47:44 (11 years ago)

Author:

hendrikvanantwerpen

Message:

Updated README and made syncs more resilient.

Location:

Dev/trunk

Files:

• Gruntfile.js (modified) (2 diffs)
• README.md (modified) (1 diff)

Dev/trunk/Gruntfile.js

@@ -178 +178 @@
                     body: {
                         source: "<%= herokuConfig.CLOUDANT_URL %>/<%= dbName %>",
-                        target: "<%= dbName %>"
+                        target: "<%= dbName %>",
+                        create_target: true
                     },
                     json: true
@@ -189 +190 @@
                     body: {
                         source: "<%= dbName %>",
-                        target: "<%= herokuConfig.CLOUDANT_URL %>/<%= dbName %>"
+                        target: "<%= herokuConfig.CLOUDANT_URL %>/<%= dbName %>",
+                        create_target: true
                     },
                     json: true

Dev/trunk/README.md

@@ -9 +9 @@
 with _Grunt_, a node based task runner.
 
-First make sure _node_, _npm_ and _couchdb_ are installed. Then
-install all dependencies by running `npm install`. To run _grunt_,
-you'll have to install the commandline client with `npm install -g
-grunt-cli`.
+First make sure _node_, _npm_, _couchdb_, _heroku_, _formena_, _git_
+and _svn_ are installed. To run _grunt_, you'll have to install the
+commandline client with `npm install -g grunt-cli`.
+
+QED can run in two modes, _dev_ and _production_. This is controlled
+by the environment variable `QED_ENV`. If it is not present, _dev_ is
+the assumed mode. In development mode, QED runs agains another
+database than in production. So, to run the production server, you
+must use `QED_ENV=production grunt run`. Usually when developing you
+will use the dev mode and you can omit the QED_ENV variable. The value
+of QED_ENV on heroku is already set to production (this can be done
+with `heroku config:set QED_ENV=production --app quod-erat` and is
+persisent).
 
 From source to a deployable version goes in few steps.
- 1. Develop in `src`.
- 1. Create a development version with `grunt build`. This will put a
-    complete uncompressed version in `build/development`.
- 1. Run the development version with `node server/standalone.js` or
-    `foreman start`. For the last option, you have to have the Heroku
-    chain installed.
- 1. When editing more files, you can skip copying the fixed
-    dependencies and only process our own source files by running
-    `grunt compile`. If dependencies change (e.g. you installed node
-    modules) or you have the feeling something is weird, just do a
-    clean build by running `grunt build` again. Don't forget to
-    restart the server.
- 1. When you feel your changes are production ready, create a
-    production version by running `grunt deploy`. This will do a
-    _Dojo_ build on the client, creating compressed CSS and
-    Javascript.
- 1. You can test this version with the same commands as the
-    development version, but now from the `build/production`
-    directory. You can distribute the content is this directory as a
-    release.
- 1. If you want to deploy to Heroku, do the following:
-    ```sh
-    $ git clone git@heroku.com:quod-erat.git build/quod-erat
-    $ cd build/quod-erat
-    $ rm -rf *
-    cp -r ../production/* .
-    git add .
-    git commit -a -m "Something informative goes here..."
-    git push
-    ```
+ 1. Develop in `src`. You can run `grunt` (or `grunt compile`) to do
+    compiling of Coffee and LESS sources and linting of Javascript,
+    HTML etc.
+ 1. Run a server with `grunt run` and test. If client sources are
+    changed, you only have to run `grunt compile` and reload the
+    browser, for server sources you have to restart it.
+ 1. You can create a _Dojo_ build with `grunt build`, which will merge
+    and compress sources. You can also run `grunt run-build`, which
+    will do the build and start it locally for testing.
+ 1. When you feel your changes are production ready, you can deploy to
+    Heroku by running `grunt deploy`. The heroku app must know about
+    _quod-erat_ already, so you might have to add it by hand the first
+    time.
 
-File organisation
------------------
+## Database management
+
+There are _grunt_ tasks to push local database to Cloudant, pull the
+oter way or make a backup of the Cloudant database. Which database is
+used (dev or production) is again controlled by `QED_ENV`.
+
+In `src/server/bin` are some scripts to check if all database
+documents are valid and to upload the latest version of the design
+documents. Both the design documents and the database schema are
+versioned and QED won't start if the versions don't match.
+
+If an update required changes to (normally) immutable documents, you
+can disable the modification check with
+`config-db-for-upgrade.js`. It's usually a good idea to write and
+update script instead of doing things by hand. Don't forget to restore
+the check with `config-db.js`, although a server restart will also do
+that for you.
+
+Synchronisation doesn't ignore validation checks, so if you had to
+disable the validation to do an upgrade, you also have to disable
+validation on the database that you synchronize to. Currently this is
+not automated, so you have to run the scripts yourself in a sane
+order.
+
+If you want to test locally but with the Cloudant database instead of
+localhost, run like `CLOUDANT_URL=<ur> QED_ENV=dev grunt run`. You can
+get the url by running `heroku config:get CLOUDANT_URL --app
+quod-erat`.
+
+## File organisation
 
  * _/_ Project root