README.md

   1 Herouter
   2 ========
   3
   4 This is a small flask application that redirects an entire host to a
   5 different domain. This is your tool if you need to direct your
   6 non-www host example.com to www.example.com hosted on GitHub Pages or
   7 another service that does not allow several hosts to be served.
   8
   9 Example
  10 -------
  11
  12 You will best understand the behavior of the application by seeing by
  13 yourself. There are three views:
  14
  15 * [Dashboard](http://dash.herouter.fuk.fi/) in the `HEROKU_HOST`
  16 * [Error page](http://snap.herouter.fuk.fi/) if URL is not
  17   configured.
  18 * [Redirect](http://www.herouter.fuk.fi/) redirects to this page
  19   repository
  20
  21 Of course none of this will work if the last build has failed:
  22
  23 [![Build Status](https://ferrix.ci.cloudbees.com/job/Herouter/badge/icon)](https://ferrix.ci.cloudbees.com/job/Herouter/)
  24
  25 Deployment
  26 ----------
  27
  28 Deploying the application is easy
  29
  30 Create a new Heroku (cedar) app
  31
  32     git clone http://github.com/fubaz/herouter
  33     heroku create
  34     heroku rename myherouter
  35
  36 Add CouchDB service
  37
  38     heroku addons:add cloudant:oxygen
  39
  40 Configure default dashboard URL
  41
  42     heroku config:set HEROKU_HOST=myherouter.herokuapp.com
  43
  44 Deploy
  45
  46     git push heroku master
  47
  48 In case you want to register your hosts with Google Apps or
  49 Webmaster Tools, you should copy the alphanumeric string from the URL
  50 given by the HTML verification method. (eg. google8f7f61119a558993.html)
  51
  52     heroku config:set GOOGLE_VERIFICATION=8f7f61119a558993
  53
  54 This will make the file appear on all redirected domains.
  55
  56 Configuration
  57 -------------
  58
  59 There is currently no nice way to configure the service from the command
  60 line or web. Luckily CouchDB provides a nice web interface that can be
  61 accessed through Heroku.
  62
  63     heroku addons:open cloudant
  64
  65 In the user interface create a new database called 'router'. Then create
  66 a document whose `_id` would be the host like `example.com`. Add a field
  67 called `destination` and give it the destination address like
  68 `http://www.example.com`. The scheme does not need to be http but it is
  69 recommended to have some scheme there.
  70
  71 You can do this from `python` (or `heroku run python`) and configure using
  72 the following functions:
  73
  74     from router import get_redirect, add_redirect, del_redirect
  75     add_redirect('example.com', 'http://www.example.com/')
  76     get_redirect('example.com')
  77     del_redirect('example.com')
  78
  79 You will need to add incoming addresses to your heroku application as well.
  80
  81     heroku domains:add example.com
  82
  83 Then you need to follow Heroku's instructions on what to tell your DNS
  84 provider or server.
  85
  86 Special tricks
  87 --------------
  88
  89 You can inject a path, query parameters and a fragment in the destination
  90 URL. In theory, it is possible to deliver authentication information, it
  91 is however not recommended. The redirect will combine the query parameters
  92 with whatever the user sets:
  93
  94     source:      http://example.com/baz/?foo=bar
  95     destination: https://root:secre7@www.example.com/p?foo=baz&nop=1#e
  96     result:      https://root:secre7@www.example.com/p/baz?foo=bar&nop=1#e
  97
  98 These options can be changed in the CouchDB by giving additional fields to
  99 destinations. For example the following scenario would change with
 100 `strip_path = true` and `prefer_destination`:
 101
 102     source:      http://example.com/baz/?foo=bar&bar=foo
 103     destination: https://root:secre7@www.example.com/p?foo=baz&nop=1
 104     result:      https://root:secre7@www.example.com/p?foo=baz&nop=1&bar=foo
 105
 106 The entire domain can be redirected to a single url by setting
 107 `strip_path = true` and `strip_query = true`:
 108
 109     source:      http://example.com/bar/?foo=bar&bar=foo
 110     destination: https://www.example.com/?foo=baz#bottom
 111     result:      https://www.example.com/?foo=baz#bottom
 112
 113 These variables can be set through `python` by giving keyword parameters to
 114 `add_redirect`. All of them default to false:
 115
 116     add_redirect('x.com', 'y.com', strip_path=True, strip_query=True)
 117     add_redirect('a.com', 'b.net', prefer_destination=True)
 118     add_redirect('d.ork', 'd.org', True, False, True)
 119
 120 Debugging
 121 ---------
 122
 123 If you want to debug the application, it is best to run it on
 124 localhost. Sadly, that requires some setting up. You will need access
 125 to a CouchDB server and run the following to install the packages
 126 (either in a virtualenv or directly on command line):
 127
 128     pip install -r requirements.txt
 129
 130 Next, you need to set some environment variables:
 131
 132     # Instead of redirecting, show the URL
 133     # Value does not matter, true if defined
 134     export DEBUG_REDIRECT=a
 135
 136     # Show errors to user on the browser
 137     # Value does not matter, true if defined
 138     export DEBUG=g
 139
 140     # Database url if something else than http://localhost:5984/
 141     export CLOUDANT_URL=http://server.com:5984/
 142
 143     # Show dashboard on URL other than localhost:5000
 144     export HEROKU_HOST=x
 145
 146     # If you want to change the port to something else than 5000
 147     export PORT=4999
 148
 149 By default, the port is 5000 and localhost:5000 is the default
 150 dashboard. So to use localhost to debug redirects, set
 151 `HEROKU_HOST=foo`, `DEBUG_REDIRECT=yes` and run the following
 152 lines in `python`:
 153
 154     from router import add_redirect
 155     add_redirect('localhost:5000', 'http://example.com/')
 156
 157 Technical Stuff
 158 ---------------
 159
 160 * Flask
 161 * Jinja2
 162 * CouchDB
 163 * WTForms
 164 * Bootstrap
 165
 166 Herouter is (surprisingly) designed to be deployed on a free Heroku
 167 instance.