Site hosting on Github.com

Rdbhost makes relational databases available to JavaScript apps in the browser. You do have to host the static app pages somewhere, and while you can store static pages (and other files) on Rdbhost, other options can be attractive. Github will host pages, under your domain name even, with a git DVCS uploading mechanism, and can be used to host the static part of your database-backed JavaScript application.

Here is an overview of how to setup a site on Github.com, with Rdbhost database hosting.

Create a Github Account:

This is very straightforward, following the prompts at Github. You do need an account per site, each with its own public key.

Create an Eponymous Repository

Create a new repository in your account, named for the account; If your account is named 'example', the repository would be 'example.github.com'. There are well-written step-by-step instructions for setting up pages on pages.github.com Read the 'User & Organization Pages' section at the top, and the 'Custom Domains' section at the bottom.

The instructions on github.com seem to expect a bash shell. I used windows git-bash, which is built on msys, and it works fine.

Once the eponymous repository is created, commited, and pushed, wait a few minutes, and you should have a site at 'example.github.com'. If you did not include an index.html file, you will see a github error page, but that's ok for now. We still need to setup the real domain name.

The following two screenshots show the sequence of git commands and git's responses, for setting up Rdbhost's demo page.

Put Page Content in Repo

Create a file 'index.html' in your new repository, and commit and push it. The site indicates putting the file in the 'master' branch, but that is the default. Also create a file called 'CNAME', and put your domain name in it, as the only line. My repository CNAME file says 'gh.rdbhost.com', but domains without subdomain work as well.

Setup Domains

To use the recommended JavaScript library for Rdbhost, you need a site domain that you own, and can setup subdomains on. In your domain registrar's domain manager, create a principle domain (with or without subdomain) that points at github.com, and another subdomain that points at www.rdbhost.com. For example, your github pages could be www.example.com, and the database subdomain would be rdbhost.example.com. This is the same general subdomain configuration used for a JavaScript app hosted anywhere. The domain/subdomain you point at github.com should be the one in the CNAME file.

The alternate JavaScript library relies on CORS (Cross Origin Resource Sharing) compliance by the user's browser, and only relatively modern browsers comply.

We have a tutorial on setting up domain pointers at GoDaddy, and the following is a screenshot of how one registrar handles zone editing, and Rdbhost's domain configuration.

After you commit and push the CNAME file, you should be able to access your static index.html at that domain.

Develop Your App

Develop your app in your 'example.github.com' folder, and periodically commit and push it to the github.com server. You will be able to test it at the internet domain as well as on localhost.

We have a demonstration app, on gh.rdbhost.com, called 'Three Faves'. This is the simplest database example app I could think of that might be fun. You enter 3 favorite things, and it looks for other people in the database that also entered any of those things, and shows you what else they entered. It is completely anonymous, and has a crowd-sourced bad-words filter.

The source for this app is in the rdbhost.github.com public github repository. It is one-file resource, with css and javascript all rolled in there, except for the rdbhost.jquery.js database library.

Prior to writing and testing the application, put the Rdbhost server into training mode, where it accepts and white-lists any queries received from the training client machines. When the app is debugged, you can clear the white-list (also called the lookup.preauth_queries table) to remove cruft, and repopulate it by rerunning the application, and then turn training off. Training mode is enabled and disabled from the training page, linked from the account profile.

You also need to create the database roles that will query the database. Generally, for a JavaScript application, you would use the preauth or the auth role, perhaps in combination with the reader role. The roles are created from the role manager page. Privileges to the various tables and resources must be granted to the chosen roles, using SQL GRANT statements.

The 'Three Faves' app uses the preauth role, which is only permitted to run white-listed queries, so the database is protected from somebody trying to run arbitrary destructive queries as that role.

The creation of tables, views, indexes, etc, can be incorporated into your app, but the Rdbadmin utility is useful for creating initial tables and such. Use SQL GRANT to grant necessary privileges to the chosen roles.

To summarize the main points:

1. You can host static pages on Github.com, under your own domain, and use Rdbhost hosted databases from those static pages.
2. You need to point your own domain to your Github page, and also point a subdomain at the Rdbhost server, in order for the JavaScript library to manage the cross-domain data transfer.
3. Setup roles on Rdbhost, and grant appropriate privileges to tables and other resources..
4. Create tables and indexes using the Rdbadmin utility.
5. Put account in training mode, develop your application, clear the whitelist, repopulate with valid queries, and then disable training mode.