Update-app-to-use-environment-variable-RAILS_DATAROOT.md

+Theses are directions for updating an app that was built prior to the introduction of the awesim_rails gem.
+
+While developing apps, we previously used the default db location `$RAILS_APP_ROOT/db/development.sqlite3` and used `OSC::Machete::Crimson` object to give the crimson files path where we stored user files, which was `$HOME/crimson_files/APP_NAME/`. **This will no longer work.**
+
+See [Rationale for RAILS_DATAROOT](Rationale-for-RAILS_DATAROOT) for an explanation.
+
+#### 1. Add these gems to your Gemfile and use the latest osc-machete gem:
+
+```ruby
+gem 'dotenv-rails', '~> 2.0.0'
+gem 'awesim_rails', '~> 0.6.0'
+gem 'osc-machete', '~> 0.6.2'
+
+gem 'rails_12factor', group: :production
+```
+
+#### 2. Update code to use AwesimRails.dataroot
+
+`awesim_rails` introduces `AwesimRails.dataroot` which replaces `OSC::Machete::Crimson#files_path`. osc-machete v0.5.0 removes OSC::Machete::Crimson. 
+
+1\. Update paperclip initializer `config/initializers/paperclip.rb`
+
+```diff
++++ b/config/initializers/paperclip.rb
+@@ -5,7 +5,7 @@ Paperclip.options[:content_type_mappings] = {
+ }
+ 
+ # We use ":class/:id/:created_at/" to specify path uniqueness
+-Paperclip::Attachment.default_options[:path] = "#{ENV['HOME']}/crimson_files/ContainerFillSim/uploads/:class/:id/:created_at/:attachment/:filename"
++Paperclip::Attachment.default_options[:path] = "#{AwesimRails.dataroot}/uploads/:class/:id/:created_at/:attachment/:filename"
+ 
+ # URL location points to file mount in routes called "/files"
+ # therefore this mirrors ':path' to some extent
+```
+
+2\. Update config/routes.rb - awesim_rails automatically mounts this at '/files':
+
+```diff
+diff --git a/config/routes.rb b/config/routes.rb
+index ad63f0b..0794d6d 100644
+--- a/config/routes.rb
++++ b/config/routes.rb
+@@ -13,9 +13,6 @@ ContainerFillSim::Application.routes.draw do
+ 
+   root 'containers#index'
+ 
+-  #FIXME: add as a separate object that we can mount in osc-machete-rails
+-  mount proc { |env| Rack::Directory.new(OSC::Machete::Crimson.new(Rails.application.class.parent_name).files_path).call(env) } => "/files"
+-
+   # The priority is based upon order of creation: first created -> highest priority.
+   # See how all your routes lay out with "rake routes".
+```
+
+3\. Replace in your code wherever OSC::Machete::Crimson is used with AwesimRails.dataroot. AwesimRails.dataroot is a Pathname object just like Rails.root is, so you can do something like `outdir = AwesimRails.dataroot.join("vnc", "paraview")` which is a line from the updated version of ContainerFillSim
+
+ 
+#### 3. Set RAILS_DATAROOT env var in .env.development code to use AwesimRails.dataroot
+
+AwesimRails.dataroot by default is set to the environment variable RAILS_DATAROOT. Add `.env.development` to the root of your project with this content:
+
+```bash
+export RAILS_DATAROOT=$HOME/crimson_files/ContainerFillSim
+```
+