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.

github screenshot

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.

git-bash screenshot

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.

git-bash screenshot

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. The domain you point at github.com should be the one in the CNAME file.

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. This example also illustrates the recommended practice of creating a TXT record with your account number.

dns screenshot

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

Register Domain on RdbHost Account

Add the chosen domain to your RdbHost account configuration at the /mbr/domain page.

domain screenshot

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.

three faves screenshot

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.

Database Roles

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.

role mgr screenshot

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. Setup roles on RdbHost, and grant appropriate privileges to tables and other resources..
  3. Create tables and indexes using the Rdbadmin utility.
  4. Develop your application, clear the whitelist, repopulate with valid queries by testing every app feature, and you are done.