Skip to content

Commit

Permalink
update README
Browse files Browse the repository at this point in the history
  • Loading branch information
@DanielKehoe
DanielKehoe committed Jan 22, 2013
1 parent a5d894e commit 3344ff8
Showing 1 changed file with 136 additions and 58 deletions.
194 changes: 136 additions & 58 deletions README.textile
View file
Expand Up @@ -76,14 +76,86 @@ If you want to use the project as a starter app, use the "Rails Composer":http:/
To build the example application, run the command:

<pre>
$ rails new myapp -m https://raw.github.com/RailsApps/rails-composer/master/composer.rb -T -O
$ rails new rails3-subdomains -m https://raw.github.com/RailsApps/rails-composer/master/composer.rb -T -O
</pre>

Use the @-T -O@ flags to skip Test::Unit files and Active Record files.

The @$@ character indicates a shell prompt; don't include it when you run the command.

This creates a new Rails app (with the name "myapp") on your computer.
This creates a new Rails app named @rails3-subdomains@ on your computer.

You'll see a prompt:

<pre>
question Install an example application?
1) I want to build my own application
2) membership/subscription/saas
3) rails-prelaunch-signup
4) rails3-bootstrap-devise-cancan
5) rails3-devise-rspec-cucumber
6) rails3-mongoid-devise
7) rails3-mongoid-omniauth
8) rails3-subdomains
</pre>

Choose *rails3-subdomains*. The Rails Composer tool may give you other options (other choices may have been added since these notes were written).

The application generator template will ask you for additional preferences:

<pre>
question Web server for development?
1) WEBrick (default)
2) Thin
3) Unicorn
4) Puma
question Web server for production?
1) Same as development
2) Thin
3) Unicorn
4) Puma
question Template engine?
1) ERB
2) Haml
3) Slim
extras Set a robots.txt file to ban spiders? (y/n)
extras Create a project-specific rvm gemset and .rvmrc? (y/n)
extras Create a GitHub repository? (y/n)
</pre>

h4. Web Servers

Use the default WEBrick server for convenience. If you plan to deploy to Heroku, select "thin" as your production webserver.

h4. Template Engine

The example application uses the default "ERB" Rails template engine. Optionally, you can use another template engine, such as Haml or Slim. See instructions for "Haml and Rails":http://railsapps.github.com/rails-haml.html.

h4. Other Choices

Set a robots.txt file to ban spiders if you want to keep your new site out of Google search results.

It is a good idea to use "rvm":https://rvm.io/, the Ruby Version Manager, and create a project-specific rvm gemset and .rvmrc file (not available on Windows). See "Installing Rails":http://railsapps.github.com/installing-rails.html.

If you choose to create a GitHub repository, the generator will prompt you for a GitHub username and password.

h4. Troubleshooting

If you get an error "OpenSSL certificate verify failed" or "Gem::RemoteFetcher::FetchError: SSL_connect" see the article "OpenSSL errors and Rails":http://railsapps.github.com/openssl-certificate-verify-failed.html.

If you get an error like this:

<pre>
Your bundle is complete! Use `bundle show [gemname]` to see where a bundled gem is installed.
composer Running 'after bundler' callbacks.
The template [...] could not be loaded.
Error: You have already activated ..., but your Gemfile requires ....
Using bundle exec may solve this.
</pre>

It's due to conflicting gem versions. See the article "Rails Error: “You have already activated (…)”":http://railsapps.github.com/rails-error-you-have-already-activated.html.

Other problems? Check the "issues":https://github.com/RailsApps/rails3-subdomains/issues.

h3. Edit the README

Expand Down Expand Up @@ -123,82 +195,67 @@ If you want to see what's in your MongoDB databases, I recommend using the "Mong

h3. Configure Email

You must configure the app for your email account if you want your application to send email messages.

h4. Use a Gmail account
This example application doesn't send email messages. However, if you want your application to send email messages (for example, if you plan to install the Devise @:confirmable@ module) you must configure the application for your email account. See the article "Send Email with Rails":http://railsapps.github.com/rails-send-email.html.

You'll need to modify two files to include your Gmail username and password:
h3. Configure Devise

* *config/environments/development.rb*
* *config/environments/production.rb*
You can modify the configuration file for Devise if you want to use something other than the defaults:

<pre>
config.action_mailer.smtp_settings = {
address: "smtp.gmail.com",
port: 587,
domain: "example.com",
authentication: "plain",
enable_starttls_auto: true,
user_name: ENV["GMAIL_USERNAME"],
password: ENV["GMAIL_PASSWORD"]
}
</pre>
* *config/initializers/devise.rb*

