From e99856e5338424b36884e21db1f1399f4753ab3a Mon Sep 17 00:00:00 2001 From: elijah Date: Wed, 29 Apr 2015 13:51:11 -0700 Subject: clean up docs --- CUSTOM.md | 14 ------ Capfile | 5 --- DEPLOY.md | 72 ------------------------------- DEVELOP.md | 91 --------------------------------------- INSTALL.md | 78 --------------------------------- TROUBLESHOOT.md | 46 -------------------- config/deploy.rb.example | 37 ---------------- doc/CUSTOM.md | 14 ++++++ doc/DEPLOY.md | 72 +++++++++++++++++++++++++++++++ doc/DEVELOP.md | 91 +++++++++++++++++++++++++++++++++++++++ doc/KNOWN_PROBLEMS.md | 4 ++ doc/README_FOR_APP | 2 - doc/TROUBLESHOOT.md | 46 ++++++++++++++++++++ doc/examples/capistrano/Capfile | 5 +++ doc/examples/capistrano/deploy.rb | 37 ++++++++++++++++ 15 files changed, 269 insertions(+), 345 deletions(-) delete mode 100644 CUSTOM.md delete mode 100644 Capfile delete mode 100644 DEPLOY.md delete mode 100644 DEVELOP.md delete mode 100644 INSTALL.md delete mode 100644 TROUBLESHOOT.md delete mode 100644 config/deploy.rb.example create mode 100644 doc/CUSTOM.md create mode 100644 doc/DEPLOY.md create mode 100644 doc/DEVELOP.md create mode 100644 doc/KNOWN_PROBLEMS.md delete mode 100644 doc/README_FOR_APP create mode 100644 doc/TROUBLESHOOT.md create mode 100644 doc/examples/capistrano/Capfile create mode 100644 doc/examples/capistrano/deploy.rb diff --git a/CUSTOM.md b/CUSTOM.md deleted file mode 100644 index 53e4d88..0000000 --- a/CUSTOM.md +++ /dev/null @@ -1,14 +0,0 @@ -Customization -============================== - -Customization directory ---------------------------------------- - -See config/customization/README.md - -Engines ---------------------- - -Leap Web includes some Engines. All things in `app` will overwrite the engine behaviour. You can clone the leap web repository and add your customizations to the `app` directory. Including leap_web as a gem is currently not supported. It should not require too much work though and we would be happy to include the changes required. - -If you have no use for one of the engines you can remove it from the Gemfile. Engines should really be plugins - no other engines should depend upon them. If you need functionality in different engines it should probably go into the toplevel. The 'users' engine will soon become part of the main webapp for that reason. diff --git a/Capfile b/Capfile deleted file mode 100644 index f65237f..0000000 --- a/Capfile +++ /dev/null @@ -1,5 +0,0 @@ -load 'deploy' -# Uncomment if you are using Rails' asset pipeline -load 'deploy/assets' -Dir['vendor/gems/*/recipes/*.rb','vendor/plugins/*/recipes/*.rb'].each { |plugin| load(plugin) } -load 'config/deploy' # remove this line to skip loading any of the default tasks diff --git a/DEPLOY.md b/DEPLOY.md deleted file mode 100644 index 33d5598..0000000 --- a/DEPLOY.md +++ /dev/null @@ -1,72 +0,0 @@ -# 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.9 -* rubygems1.9 -* couchdb (if you want to use a local couch) - -### Setup Capistrano ### - -We use puppet to deploy. But we also ship an example deploy.rb in -config/deploy.rb.example. Edit it to match your needs if you want to use -capistrano. - -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: - -* `public/config/provider.json` -- provider bootstrap file. -* `config/couchdb.yml` -- normal webapp couchdb configuration. -* `config/couchdb.admin.yml` -- configuration used for rake tasks. - -## Couch Security ## - -We recommend against using an admin user for running the webapp. To avoid this -couch design documents need to be created ahead of time and the auto update -mechanism needs to be disabled. Take a look at `test/travis/setup_couch.sh` -for an example of securing the couch. - -### DESIGN DOCUMENTS ### - -After securing the couch design documents need to be deployed with admin -permissions. There are two ways of doing this: - * rake couchrest:migrate_with_proxies - * dump the documents as files with `rake couchrest:dump` and deploy them - to the couch by hand or with puppet. - -#### CouchRest::Migrate #### - -The before_script block in .travis.yml illustrates how to do this: - -```bash -mv test/config/couchdb.yml config/couchdb.yml -mv test/config/couchdb.admin.yml config/couchdb.admin.yml -bundle exec rake db:rotate # create dbs -bundle exec rake couchrest:migrate # run migrations -``` - -#### Deploy design docs from CouchRest::Dump #### - -First of all we get the design docs as files: - -```bash -# put design docs in /tmp/design -bundle exec rake couchrest:dump -``` - -Then we add them to files/design in the site_couchdb module in leap_platform -so they get deployed with the couch. You could also upload them using curl or -sth. similar. diff --git a/DEVELOP.md b/DEVELOP.md deleted file mode 100644 index 991218e..0000000 --- a/DEVELOP.md +++ /dev/null @@ -1,91 +0,0 @@ -# Development # - -## Continuous Integration ## - -See https://travis-ci.org/leapcode/leap_web for CI reports. - -## Views ## - -Some tips on modifying the views: - -* Many of the forms use [simple_form gem](https://github.com/plataformatec/simple_form) -* We still use client_side_validations for the validation code but since it is not maintained anymore we want to drop it asap. - -## Engines ## - -Leap Web contains some. 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 includes 2 Engines: - -* [support](https://github.com/leapcode/leap_web/blob/master/engines/support) - Help ticket management -* [billing](https://github.com/leapcode/leap_web/blob/master/engines/billing) - Billing System - -## Creating a new engine ## - -If you want to add functionality to the webapp but keep it easy to remove you might consider adding an engine. This only makes sense if your engine really is a plugin - so no other pieces of code depend on it. - -### 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. - -You need to require engine specific gems in lib/my_engine/engine.rb: - -```ruby -require "my_dependency" - -module MyEngine - class Engine < ::Rails::Engine - # ... - end -end -``` - -## Creating Models ## - -You can use the normal rails generators to create models. You probably want to require 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. - -## Writing Tests ## - -### Locale - -The ApplicationController defines a before filter #set_locale that will set -the default_url_options to include the appropriate default {:locale => x} param. - -However, paths generated in tests don't use default_url_options. This can -create failures for certain nested routes unless you explicitly provide -:locale => nil to the path helper. This is not needed for actual path code in -the controllers or views, only when generating paths in tests. - -For example: - - test "robot" do - login_as @user - visit robot_path(@robot, :locale => nil) - end - -## Debugging - -Sometimes bugs only show up when deployed to the live production server. Debugging can be tricky, -because the open source mod_passenger does not support debugger. You can't just run -`rails server` because HSTS records for your site will make most browsers require TLS. - -One solution is to temporarily modify the apache config to proxypass the TLS requests to rails: - - - ProxyPass / http://127.0.0.1:3000/ - ProxyPassReverse / http://127.0.0.1:3000/ - ProxyPreserveHost on - .... - \ No newline at end of file diff --git a/INSTALL.md b/INSTALL.md deleted file mode 100644 index 75cb2a6..0000000 --- a/INSTALL.md +++ /dev/null @@ -1,78 +0,0 @@ -# Installation # - -Please see TROUBLESHOOT.md if you run into any issues during install. - -## TL;DR ## - -Install git, ruby 1.9, rubygems and couchdb on your system. Then run - -``` -gem install bundler -git clone https://leap.se/git/leap_web -cd leap_web -git submodule init -git submodule update -bundle install --binstubs -bin/rails server -``` - -You will find Leap Web running on `localhost:3000`. Check out the Cert Distribution section below for setting up the cert and server config. - -## Requirements ## - -The webapp only depends on very basic ruby packages and installs the other requirements as gems through bundler. - -### Packages ### - -The following packages need to be installed: - -* git -* ruby1.9.3 -* rubygems -* couchdb - -### Code ### - -Simply clone the git repository: - -``` - git clone https://leap.se/git/leap_web - cd leap_web -``` - -### Gems ### - -We install most gems we depend upon through [bundler](http://gembundler.com). First install bundler - -``` - gem install bundler -``` - -Then install all the required gems: -``` - bundle install --binstubs -``` - -## Setup ## - -### SRP submodule ### - -We currently use a git submodule to include srp-js. This will soon be replaced by a ruby gem. but for now you need to run - -``` - git submodule init - git submodule update -``` - -### Provider Information ### - -The leap client fetches provider information via json files from the server. -If you want to use that functionality please add your provider files the public/config directory. - -## Running ## - -``` -bin/rails server -``` - -You'll find Leap Web running on `localhost:3000` diff --git a/TROUBLESHOOT.md b/TROUBLESHOOT.md deleted file mode 100644 index f3db006..0000000 --- a/TROUBLESHOOT.md +++ /dev/null @@ -1,46 +0,0 @@ -# Troubleshooting # - -Here are some less common issues you might run into when installing Leap Web. - -## Cannot find Bundler ## - -### Error Messages ### - -`bundle: command not found` - -### Solution ### - -Make sure bundler is installed. `gem list bundler` should list `bundler`. -You also need to be able to access the `bundler` executable in your PATH. - -## Outdated version of rubygems ## - -### Error Messages ### - -`bundler requires rubygems >= 1.3.6` - -### Solution ### - -`gem update --system` will install the latest rubygems - -## Missing development tools ## - -Some required gems will compile C extensions. They need a bunch of utils for this. - -### Error Messages ### - -`make: Command not found` - -### Solution ### - -Install the required tools. For linux the `build-essential` package provides most of them. For Mac OS you probably want the XCode Commandline tools. - -## Missing libraries and headers ## - -Some gem dependencies might not compile because they lack the needed c libraries. - -### Solution ### - -Install the libraries in question including their development files. - - diff --git a/config/deploy.rb.example b/config/deploy.rb.example deleted file mode 100644 index 1fd4b8c..0000000 --- a/config/deploy.rb.example +++ /dev/null @@ -1,37 +0,0 @@ -require "bundler/capistrano" - -set :application, "webapp" - -set :scm, :git -set :repository, "https://leap.se/git/leap_web" -set :branch, "master" - -set :deploy_via, :remote_cache -set :deploy_to, '/home/webapp' -set :use_sudo, false - -set :normalize_asset_timestamps, false - -set :user, "webapp" - -role :web, "YOUR SERVER" # Your HTTP server, Apache/etc -role :app, "YOUR SERVER" # This may be the same as your `Web` server - -# We're not using this for now... -# role :db, "your primary db-server here", :primary => true # This is where Rails migrations will run -# role :db, "your slave db-server here" - -# if you want to clean up old releases on each deploy uncomment this: -# after "deploy:restart", "deploy:cleanup" - -# if you're still using the script/reaper helper you will need -# these http://github.com/rails/irs_process_scripts - -# If you are using Passenger mod_rails uncomment this: -# namespace :deploy do -# task :start do ; end -# task :stop do ; end -# task :restart, :roles => :app, :except => { :no_release => true } do -# run "#{try_sudo} touch #{File.join(current_path,'tmp','restart.txt')}" -# end -# end diff --git a/doc/CUSTOM.md b/doc/CUSTOM.md new file mode 100644 index 0000000..53e4d88 --- /dev/null +++ b/doc/CUSTOM.md @@ -0,0 +1,14 @@ +Customization +============================== + +Customization directory +--------------------------------------- + +See config/customization/README.md + +Engines +--------------------- + +Leap Web includes some Engines. All things in `app` will overwrite the engine behaviour. You can clone the leap web repository and add your customizations to the `app` directory. Including leap_web as a gem is currently not supported. It should not require too much work though and we would be happy to include the changes required. + +If you have no use for one of the engines you can remove it from the Gemfile. Engines should really be plugins - no other engines should depend upon them. If you need functionality in different engines it should probably go into the toplevel. The 'users' engine will soon become part of the main webapp for that reason. diff --git a/doc/DEPLOY.md b/doc/DEPLOY.md new file mode 100644 index 0000000..33d5598 --- /dev/null +++ b/doc/DEPLOY.md @@ -0,0 +1,72 @@ +# 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.9 +* rubygems1.9 +* couchdb (if you want to use a local couch) + +### Setup Capistrano ### + +We use puppet to deploy. But we also ship an example deploy.rb in +config/deploy.rb.example. Edit it to match your needs if you want to use +capistrano. + +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: + +* `public/config/provider.json` -- provider bootstrap file. +* `config/couchdb.yml` -- normal webapp couchdb configuration. +* `config/couchdb.admin.yml` -- configuration used for rake tasks. + +## Couch Security ## + +We recommend against using an admin user for running the webapp. To avoid this +couch design documents need to be created ahead of time and the auto update +mechanism needs to be disabled. Take a look at `test/travis/setup_couch.sh` +for an example of securing the couch. + +### DESIGN DOCUMENTS ### + +After securing the couch design documents need to be deployed with admin +permissions. There are two ways of doing this: + * rake couchrest:migrate_with_proxies + * dump the documents as files with `rake couchrest:dump` and deploy them + to the couch by hand or with puppet. + +#### CouchRest::Migrate #### + +The before_script block in .travis.yml illustrates how to do this: + +```bash +mv test/config/couchdb.yml config/couchdb.yml +mv test/config/couchdb.admin.yml config/couchdb.admin.yml +bundle exec rake db:rotate # create dbs +bundle exec rake couchrest:migrate # run migrations +``` + +#### Deploy design docs from CouchRest::Dump #### + +First of all we get the design docs as files: + +```bash +# put design docs in /tmp/design +bundle exec rake couchrest:dump +``` + +Then we add them to files/design in the site_couchdb module in leap_platform +so they get deployed with the couch. You could also upload them using curl or +sth. similar. diff --git a/doc/DEVELOP.md b/doc/DEVELOP.md new file mode 100644 index 0000000..991218e --- /dev/null +++ b/doc/DEVELOP.md @@ -0,0 +1,91 @@ +# Development # + +## Continuous Integration ## + +See https://travis-ci.org/leapcode/leap_web for CI reports. + +## Views ## + +Some tips on modifying the views: + +* Many of the forms use [simple_form gem](https://github.com/plataformatec/simple_form) +* We still use client_side_validations for the validation code but since it is not maintained anymore we want to drop it asap. + +## Engines ## + +Leap Web contains some. 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 includes 2 Engines: + +* [support](https://github.com/leapcode/leap_web/blob/master/engines/support) - Help ticket management +* [billing](https://github.com/leapcode/leap_web/blob/master/engines/billing) - Billing System + +## Creating a new engine ## + +If you want to add functionality to the webapp but keep it easy to remove you might consider adding an engine. This only makes sense if your engine really is a plugin - so no other pieces of code depend on it. + +### 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. + +You need to require engine specific gems in lib/my_engine/engine.rb: + +```ruby +require "my_dependency" + +module MyEngine + class Engine < ::Rails::Engine + # ... + end +end +``` + +## Creating Models ## + +You can use the normal rails generators to create models. You probably want to require 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. + +## Writing Tests ## + +### Locale + +The ApplicationController defines a before filter #set_locale that will set +the default_url_options to include the appropriate default {:locale => x} param. + +However, paths generated in tests don't use default_url_options. This can +create failures for certain nested routes unless you explicitly provide +:locale => nil to the path helper. This is not needed for actual path code in +the controllers or views, only when generating paths in tests. + +For example: + + test "robot" do + login_as @user + visit robot_path(@robot, :locale => nil) + end + +## Debugging + +Sometimes bugs only show up when deployed to the live production server. Debugging can be tricky, +because the open source mod_passenger does not support debugger. You can't just run +`rails server` because HSTS records for your site will make most browsers require TLS. + +One solution is to temporarily modify the apache config to proxypass the TLS requests to rails: + + + ProxyPass / http://127.0.0.1:3000/ + ProxyPassReverse / http://127.0.0.1:3000/ + ProxyPreserveHost on + .... + \ No newline at end of file diff --git a/doc/KNOWN_PROBLEMS.md b/doc/KNOWN_PROBLEMS.md new file mode 100644 index 0000000..d35c743 --- /dev/null +++ b/doc/KNOWN_PROBLEMS.md @@ -0,0 +1,4 @@ +PROBLEMS + +rake couchrest:migrate on empty db fails + diff --git a/doc/README_FOR_APP b/doc/README_FOR_APP deleted file mode 100644 index fe41f5c..0000000 --- a/doc/README_FOR_APP +++ /dev/null @@ -1,2 +0,0 @@ -Use this README file to introduce your application and point to useful places in the API for learning more. -Run "rake doc:app" to generate API documentation for your models, controllers, helpers, and libraries. diff --git a/doc/TROUBLESHOOT.md b/doc/TROUBLESHOOT.md new file mode 100644 index 0000000..f3db006 --- /dev/null +++ b/doc/TROUBLESHOOT.md @@ -0,0 +1,46 @@ +# Troubleshooting # + +Here are some less common issues you might run into when installing Leap Web. + +## Cannot find Bundler ## + +### Error Messages ### + +`bundle: command not found` + +### Solution ### + +Make sure bundler is installed. `gem list bundler` should list `bundler`. +You also need to be able to access the `bundler` executable in your PATH. + +## Outdated version of rubygems ## + +### Error Messages ### + +`bundler requires rubygems >= 1.3.6` + +### Solution ### + +`gem update --system` will install the latest rubygems + +## Missing development tools ## + +Some required gems will compile C extensions. They need a bunch of utils for this. + +### Error Messages ### + +`make: Command not found` + +### Solution ### + +Install the required tools. For linux the `build-essential` package provides most of them. For Mac OS you probably want the XCode Commandline tools. + +## Missing libraries and headers ## + +Some gem dependencies might not compile because they lack the needed c libraries. + +### Solution ### + +Install the libraries in question including their development files. + + diff --git a/doc/examples/capistrano/Capfile b/doc/examples/capistrano/Capfile new file mode 100644 index 0000000..f65237f --- /dev/null +++ b/doc/examples/capistrano/Capfile @@ -0,0 +1,5 @@ +load 'deploy' +# Uncomment if you are using Rails' asset pipeline +load 'deploy/assets' +Dir['vendor/gems/*/recipes/*.rb','vendor/plugins/*/recipes/*.rb'].each { |plugin| load(plugin) } +load 'config/deploy' # remove this line to skip loading any of the default tasks diff --git a/doc/examples/capistrano/deploy.rb b/doc/examples/capistrano/deploy.rb new file mode 100644 index 0000000..1fd4b8c --- /dev/null +++ b/doc/examples/capistrano/deploy.rb @@ -0,0 +1,37 @@ +require "bundler/capistrano" + +set :application, "webapp" + +set :scm, :git +set :repository, "https://leap.se/git/leap_web" +set :branch, "master" + +set :deploy_via, :remote_cache +set :deploy_to, '/home/webapp' +set :use_sudo, false + +set :normalize_asset_timestamps, false + +set :user, "webapp" + +role :web, "YOUR SERVER" # Your HTTP server, Apache/etc +role :app, "YOUR SERVER" # This may be the same as your `Web` server + +# We're not using this for now... +# role :db, "your primary db-server here", :primary => true # This is where Rails migrations will run +# role :db, "your slave db-server here" + +# if you want to clean up old releases on each deploy uncomment this: +# after "deploy:restart", "deploy:cleanup" + +# if you're still using the script/reaper helper you will need +# these http://github.com/rails/irs_process_scripts + +# If you are using Passenger mod_rails uncomment this: +# namespace :deploy do +# task :start do ; end +# task :stop do ; end +# task :restart, :roles => :app, :except => { :no_release => true } do +# run "#{try_sudo} touch #{File.join(current_path,'tmp','restart.txt')}" +# end +# end -- cgit v1.2.3