clean up docs

8 files changed, 269 insertions, 2 deletions

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:
+
+    <virtualhost *:443>
+      ProxyPass / http://127.0.0.1:3000/
+      ProxyPassReverse / http://127.0.0.1:3000/
+      ProxyPreserveHost on
+      ....
+    </virtualhost>
\ 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