You can replace @ENV["GMAIL_USERNAME"]@ and @ENV["GMAIL_PASSWORD"]@ with your Gmail username and password. However, committing the file to a public GitHub repository will expose your secret password.
h3. Configuration File

If you're familiar with setting "Unix environment variables":http://en.wikipedia.org/wiki/Environment_variable, it's advisable to leave @config.action_mailer.smtp_settings@ unchanged and set your environment variables in the file that is read when starting an interactive shell (the *~/.bashrc* file for the bash shell). This will keep the password out of your repository.
The application uses the "figaro gem":https://github.com/laserlemon/figaro to set environment variables. Credentials for your administrator account and email account are set in the *config/application.yml* file. The *.gitignore* file prevents the *config/application.yml* file from being saved in the git repository so your credentials are kept private. See the article "Rails Environment Variables":http://railsapps.github.com/rails-environment-variables.html for more information.

Are you using a bash shell? Use @echo $SHELL@ to find out. For a bash shell, edit the *~/.bashrc* file and add:
Modify the file *config/application.yml*:

<pre>
export GMAIL_USERNAME="myname@gmail.com"
export GMAIL_PASSWORD="secret*"
# Add account credentials and API keys here.
# See http://railsapps.github.com/rails-environment-variables.html
# This file should be listed in .gitignore to keep your settings secret!
# Each entry sets a local environment variable and overrides ENV variables in the Unix shell.
# For example, setting:
# GMAIL_USERNAME: Your_Gmail_Username
# makes 'Your_Gmail_Username' available as ENV["GMAIL_USERNAME"]
# Add application configuration variables here, as shown below.
#
GMAIL_USERNAME: Your_Username
GMAIL_PASSWORD: Your_Password
ADMIN_NAME: user1
ADMIN_EMAIL: user@example.com
ADMIN_PASSWORD: changeme
</pre>

Open a new shell or restart your terminal application to continue.

h4. Configure ActionMailer
If you are planning to customize the application to send email using a Gmail account, you can add the user name and password needed for the application to send email. See the article "Send Email with Rails":http://railsapps.github.com/rails-send-email.html.

The example application is set to deliver email in production only. It will raise delivery errors in development but not production.
If you wish, set your name, email address, and password for the first user's account. If you prefer, you can use the default to sign in to the application and edit the account after deployment. It is always a good idea to change the password after the application is deployed.

In development, @config.action_mailer.default_url_options@ is set for a host at @localhost:3000@ which will enable links in Devise confirmation email messages to work properly. You'll need to change the @config.action_mailer.default_url_options@ host option from @example.com@ to your own domain for the production environment.
All configuration values in the *config/application.yml* file are available anywhere in the application as environment variables. For example, @ENV["GMAIL_USERNAME"]@ will return the string "Your_Username".

You can change these values as needed in these two files:
If you prefer, you can delete the *config/application.yml* file and set each value as an environment variable in the Unix shell.

* *config/environments/development.rb*
* *config/environments/production.rb*
h3. Set Up a Database Seed File

h4. Configure Devise for Email

Complete your email configuration by modifying

* *config/initializers/devise.rb*
The *db/seeds.rb* file initializes the database with default values. To keep some data private, and consolidate configuration settings in a single location, we use the *config/application.yml* file to set environment variables and then use the environment variables in the *db/seeds.rb* file.

and setting the @config.mailer_sender@ option for the return email address for messages that Devise sends from the application.

h2. Configure Devise

You can modify the configuration file for Devise if you want to use something other than the defaults:

*config/initializers/devise.rb*
<pre>
puts 'DEFAULT USERS'
user = User.create! :name => ENV['ADMIN_NAME'].dup, :email => ENV['ADMIN_EMAIL'].dup, :password => ENV['ADMIN_PASSWORD'].dup, :password_confirmation => ENV['ADMIN_PASSWORD'].dup
puts 'user: ' << user.name
</pre>

h2. Create a Default User
You can change the first user's name, email, and password in this file but it is better to make the changes in the *config/application.yml* file to keep the credentials private. If you decide to include your private password in the *db/seeds.rb* file, be sure to add the filename to your *.gitignore* file so that your password doesn't become available in your public GitHub repository.

h4. Set Up a Database Seed File
Note that it's not necessary to personalize the *db/seeds.rb* file before you deploy your app. You can deploy the app with an example user and then use the application's "Edit Account" feature to change name, email address, and password after you log in. Use this feature to log in as the first user and change the user name and password to your own.

