From 4abbb521c0a23f90a7790db20b281df3f062f4f9 Mon Sep 17 00:00:00 2001 From: Azul Date: Sun, 7 Oct 2012 15:06:16 +0200 Subject: added basic documentation --- CUSTOM.md | 11 +++++++ DEPLOY.md | 30 +++++++++++++++++++ DEVELOP.md | 93 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Development.md | 90 -------------------------------------------------------- INSTALL.md | 34 +++++++++++---------- Readme.md | 22 +++++++++++++- 6 files changed, 174 insertions(+), 106 deletions(-) create mode 100644 CUSTOM.md create mode 100644 DEPLOY.md create mode 100644 DEVELOP.md delete mode 100644 Development.md diff --git a/CUSTOM.md b/CUSTOM.md new file mode 100644 index 0000000..c566c84 --- /dev/null +++ b/CUSTOM.md @@ -0,0 +1,11 @@ +# Customization # + +Leap Web is based on Engines. All things in '''app''' will overwrite the default behaviour. You can either create a new rails app and include the leap_web gem or clone the leap web repository and add your customizations to the '''app''' directory. + +## CSS Customization ## + +We use scss. It's a superset of css3. Add your customizations to '''app/assets/stylesheets'''. + +## Disabling an Engine ## + +If you have no use for one of the engines you can remove it from the Gemfile. Not however that your app might still need to provide some functionality for the other engines to work. For example the users engine provides '''current_user''' and other methods. diff --git a/DEPLOY.md b/DEPLOY.md new file mode 100644 index 0000000..49d9fed --- /dev/null +++ b/DEPLOY.md @@ -0,0 +1,30 @@ +# Deployment # + +These instructions are targeting a Debian GNU/Linux system. You might need to change the commands to match your own needs. + +## Server Preperation ## + +### Dependencies ## + +The following packages need to be installed: + +* git +* ruby1.8 +* rubygems1.8 +* couchdb (if you want to use a local couch) + +### Setup Capistrano ### + +We use capistrano to deploy. +We ship an example deploy.rb in config/deploy.rb.example. Edit it to match your needs. + +run '''cap deploy:setup''' to create the directory structure. + +run '''cap deploy''' to deploy to the server. + +## Customized Files ## + +Please make sure your deploy includes the following files: + +* config/cert +* public/config/provider.json diff --git a/DEVELOP.md b/DEVELOP.md new file mode 100644 index 0000000..6a65285 --- /dev/null +++ b/DEVELOP.md @@ -0,0 +1,93 @@ +# Development # + + +## Engines ## + +Leap Web consists of different Engines. They live in their own subdirectory and are included through bundler via their path. This way changes to the engines immediately affect the server as if they were in the main '''app''' directory. + +Currently Leap Web consists of 4 Engines: + +* [core](https://github.com/leapcode/leap_web/blob/master/core) - ships some dependencies that are used accross all engines. This might be removed at some point. +* [users](https://github.com/leapcode/leap_web/blob/master/users) - user registration and authorization +* [certs](https://github.com/leapcode/leap_web/blob/master/certs) - Cert distribution for the EIP client +* [help](https://github.com/leapcode/leap_web/blob/master/help)- Help ticket management + +## Creating a new engine ## + +### Rails plugin new ### + +Create the basic tree structure for an engine using + +rails plugin new ENGINE_NAME -O --full + + +'''-O''' will skip active record and not add a dev dependency on sqlite. +'''-full''' will create a directory structure with config/routes and app and a basic engine file. + +See http://guides.rubyonrails.org/engines.html for more general info about engines. + +### Require Leap Web Core ### + +You need to add leap_web_core to your .gemspec: + + Gem::Specification.new do |s| + ... + s.add_dependency "rails" ... + s.add_dependency "leap_web_core", "~> 0.0.1" + end + + +You also need to require it before you define your engine in lib/my_engine/engine.rb: + +require "leap_web_core" + +module MyEngine + class Engine < ::Rails::Engine + ... + end +end + + +### Require UI Gems ### + +Leap Web Core provides a basic set of UI gems that should be used accross the engines. These include haml, sass, coffeescript, uglifier, bootstrap-sass, jquery and simple_form. + +Do you want to add views, javascript and the like to your engine? Then you should use the common gems. In order to do so you need to add them to your gemspec: + + + require "my_engine/version" + require "leap_web_core/dependencies" + + ... + + Gem::Specification.new do |s| + ... + s.add_dependency "rails" ... + s.add_dependency "leap_web_core", "~> 0.0.1" + + LeapWebCore::Dependencies.add_ui_gems_to_spec(s) + end + + +You also need to require them before you define your engine in lib/my_engine/engine.rb: + +require "leap_web_core" +LeapWebCore::Dependencies.require_ui_gems + +module MyEngine + class Engine < ::Rails::Engine + ... + end +end + + + +## Creating Models ## + +You can use the normal rails generators to create models. Since you required the leap_web_core gem you will be using CouchRest::Model. So your models inherit from CouchRest::Model::Base. +http://www.couchrest.info/model/definition.html has some good first steps for setting up the model. +CouchRest Model behaved strangely when using a model without a design block. So make sure to define an initial view: http://www.couchrest.info/model/view_objects.html . + +From that point on you should be able to use the standart persistance and querying methods such as create, find, destroy and so on. + + diff --git a/Development.md b/Development.md deleted file mode 100644 index 53942bb..0000000 --- a/Development.md +++ /dev/null @@ -1,90 +0,0 @@ -Leap Web Core -============ - -This gem provides the generic helpers shared across the different engines that make up leap_web. - - -Creating a new engine -=================== - -Rails plugin new ----------------- - -Create the basic tree structure for an engine using - -rails plugin new ENGINE_NAME -O --full - - -'''-O''' will skip active record and not add a dev dependency on sqlite. -'''-full''' will create a directory structure with config/routes and app and a basic engine file. - -See http://guides.rubyonrails.org/engines.html for more general info about engines. - -Require Leap Web Core ---------------------- - -You need to add leap_web_core to your .gemspec: - - Gem::Specification.new do |s| - ... - s.add_dependency "rails" ... - s.add_dependency "leap_web_core", "~> 0.0.1" - end - - -You also need to require it before you define your engine in lib/my_engine/engine.rb: - -require "leap_web_core" - -module MyEngine - class Engine < ::Rails::Engine - ... - end -end - - -Require UI Gems ---------------- - -Leap Web Core provides a basic set of UI gems that should be used accross the engines. These include haml, sass, coffeescript, uglifier, bootstrap-sass, jquery and simple_form. - -Do you want to add views, javascript and the like to your engine? Then you should use the common gems. In order to do so you need to add them to your gemspec: - - - require "my_engine/version" - require "leap_web_core/dependencies" - - ... - - Gem::Specification.new do |s| - ... - s.add_dependency "rails" ... - s.add_dependency "leap_web_core", "~> 0.0.1" - - LeapWebCore::Dependencies.add_ui_gems_to_spec(s) - end - - -You also need to require them before you define your engine in lib/my_engine/engine.rb: - -require "leap_web_core" -LeapWebCore::Dependencies.require_ui_gems - -module MyEngine - class Engine < ::Rails::Engine - ... - end -end - - - -Creating Models -=============== - -You can use the normal rails generators to create models. Since you required the leap_web_core gem you will be using CouchRest::Model. So your models inherit from CouchRest::Model::Base. -http://www.couchrest.info/model/definition.html has some good first steps for setting up the model. -CouchRest Model behaved strangely when using a model without a design block. So make sure to define an initial view: http://www.couchrest.info/model/view_objects.html . - -From that point on you should be able to use the standart persistance and querying methods such as create, find, destroy and so on. - - diff --git a/INSTALL.md b/INSTALL.md index ff7374e..976a9a4 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,31 +1,35 @@ -Installation -------------- +# Installation # +## Requirements ## -### Requirements ### +The webapp only depends on very basic ruby packages and installs the other requirements as gems through bundler. -This file documents installing the webapp demo on a debian system. For other systems you might have to use other commands / packages. +### Packages ### -The webapp only depends on very basic ruby packages and installs the other requirements as gems for now. We use git for version controll and capistrano to deploy. - -#### Packages #### - -The following packages need to be installed: +For now we are using ruby 1.8.7. The following packages need to be installed: * git * ruby1.8 * rubygems1.8 * couchdb -#### Gems #### +### Gems ### + +We install most gems we depend upon through [bundler](http://gembundler.com). However the bundler gem needs to be installed and the '''bundle''' command needs to be available to the user used for deploy. + +### Bundler ### + +Run '''bundle install''' to install all the required gems. + +## Setup ## -We install most gems we depend upon through bundler. However the bundler gem needs to be installed and the '''bundle''' command needs to be available to the user used for deploy. +### Cert Distribution ### -### Setup Capistrano ### +The Webapp can hand out certs for the EIP client. These certs are either picked from a pool in CouchDB or from a file. For now you can either run [Leap CA](http://github.com/leapcode/leap_ca) to fill the pool or you can put your certs file in config/cert. -run capify in the source tree and edit config/deploy.rb to match your needs. We ship an example in config/deploy.rb.example. +We also ship provider information through the webapp. For now please add your eip-service.json to the public/config directory. -run '''cap deploy:setup''' to create the directory structure. +## Running ## -run '''cap deploy''' to deploy to the server. +Run '''rails server''' or whatever rack server you prefer. diff --git a/Readme.md b/Readme.md index 3d81d2e..8b51b4d 100644 --- a/Readme.md +++ b/Readme.md @@ -1,4 +1,24 @@ # Leap Web # -Web application for LEAP. +Web application for LEAP. Currently Leap Web allows Leap providers to manage users, hand out certs for the EIP. + +## Functions ## + +### Supported ### + +* *User Management* - User Registration and Authentication +* *Cert Distribution* - Certs for the Encrypted Internet Proxy + +### Under Development ### + +* *Help Desk* - Managing Help Requests + + +## Documentation ## + +* [INSTALL](https://github.com/leapcode/leap_web/blob/master/INSTALL.md) for installation instructions +* [DEPLOY](https://github.com/leapcode/leap_web/blob/master/DEPLOY.md) for deployment +* [DEVELOP](https://github.com/leapcode/leap_web/blob/master/DEVELOP.md) for developer notes. +* [CUSTOM](https://github.com/leapcode/leap_web/blob/master/CUSTOM.md) to customize. + -- cgit v1.2.3