Data Commons Directory

From Cultivate.Coop

This page details how to set up a Data Commons online directory, in the style of It is intended for developers who wish to experiment with the directory on their own machine, modify it, and (ideally!) contribute to the project (see Data Commons Code Sprint).

These instructions are for Ubuntu. To use these instructions for other platforms, you could use VirtualBox (e.g. for windows, see here).

These instructions are based on:


Get ruby and rails, the language and web framework we use:

 sudo apt-get install ruby rake rubygems ruby-dev libjson-ruby
sudo gem install --version 2.2.2 --no-rdoc --no-ri rails
sudo gem install --no-rdoc --no-ri ruport acts_as_reportable ferret geokit

Get an interface to mysql, a database:

 sudo apt-get install libmysqlclient-dev
sudo gem install --no-rdoc --no-ri mysql

Set up a mysql server on your machine, for testing:

 sudo apt-get install mysql-server

Keep note of any username/password combination you set up. You'll need that later.

Get the tool needed to download our software (and, if you are feeling generous, to send back changes):

 sudo apt-get install bzr

The Directory Software

Pick a directory where you'd like to put the Data Commons Directory (DCD) software. Go there, and issue this command:

 bzr branch lp:datacommons

You should now have a copy of the DCD in a directory called "datacommons".

Enter the "datacommons" directory:

 cd datacommons

And configure the database:

 cp config/database.yml.dist config/database.yml

You'll need to modify database.yml to match any username/password combination you set up for your mysql server. For example, if you like using the gedit editor:

 gedit config/database.yml
# now find username and password entries and replace them.

Then create an empty database for the DCD:

 rake db:create
rake db:reset
rake db:migrate

(do "rake -T" to see all options)

At this point, running a test server should work. Leave this running in a terminal:


And then, from a browser, visit:


Setting up mysql

If the rake commands above (rake db:) don't work, one reason might have to do with your mysql setup. One way to set up a username/password in mysql is to log into mysql as root:

 mysql -u root -p

Create a new user and grant privileges:

 CREATE USER 'tester'@localhost IDENTIFIED BY 'changeme';
GRANT ALL PRIVILEGES ON dcp_development.* TO 'tester'@localhost;

Edit the database.yml file with this new username and password. The password, in the above example, would be "changeme", without the quotes. Try your rake commands again.


Searching the DCD relies on a separate service. To get searching working, start up the "Ferret Server" before running the web server (script/server above):

 script/ferret_server -e development -R $PWD start

If the index has never been built (i.e. first installation, first run, etc.):

 script/runner -e development 'Organization.rebuild_index'

Committing changes

Changes should be developed first in your own "branch", rather than trunk (lp:datacommons).

To create a branch, visit:
(choose "hosted" option)

Remember the launchpad username you chose, you'll be asked to provide it later.

When you create a branch, you'll be given a command like "bzr push ...." which can be used to put your changes online. You can then either send email to other DCP developers to have them review your work, or use the "propose merge" option.


Here's a snapshot of the schema used by the directory, for reference. To be sure you have an up-to-date schema, do "rake db:schema:dump".

We allow each organization to have multiple locations, people, legal structures, organization types, business sectors, and products+services associated with it. This is nice and flexible, with one downside: to import/export from a spreadsheet, you may need to "flatten" things - maybe restrict organizations to have one location and a fixed number of people associated with it.

Fields for "organizations":

 string   "name"
text     "description"
integer  "created_by_id"
integer  "updated_by_id"
string   "phone"
string   "fax"
string   "email"
string   "website"
date     "year_founded"
boolean  "democratic"
integer  "primary_location_id"
datetime "created_at"
datetime "updated_at"
... with cross-references to locations, people, legal structures, organization types, business sectors, products+services

For "locations":

 string   "note"
string   "physical_address1"
string   "physical_address2"
string   "physical_city"
string   "physical_state"
string   "physical_zip"
string   "physical_country"
string   "mailing_address1"
string   "mailing_address2"
string   "mailing_city"
string   "mailing_state"
string   "mailing_zip"
string   "mailing_country"
float    "latitude"     (we generate this automatically)
float    "longitude"  (we generate this automatically)
datetime "created_at"
datetime "updated_at"

For "people":

 string   "firstname"
string   "lastname"
string   "phone_mobile"
string   "phone_home"
string   "fax"
string   "email"
boolean  "phone_contact_preferred"
boolean  "email_contact_preferred"
datetime "created_at"
datetime "updated_at"

... and for the association between organizations and people ("contacts")...

 string   "role_name"
string   "phone"
string   "email"
datetime "created_at"
datetime "updated_at"

For "legal structure": (this is technically an open-ended list of options)

Limited Liability Corporation (LLC)
C Corp
S Corp
Non-profit Corporation

For "organization types": (this is technically an open-ended list of options)

 Academic Institution or Program
Activist or Social Change Organization
Artist -Run/Owned Space
Community Center
Community Currency or Barter Group
Community Development Credit Union
Community Development Financial Institution
Community Garden Project
Community Land Trust
Community Supported Agriculture (CSA) Program
Community-Building Group
Conservation/Agricultural Land Trust
Conventional Business
Conventional Non-Profit
Cooperative, Consumer
Cooperative, Financial
Cooperative, Housing
Cooperative, Marketing
Cooperative, Multi-Stakeholder
Cooperative, Producer
Cooperative, Retail
Cooperative, Worker
Credit Union
Fair Trade Organization or Business
Financial Institution Supporting Cooperatives
Government Agency/Department/Program
Intentional Community or Ecovillage
Majority Owned ESOP
Mutual-aid/Self-help Group
Network, Association or Coalition
Other Cooperative Financial Institution
Support Organization
Union or Other Labor Organization

For "business sectors": (this is technically an open-ended list of options)

 Accomodation & Food Services
Arts & Culture
Community & Economic Development
Community-Building & Mutual Aid
Construction & Repair
Farm, Fish & Forest
Farm, Fish & Forest_Animal Production
Farm, Fish & Forest_Crop Production
Farm, Fish & Forest_Fishing, Hunting & Trapping
Farm, Fish & Forest_Forestry & Logging
Finance & Insurance
Government & Public Administration
Housing & Land
Information Technology
Labor Organization
Legal Services
Manufacturing_Fabricated Metals
Manufacturing_Food & Beverage Production
Manufacturing_Machinery, Computers, Electronics, & Electrical Equipment
Manufacturing_Petroleum, Coal, Chemicals, Plastics, Minerals & Metals
Manufacturing_Textiles, Apparel & Leather
Manufacturing_Transportation Equipment
Manufacturing_Wood & Paper
Network, Coalition, or Association
Organizational Support & Development
Personal Care & Cleaning Services
Private Household
Religious or Spiritual
Retail Trade
Retail Trade_Books, Music & Hobby Supplies
Retail Trade_Clothing & Accessories
Retail Trade_Food, Beverages & Health Supplies
Retail Trade_Other
Retail Trade_Vehicles, Furniture, Electronics, Tools & Equipment
Social Change Organization
Social Services
Transportation & Warehousing
Waste Management & Remediation
Wholesale Trade

For "products+services": this is a completely open list.

Staying up to date

From time to time, the directory software may be updated. You can view updates here:

To merge them into your copy of the directory software, do:

 bzr pull

(make sure you are in the "datacommons" directory when you do that).