Data Commons Directory
This page details how to set up a Data Commons online directory, in the style of find.coop. 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:
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; exit
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'
Changes should be developed first in your own "branch", rather than trunk (lp:datacommons).
To create a branch, visit:
https://code.launchpad.net/datacommons/+addbranch (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
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"
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)
Informal Cooperative Partnership Limited Liability Corporation (LLC) C Corp S Corp Non-profit Corporation 501(c)3 501(c)4
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 Collective 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 ESOP 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 Childcare 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 Healthcare Housing & Land Information Technology Labor Organization Legal Services Manufacturing Manufacturing_Fabricated Metals Manufacturing_Food & Beverage Production Manufacturing_Furniture Manufacturing_Machinery, Computers, Electronics, & Electrical Equipment Manufacturing_Other Manufacturing_Petroleum, Coal, Chemicals, Plastics, Minerals & Metals Manufacturing_Printing Manufacturing_Textiles, Apparel & Leather Manufacturing_Transportation Equipment Manufacturing_Wood & Paper Media Mining 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 Utilities 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:
(make sure you are in the "datacommons" directory when you do that).