Freehub Developer Guide

This developer guide is a work in progress with information added as we need to capture it.

Contributors

To contribute to Freehub, feel free to send a pull request or join the freehub-users google group. We'll take it from there.

You can check Freehub out from GitHub.

See Where To Find Things to start getting familiar with Freehub.

Development

Freehub was originally created in 2008 and is worked on part time or not at all for long stretches of time (like years!). For this reason, it has a number of dependencies that are out of date. For example, it uses Ruby 1.9.3 and Rails 2.3. If anyone wants to help update to more modern versions of Ruby and Rails, let us know ;-)

Freehub is set up for development using Docker in order to make it easy to get set up with the correct versions of Ruby, Rails, and MySQL.

To get set up developing Freehub with Docker, first install Docker and Docker Compose (Compose is included with Docker Desktop for Mac and Windows).

Then checkout Freehub:

git clone https://github.com/asalant/freehub.git
cd freehub

Bootstrap the Docker images, create the development databases, and load test data:

docker-compose build

docker-compose up
docker-compose exec app rake db:create db:schema:load db:fixtures:load
docker-compose exec app rake db:create RAILS_ENV=test

Once you have done this you can open the app, log in, and play around.

open http://localhost:3000

The test user below is preconfigured.

username: sfbk
password: test

To run the test suite:

docker-compose exec app rake test

To get a console into the docker MySQL instance (the development root password is password):

docker-compose exec app mysql freehub_for_all_development -h mysql -u root -p

Use run instead of exec in any of the above commands if the app container has not been started with docker-compose up.

To shut down the containers (but not lose database data):

docker-compose stop

To stop and remove the containers (losing database data):

docker-compose down

What's going on here is that we are using docker-compose to manage two docker containers, one that runs the Rails app and one that runs MySQL. The container running the app is started with your local freehub working directory mapped to /app in the container where Rails is run from. You can make changes locally and they will be picked up immediately.

To run any rake tasks or scripts in the Rails container, just prefix with docker-compose run app. If you make changes to gem dependencies, you'll need to rebuild the app container with docker-compose build.

For background and more info on this Docker setup, see "this post":https://blog.codeship.com/running-rails-development-environment-docker/.

Related Projects/Tools

Freehub uses:

• "HAML":http://haml-lang.com for generating markup in its views.
• the Ruby Test::Unit testing suite with Rails fixtures.
• "annotate-models":http://github.com/ctran/annotate_models plugin for model schema information

References and Tutorials

• "Rails API, method reference":http://api.rubyonrails.org/
• "Front to back Rails tutorial":http://railstutorial.org/ that uses github as its example VCS. Uses Heroku for deployment, eRB for views and rspec for testing, which isn't that helpful, but it's a good starter tutorial anyway.
• "RailsGuides":http://guides.rubyonrails.org/index.html In depth guides to particular features. Look here if you're already familiar with rails, but need more.

License

Freehub is licensed for use under the "Apache 2.0 License":http://www.apache.org/licenses/LICENSE-2.0.