diff options
Diffstat (limited to 'pages/docs/platform/services/webapp.md')
| -rw-r--r-- | pages/docs/platform/services/webapp.md | 115 |
1 files changed, 115 insertions, 0 deletions
diff --git a/pages/docs/platform/services/webapp.md b/pages/docs/platform/services/webapp.md new file mode 100644 index 0000000..4e0d171 --- /dev/null +++ b/pages/docs/platform/services/webapp.md @@ -0,0 +1,115 @@ +@title = "webapp" +@summary = "leap_web user management application and provider API." + +Introduction +------------------------ + +The service `webapp` will install the web application [[leap_web => https://leap.se/git/leap_web.git]]. It has performs the following functions: + +* REST API for user registration and authentication via the Bitmask client. +* Admin interface to manage users. +* Client certificate distribution and renewal. +* User support help tickets. + +Coming soon: + +* Billing. +* Customizable and localized user documentation. + +The leap_web application is written in Ruby on Rails 3, using CouchDB as the backend data store. + +Topology +------------------------- + +Currently, the platform only supports a single `webapp` node, although we hope to change this in the future. + +`webapp` nodes communicate heavily with `couchdb` nodes. + +Configuration +-------------------------- + +Essential options: + +* `webapp.admin`: An array of username that will be blessed with administrative permissions. These admins can delete users, answer help tickets, and so on. + +For example, `services/webapp.json`: + + { + "webapp": { + "admins": ["joehill", "ali", "mack_the_turtle"] + } + } + +By putting this in `services/webapp.json`, all the `webapp` nodes will inherit the same admin list. + +Customization +--------------------------- + +The provider directory `files/webapp` can be used to customize the appearance of the webapp. All the files in this directory will get sync'ed to the `/srv/leap/webapp/config/customization` directory of the deployed webapp node. + +Files in the `files/webapp` can override view files, locales, and stylesheets in the leap_web app: + +For example: + + stylesheets/ -- override files in Rails.root/app/assets/stylesheets + tail.scss -- included before all others + head.scss -- included after all others + + public/ -- overrides files in Rails.root/public + favicon.ico -- custom favicon + img/ -- customary directory to put images in + + views/ -- overrides files Rails.root/app/views + home/ + index.html.haml -- this file is what shows up on + the home page + pages/ + privacy-policy.en.md -- this file will override + the default privacy policy + terms-of-service.en.md -- this file will override + the default TOS. + + locales/ -- overrides files in Rails.root/config/locales + en.yml -- overrides for English + de.yml -- overrides for German + and so on... + +To play with these customizations, it is easiest to first modify the contents of the directory `/srv/leap/webapp/config/customization` on the `webapp` node. When doing this, you may need to restart leap_web in order for changes to take effect (`touch /srv/leap/webapp/tmp/restart.txt`). + +Sometimes a `rake tmp:clear` and a rails restart is required to pick up a new stylesheet. + +Once you have what you want, then copy these files to the local provider directory `files/webapp` so that they will be installed each time you deploy. + +Custom Fork +---------------------------- + +Sometimes it is easier to maintain your own fork of the leap_web app. You can keep your customizations in that fork instead of in the provider `files/webapp` directory. Or, perhaps you want to add an engine to the application that modifies the app's behavior. + +To deploy your own leap_web, modify the provider file `common.json`: + + { + "sources": { + "webapp": { + "revision": "origin/develop", + "source": "https://github.com/leapcode/leap_web", + "type": "git" + } + } + } + +To target only particular environment, modify instead `common.ENV.json`, where ENV is the name of the environment. + +See https://github.com/leapcode/leap_web/blob/develop/doc/DEVELOP.md for notes on getting started hacking on leap_web. + +Known problems +--------------------------- + +* Client certificates are generated without a CSR. The problem is that this makes the web + application extremely vulnerable to denial of service attacks. This was not an issue until we + started to allow the possibility of anonymously fetching a client certificate without + authenticating first. + +* By its very nature, the user database is vulnerable to enumeration attacks. These are + very hard to prevent, because our protocol is designed to allow query of a user database via + proxy in order to provide network perspective. + |