Setting Up Your Development Environment

From Wontology

Jump to: navigation, search

Contents

Introduction

This page provides detailed instructions for setting up a WontoMedia development environment, including setting up a directory tree and repository using Git, and installing all of the Ruby gems on which WontoMedia's automated test suite depends. If you have any problems, please let us know on our forum or email list.

Supported Platforms

The fundamental systems on which WontoMedia depends (the Ruby programming language and the Ruby-on-Rails web application framework) are available on and support a wide variety of platforms, operating systems, web servers, and database packages. However, currently our testing of WontoMedia is limited to a single system configuration. It is likely that you can successfully install and run WontoMedia on configurations other than what we've used to test, and we will try to support you in this, but at this point we cannot make any guarantees. If you do install WontoMedia on a different system configuration, please let us know on our forum or email list, whether you have problems or success.

WontoMedia Testing Platform

WontoMedia has been developed and tested on the following system configuration:

WontoMedia on Commercial Hosting Providers

WontoMedia has been installed and tested on shared servers at A2 Hosting. Installing on A2 Hosting provides details of the steps involved.

Installation Steps

Preparing for WontoMedia Source

If you have already installed WontoMedia as a gem, it is recommended that you uninstall the gem before setting up a development environment. 

sudo gem uninstall wontomedia

Note that this will not eliminate the contents of any database you have already been using with WontoMedia. If you configure your new database.yml file (below) with the same database-access values you were previously using, your new WontoMedia installation should contain and serve the same data you had. If this isn't desired, you will have to manually drop the content of the old database.

WontoMedia development uses the Git source code management system. To install the full source tree for WontoMedia, you will have to use Git, which you can install by 

sudo apt-get install git-core

Cloning the WontoMedia Source

There are several URLs you can install from, depending on your intentions. Fortunately, changing your "origin" repository later is straight-forward, so there is no problem if your use of WontoMedia changes over time. In particular:

  • git://github.com/gleneivey/wontomedia.git is the "Public" clone URL for our "working" repository on GitHub. If in doubt, use this one. This repository receives the most frequent updates, and is the primary repository for our continuous integration and automated testing. The HEAD of the master branch in this repository should be functional nearly all the time (e.g., barring CI failures), but may contain partial implementations of UI features.
  • git@github.com:gleneivey/wontomedia.git points to the same repository as the above, but is for use by people with commit access. Our policy is to grant committer access to anyone requesting it, in the hope that we'll have few cases where we end up having to revoke access. To request, email to development at wontology dot org or send a GitHub message to gleneivey.
  • git://rubyforge.org/wontomedia.git is the clone URL for the stable/release repository on RubyForge. Code will be pushed from GitHub to RubyForge on completion of each "user story", and the latest numbered, stable release is the HEAD of the master branch.
  • [your own GitHub repository URL] The work flow provided by GitHub, which we hope to use extensively, is based on developers creating their own "forked" repositories, submitting their changes there, and then making "pull requests" to the repository from which they forked. If you're going to be making more than occasional changes to WontoMedia, you should consider this option. And when you do create your own WontoMedia fork on GitHub, you will have your own "committer" Git URL for that repository, and should clone from that.

For more information on how, when, and why source changes are merged from one repository/branch to another, see our Development and Release Process.

From the directory in which you want to create your wontomedia file tree, execute the command: 

git clone git://github.com/gleneivey/wontomedia.git