You'll want to set up a default user so you can easily log in to test the app. You can modify the file *db/seeds.rb* for your own name, email and password:
You may wish to include additional sample users:

<pre>
puts 'EMPTY THE MONGODB DATABASE'
Mongoid.master.collections.reject { |c| c.name =~ /^system/}.each(&:drop)
puts 'SETTING UP DEFAULT USER LOGIN'
user = User.create! :name => 'user1', :email => 'user@example.com', :password => 'please', :password_confirmation => 'please'
puts 'New user created: ' << user.name
user2 = User.create! :name => 'user2', :email => 'user2@example.com', :password => 'please', :password_confirmation => 'please'
puts 'New user created: ' << user2.name
user2 = User.create! :name => 'user2', :email => 'user2@example.com', :password => 'changeme', :password_confirmation => 'changeme'
puts 'user: ' << user2.name
</pre>

Use the defaults or change the values for name, email, and password as you wish.
This will add a second user to the database.

h3. Set the Database

Expand All @@ -208,6 +265,8 @@ Prepare the database and add the default user to the database by running the com
$ rake db:seed
</pre>

Use @rake db:reseed@ if you want to empty and reseed the database. Or you can use @rake db:drop@ and @rake db:setup@. The equivalent task for Rails with ActiveRecord is @rake db:reset@ which will be available in Mongoid 4.0.

Set the database for running tests:

<pre>
Expand All @@ -216,6 +275,25 @@ $ rake db:test:prepare

If you’re not using "rvm":https://rvm.io/, the Ruby Version Manager, you should preface each rake command with @bundle exec@. You don’t need to use @bundle exec@ if you are using rvm version 1.11.0 or newer.

h3. Change your Application's Secret Token

If you've used the Rails Composer tool to generate the application, the application's secret token will be unique, just as with any Rails application generated with the @rails new@ command.

However, if you've cloned the application directly from GitHub, it is crucial that you change the application's secret token before deploying your application in production mode. Otherwise, people could change their session information, and potentially access your site without your permission. Your secret token should be at least 30 characters long and completely random.

Get a unique secret token:

<pre>
rake secret
</pre>

Edit your *config/initializers/secret_token.rb* file to add the secret token:

<pre>
Rails3BootstrapDeviseCancan::Application.config.secret_token = '...some really long, random string...'
</pre>


h2. Test the Application With Subdomains

If you launch the application, it will be running at "http://localhost:3000/":http://localhost:3000/ or "http://0.0.0.0:3000/":http://0.0.0.0:3000/. However, unless you've made some configuration changes to your computer, you won't be able to resolve an address that uses a subdomain, such as "http://foo.localhost:3000/":http://foo.localhost:3000/. There are several complex solutions to this problem. You could set up your own domain name server on your localhost and create an A entry to catch all subdomains. You could modify your */etc/hosts* file (but it won't accommodate dynamically created subdomains). You can create a "proxy auto-config (PAC)":http://en.wikipedia.org/wiki/Proxy_auto-config file and set it up as the proxy in your web browser preferences.There's a far simpler solution that does not require reconfiguring your computer or web browser preferences. The developer Levi Cook registered a domain, "lvh.me":http://lvh.me:3000/ (short for: local virtual host me), that resolves to the localhost IP address 127.0.0.1 and supports wildcards (accommodating dynamically created subdomains).
Expand Down Expand Up @@ -251,9 +329,9 @@ The application is set up for RSpec unit tests and Cucumber scenarios and steps.

After installing the application, run @rake -T@ to check that rake tasks for RSpec and Cucumber are available.

Run @rake spec@ to run all RSpec tests.
Run @rake spec@ to run RSpec tests.

Run @rake cucumber@ (or more simply, @cucumber@) to run all Cucumber scenarios and steps.
Run @rake cucumber@ (or more simply, @cucumber@) to run Cucumber scenarios and steps.

h2. Troubleshooting

Expand Down Expand Up @@ -293,7 +371,7 @@ h2. Credits

Thank you to "Brian Cardarella":http://bcardarella.com/ for a helpful blog post on "Custom Subdomains in Rails 3":http://bcardarella.com/post/716951242/custom-subdomains-in-rails-3.

Daniel Kehoe ("http://danielkehoe.com/":http://danielkehoe.com/) implemented the application and wrote the tutorial.
Daniel Kehoe implemented the application and wrote the tutorial.

Is the app useful to you? Follow the project on Twitter: "@rails_apps":http://twitter.com/rails_apps
and tweet some praise. I'd love to know you were helped out by what I've put together.
Expand Down

0 comments on commit 3344ff8

Please sign in to comment.