Get synced

Sync in general is easy. First, run CouchDB somewhere. Then tune its settings a little to enable CORS. Then create remote DB and paste it’s URL into CloudWall DB sync settings. Save settings – and you are synced.

There are several common scenarios, that are described step by step.

Your own CouchDB instance

Nearly any web-connected machine can run CouchDB. It works pretty fine even in a very lean environment – 256Mb, old Celeron and so on. CouchDB is very reliable and power-off resistant.

1. Install and run

Download and install appropriate distributive of CouchDB to your server. It takes minute or two, really. Ensure CouchDB launches on OS start.

Note, that you need 1.5.1+ version of CouchDB, and persistent web connection with static IP or binded URL. If you decide to keep original 5984 Couch port untouched, you must enable this port for in and out connections.

When CouchDB is installed, run it – and you’ll get browser open with CouchDB admin panel, is’s named Futon and looks like this. 

Futon, CouchDB admin panel with several DBs created.

Take a look at the lower right corner of your admin panel and click Create admin link. Enter login and password – now you private cloud is protected.

2. Configure auth and CORS

Auth config is required to avoid annoying browser popups when bowsers connect to you cloud. CORS is a feature turning off end users’ cross origin sandboxes.

Both are tuned using link Configuration in Futon right panel. Go to config and edit/add some config vars. They are:

[cors] section

credentialstrue
headersaccept, authorization, content-type, origin
methodsGET,POST,PUT,DELETE,OPTIONS,HEAD
originshttp://cloudwall.me

[couch_httpd_auth] section

require_valid_user
false

[httpd] section

enable_corstrue

3. Create DB

External sync settings are in the middle

Now CORS is ready. Press Create DB button in the left bottom corner of CloudWall and name your new DB. If you want your DB to be public, you’re done. Your cloud address now is http://your.domain:5984/dbname.  

Now open DB settings and put this address into sync property of DB you want to get public. Set To and From directions of sync and duration. Zero interval means continuous replication.

Now you can share your cloud with friends – just send them a link. And with all other world – if someone guess an URL.

4. Protect DB

There are two cases of restricted group: a) all can read and write, b) there are users in read-only mode.

Scenario A. All can contribute

If you trust enough all contributors, you can create single login and password and restrict CouchDB access. Then link you share will look like http://user:pwd@your.domain:5984/db.

You can make many user account inside Couch and manage their access rights individually. CouchDB has built-in interfaces for it.

Unfortunately, in this way you can not restrict some users to be in read-only mode.

Scenario B. Several contributors and many readers

To restrict write access to your cloud for several users, you can create special-structured doc inside your server DB. In Futon (CouchDB admin panel) go to DB, click Create new doc, copy below code and save.

<!-- Put HTML code here -->
 
 
{
  "_id":"_design/auth", 
  "language": "javascript",
  "validate_doc_update": "function(n,o,u){if(n._id&&!n._id.indexOf(\"_local/\"))return;if(!u||!u.roles||u.roles.indexOf(\"_admin\")==-1){throw({forbidden:'Denied.'})}}"
}
 
/* Container for CSS code */
 
 

The code allows only users of group _admin to write updates. You can change code and grant write permissions to other groups.

CouchDB on Amazon EC2

There is nothing special about installing CouchDB to Amazon EC2 instance – just deploy and run instance, download CouchDB and install. Open 5984 port and do all the steps above. 

If you have 10-20 users – T2.micro is really enough. May be you’ll need to extend storage – default is about 8Gb.

IBM Cloudant 

There is nothing special about CouchDB on IBM Cloudant – except CORS. To enable CORS you are to hack Cloudant a little. Code for enabling CORS on Cloudant:

curl -i -u USERNAME -X PUT https://USERNAME.cloudant.com/_api/v2/user/config/cors -H "Content-Type: application/json" -d '{"enable_cors":true,"allow_credentials":true,"allow_methods":["GET","PUT","POST","DELETE","OPTIONS","HEAD"],"origins":["http://cloudwall.me"],"headers":"accept, authorization, content-type, origin"}'
 
 
 
/* Container for CSS code */
 
 

Smileupps

You can use Smileupps CouchDB instances without any specialties, just deploy an instance and set it up as regular CouchDB.

Important notes 

Keeping your data synced is a good practice since CloudWall is beta. It is built on top of many open-source and fast evolving third-party libraries. Also it is an open platform – you can receive code, that impacts system stability. 

 So be smart and get your local DBs synced with external CouchDB if you keep sensitive data in browser. 

Real-time continuous replication can be traffic-consuming – so if you work with docs, that need no immediate propagation, set replication interval to number greater than zero. This approach also helps to save money if you are connected to Cloudant or Smileupps.