(substituting the Git URL you decided on). This will create a wontomedia directory, and populate it with the WontoMedia source code plus all revision control files. In your development, you will use git commit locally, and then either prepare a patch or push to a network repository when you want to share your changes. (See I've Just Got a Little Change.)

Configuring

database.yml

You must create a database.yml file in wontomedia/config with information matching the content of your local database. This process is explained well by the Rails "Getting Started" Guide, which also gives instructions for databases other than MySQL. WontoMedia includes the file database-mysql-development.yml that you can use as a starting point: 

# MySQL.  Versions 4.1 and 5.0 are recommended.
 
production:
  adapter: mysql
  encoding: utf8
  database: wontomedia_production
  pool: 5
  username: wontomedia-user
  password: replace-bad-passwd
  socket: /var/run/mysqld/mysqld.sock
 
development:
  adapter: mysql
  encoding: utf8
  database: wontomedia_development
  pool: 5
  username: wontomedia-user
  password: replace-bad-passwd
  socket: /var/run/mysqld/mysqld.sock
 
# Warning: The database defined as "test" will be erased and
# re-generated from your development database when you run "rake".
# Do not set this db to the same as development or production.
test:
  adapter: mysql
  encoding: utf8
  database: wontomedia_test
  pool: 5
  username: wontomedia-user
  password: replace-bad-passwd
  socket: /var/run/mysqld/mysqld.sock

You will likely want to replace the values of (at least) all the items shown in bold. Note that, if you are changing from a prior gem-based WontoMedia installation and want to keep any data you have entered, you'll want to use the values from your old database.yml file in either the production or development blocks of the new file. Whatever database you specify in the test block of your new database.yml will be automatically emptied each time you run any of WontoMedia's automated tests, so you should not specify the access information for any database whose content you want to keep.

Also, the sample file assumes that you are using the same "database user" (and therefore password) for all three databases. If you have multiple database users, you may substitute different information into each block in the file.

Of course, you will have to actually create the databases and database user(s) that you name in database.yml using your database tools. (Recall that Install from Scratch contains instructions for using the mysql command-line tool for creating one database if you are using the MySQL database.)

wontomedia.rb

As described in Install from Scratch, you must create a config/initializers/wontomedia.rb file, which you can do by copying and customizing assets/wontomedia-sample.rb.

Install Development Dependencies

In addition to the packages you must have installed in order to run WontoMedia (again, see Install from Scratch), there are a number of other packages used by WontoMedia's automated test suite and by other developers. These should be installed prior to attempting to use rake on WontoMedia. The install commands needed are: 

apt-get install libxml2-dev libxslt1-dev
gem1.8 install nokogiri
gem1.8 install rspec rspec-rails webrat cucumber cucumber-rails
gem1.8 install rubyforge technicalpickles-jeweler ZenTest

The first three lines are all required in order to install cucumber, which WontoMedia uses for automated acceptance testing. WontoMedia uses jeweler (which requires rubyforge) to build its .gemspec and release gems (the original information for our gem is contained in our Rakefile).

Finally, WontoMedia is configured (.autotest file and rake tasks) so that you can use the autotest tool contained in the ZenTest package. If you are not interested in using autotest, then installing ZenTest is not necessary. If you are going to use autotest, then the environment variable AUTOFEATURE should be set to true autospec before you start it, see the autotest page of the Cucumber wiki for more information.

Launching WontoMedia

Before starting WontoMedia for the first time, you must initialize your development database, which can be done with the command: 

rake db:reseed

if you have not done this already and/or you'd like to discard any data you've added to earlier WontoMedia installations on using the same database-connection settings.

You must also configure the links from the standard Ruby-on-Rails directories in your WontoMedia source tree to the customization files you wish to use. To use the sample/default customization files included with WontoMedia (a good starting point), run the command: 

rake customize[default-custom]

You can find instructions on using alternative customization files and different parameters to the "customize" rake task in the file doc/customization.markdown. Also, a few notes on making changes to customization files during your development:

  1. Never commit a symbolic link to your Git repository. The built-in rake tasks should prevent this from happening, but you shouldn't "fix" your local versions of these to circumvent this rule.
  2. If you are making a change in appearance or behavior that you believe would be appropriate to include in other people's initial WontoMedia installations, feel free to make the changes under the default-custom directory and to contribute them back to the public.
  3. If you are making a change that is specific to your installation of WontoMedia, you should create a separate, parallel directory structure entirely outside of your WontoMedia source tree for your local version of the customization file(s). Keep in mind that you only need to make copies of the customization files that you actually want to modify, and can use the rake customize[default-custom:your-directory] form of the command to combine your local changes with the default customization files you want to use unmodified. It would likely be wise to place your customization directory(ies) under (Git) revision control, but WontoMedia does not necessitate this.
  4. If your are making your change(s) in order to incorporate a new installation-specific string or parameter, consider whether it would be appropriate to add a new customization value in config/initializers/wontomedia.rb (with matching changes in all of the core and default-custom files that are appropriate) instead of hard-coding your customization directly into your local WontoMedia source.
  5. Be very cautious of making changes to WontoMedia that involve moving files from one of the standard Ruby-on-Rails directories into default-custom. If you have decided that you need to make part of the WontoMedia core into customizable files, consider dividing the core file(s) into parts. For an example, see the division between app/views/items/home.html.erb and app/views/layouts/home.html.erb. The view in items is customizable, to control what content is placed in the home page and how it is ordered, but home-page in layouts is not customizable to provide the common structure through which the desired content is presented. If you do make a new customizable file, if it is based on an existing "core" WontoMedia file, remember to use git mv (instead of git rm followed by git add) to preserve the revision history for the portions of the file that you do not modify.
  6. Remember that WontoMedia is open-source software distributed under the "copy-left" Affero General Public License (the AGPLv3). This license requires that you make the modified versions of any WontoMedia files you change publicly available. This doesn't apply to the samples for the config files that you have to create (database.yml and initializers/wontomedia.rb), but it does apply to the default customization files under the default-custom directory.

Validating Your Installation

After all of the preceding steps, you should be able to run WontoMedia's automated test set to verify your install and development environment: 

rake customize[default-custom]
rake

Of course, you will use different directory names in the argument to the customize task (in the square brackets) if you have local customizations for your wontology site. Also, any time you re-execute the customize task, you should either execute rake asset:packager:build_all yourself (to re-incorporate your customizations into the packaged JavaScript and CSS files WontoMedia uses) or re-execute rake without any arguments to rebuilt and retest everything incorporating your customizations.

To create an installable gem from your local code (which is automatically done as part of the default rake task executed by rake-with-no-options), use the command: 

rake build

If all of these commands run cleanly, you're ready to start making changes in your local environment. Good hunting!

Retrieved from "http://wiki.wontology.org/Setting_Up_Your_Development_Environment"
Personal tools