This guide will help you quickly set up a development environment where you can contribute code to Handy. This guide will be especially useful for newcomers to Rails development.
Specifically, this guide will show you how to use VirtualBox and Vagrant to set up your dev environment with a virtual machine (VM). If you feel comfortable with Rails and don't want to use a VM, this guide isn't for you.
We'll use VirtualBox and Vagrant to prepare our environment.
Go here to get VirtualBox for your machine.
Then, go here to get Vagrant.
VirtualBox is a VM provider. It does the actual work of hosting a fake computer (the VM) in your computer (the host). Vagrant is a tool that works on top of VirtualBox. It makes sharing and configuring development environments easy.
Once you've installed the tools, I recommend going through Vagrant's Getting Started guide so you understand what's going on and you're confident your installations were successful. Or don't. I'm not the boss of you.
Now you're ready to spin up your virtual machine. In whatever directory you want to work on Handy, clone the repo with git clone https://github.com/Pitt-CSC/handy.git (or the URL of your fork). If you look at the code you just cloned, you'll see the familiar Rails project layout and some other files. One of these is called Vagrantfile. It contains the instructions to Vagrant for how to create your new VM. Inside, it directs Vagrant to download the base box WillEngler/handy. That's an Ubuntu (Linux) image with all the dependencies you'll need to start the development server.
Open Vagrantfile in a text editor to make sure you're OK with all of the settings. Then, from a terminal in the same directory, execute vagrant up to start your VM. Vagrant will start by downloading the 500MB base box from the internet, so this will take a while. Get a drink. Take a walk. Call your grandmother. Eventually, the VM will be running.
If you're not comfortable with Linux and the command line, you might want to take a break now to learn the basics. Here is a nice guide. You can get by if you're comfortable with the first three sections.
Now that you've created your VM, get inside by vagrant sshing in from the project directory. If you look at your pwd, you'll see that you were dropped in to /home/vagrant aka /~. This is not the same as the special /vagrant directory where we'll be spending most of our time. cd to /vagrant.
/vagrant is special because Vagrant synchronizes this folder to the project directory on your host machine. So if you add a new file to your project directory, it will show up in /vagrant and vice versa. This will let you edit files on your host and run the server on the VM. You'll notice that all of the Handy code is in /vagrant.
If you jump the gun and try to start the server now, you'll see some donk-nasty error messages complaining about twilio.yml. Handy needs config/twilio.yml, config/secrets.yml, and config/database.yml to work. But none of those files are in the Handy repo! That's because they contain senstive information that shouldn't be committed to GitHub.
Helpfully, the project maintainers have provided sample versions of each file. The Vagrantfile a provisioning script that creates default versions of database.yml and secrets.yml. The autogenerated database.yml marks root's password as root because that's how I set up MySQL on the base box. The autogenerated secrets.yml just uses the values in secrets.yml.sample. That would be crazy dangerous if we deployed the application like that, but it's OK for development.
Handy uses Twilio to send and receive text messages. You'll need your own Twilio account to work with Handy. Go to their website and make an account. You won't need a credit card.
Once you've signed up for a trial account, find your account credentials. Use them to fill in twilio.yml.
In /vagrant/handy, run bundle install to make sure all of the Ruby gems Handy needs are installed on your VM. I installed them myself on the base box, but as the project changes, Handy will use new gems and the base box will become out of date.
We'll need to create the tables that Handy needs in the database.
rake db:drop db:create db:schema:load --trace
rake db:seed --trace
That should do it.
You're ready to start! From /vagrant/handy, execute rails server -b 0.0.0.0. You wouldn't need -b 0.0.0.0 if you weren't running the server from a VM. By default, the rails server will bind to 127.0.0.1 (aka Localhost). That will get the HTTP responses "stuck" in the VM and not let them through to your host machine. Binding to 0.0.0.0 prevents that.
Once you've started your server, open up a web browser on the host machine and enter Localhost:3000 into the address bar. If you see Handy's login page, congratulations! You've set up your development environment!
This is as far as I can take you. Check out the issue tracker to see if there are bugs or enhancements you can work on. Or maybe add something you think would be cool. Good luck!