justsans/cdp

Thoughtworks cdp project for creating a tool for agile review process

What Is Implemented — and What Is Not

The current application has the following capabilities.

• Collect Feedbacks

Dependencies

Before generating your application, you will need:

• The Ruby language – version 2.1
• The Rails gem – version 4.1

See the article Installing Rails for instructions about setting up Rails and your development environment.

Getting the Application

Fork

If you’d like to add features (or bug fixes) to improve the example application, you can fork the GitHub repo and make pull requests. Your code contributions are welcome!

Clone

If you want to copy and customize the app with changes that are only useful for your own project, you can clone the GitHub repo. You’ll need to search-and-replace the project name throughout the application. You probably should generate the app instead (see below). To clone:

$ git clone https://github.com/justsans/cdp.git

Troubleshooting

Getting Started

See the article Installing Rails to make sure your development environment is prepared properly.

Use RVM

I recommend using rvm, the Ruby Version Manager, to create a project-specific gemset for the application. If you generate the application with the Rails Composer tool, you can create a project-specific gemset.

Gems

Here are the gems used by the application:

Install the Required Gems

$ bundle install

You can check which gems are installed on your computer with:

$ gem list

Keep in mind that you have installed these gems locally. When you deploy the app to another server, the same gems (and versions) must be available.

Configuration File

To consolidate configuration settings in a single location, we store credentials in the config/secrets.yml file. To keep your credentials private, use Unix environment variables to set your credentials. See the article Rails Environment Variables for more information.

Add your credentials to the file config/secrets.yml:

# Make sure the secrets in this file are kept private
# if you're sharing your code publicly.

development:
  admin_name: First User
  admin_email: [email protected]
  admin_password: changeme
  email_provider_username: <%= ENV["GMAIL_USERNAME"] %>
  email_provider_password: <%= ENV["GMAIL_PASSWORD"] %>
  domain_name: example.com
  secret_key_base: very_long_random_string

test:
  secret_key_base: very_long_random_string
  domain_name: example.com

# Do not keep production secrets in the repository,
# instead read values from the environment.
production:
  admin_name: <%= ENV["ADMIN_NAME"] %>
  admin_email: <%= ENV["ADMIN_EMAIL"] %>
  admin_password: <%= ENV["ADMIN_PASSWORD"] %>
  email_provider_username: <%= ENV["GMAIL_USERNAME"] %>
  email_provider_password: <%= ENV["GMAIL_PASSWORD"] %>
  domain_name: <%= ENV["DOMAIN_NAME"] %>
  secret_key_base: <%= ENV["SECRET_KEY_BASE"] %>

All configuration values in the config/secrets.yml file are available anywhere in the application as variables. For example, Rails.application.secrets.email_provider_username will return the string set in the Unix environment variable GMAIL_USERNAME.

For the Gmail username and password, enter the credentials you use to log in to Gmail when you check your inbox. See the article Send Email with Rails if you are using Google two factor authentication.

The values for admin_email and admin_password are used when the database is seeded. You will be able to log in to the application with these credentials. Note that it’s not necessary to personalize the config/secrets.yml 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 email address and password after you log in. Use this feature to log in as an administrator and change the email and password to your own.

The variable domain_name is used for sending email. You can use example.com in development. If you already have a custom domain name you’ll use when you deploy the application, you can set domain_name. If you deploy the application to Heroku, you’ll set domain_name with the unique name you’ve given your application on Heroku. You’ll have to wait until you deploy to know the name you’ll use on Heroku.

If you don’t want to use Unix environment variables, you can set each value directly in the config/secrets.yml file. The file must be in your git repository when you deploy to Heroku. However, you shouldn’t save the file to a public GitHub repository where other people can see your credentials.

Database Seed File

The db/seeds.rb file initializes the database with default values.

# This file should contain all the record creation needed to seed the database with its default values.
# The data can then be loaded with the rake db:seed (or created alongside the db with db:setup).
#
# Examples:
#
#   cities = City.create([{ name: 'Chicago' }, { name: 'Copenhagen' }])
#   Mayor.create(name: 'Emanuel', city: cities.first)
user = CreateAdminService.new.call
puts 'CREATED ADMIN USER: ' << user.email

CreateAdminService is a service object that obtains admin_email and admin_password values from the config/secrets.yml file. You can examine the file app/services/create_admin_service.rb to see how a new user is created.

Set the Database

If you’ve used the Rails Composer tool to generate the application, the database is already set up with rake db:migrate and rake db:seed.

If you’ve cloned the repo, prepare the database and add the default user to the database by running the commands:

$ rake db:migrate
$ rake db:seed

Use rake db:reset if you want to empty and reseed the database.

If you’re not using rvm, 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.

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 permission. Your secret token should be at least 30 characters long and completely random.

Get a unique secret token:

rake secret

Edit the config/secrets.yml file to change the secret token.

Test the App

You can check that your application runs properly by entering the command:

$ rails server

To see your application in action, open a browser window and navigate to http://localhost:3000/.

You should see a home page with a navigation bar.

You should be able to click the navigation links for “Log in” and “Sign up.”

Stop the server with Control-C. If you test the app by starting the web server and then leave the server running while you install new gems, you’ll have to restart the server to see any changes. The same is true for changes to configuration files in the config folder. This can be confusing to new Rails developers because you can change files in the app folders without restarting the server. Stop the server each time after testing and you will avoid this issue.

RSpec Test Suite

The application contains a suite of RSpec feature tests. To run:

$ rspec

Deploy to Heroku

For your convenience, here is a Tutorial for Rails on Heroku. Heroku provides low cost, easily configured Rails application hosting.

You’ll need to precompile assets before you commit to git and push to Heroku:

$ RAILS_ENV=production rake assets:precompile
$ git add -A
$ git commit -m "assets compiled for Heroku"
$ git push origin master

If you’ve set configuration values in the config/secrets.yml file, you’ll need to set them as Heroku environment variables. You can set Heroku environment variables directly with heroku config:add. For example:

$ heroku config:add ADMIN_NAME='First User'
$ heroku config:add ADMIN_EMAIL='[email protected]' ADMIN_PASSWORD='changeme'
$ heroku config:add GMAIL_USERNAME='[email protected]' GMAIL_PASSWORD='secret'
$ heroku config:add DOMAIN_NAME='example.com'

Complete Heroku deployment with:

$ git push heroku master

See the Tutorial for Rails on Heroku for details.

Troubleshooting

Problems? Check the issues.

Issues

Please create a GitHub issue if you identify any problems or have suggestions for improvements.

Contributing

If you make improvements to this application, please share with others.

Send the author a message, create an issue, or fork the project and submit a pull request.

Credits

Sancho Sebastine – created the application and the tutorial