README_FOR_APP
= Noosfero: a free web-based social platform
== Setting up a Noosfero development/test environment
Noosfero is written in Ruby with the "Rails framework":http://www.rubyonrails.org,
so the process of setting it up is pretty similar to other Rails applications.
=== Requirements
noosfero is intended to be run in Debian stable. It can work in other environments, but we do not test on them.
You need to have git installed, as well as:
* Ruby: http://www.ruby-lang.org/
* Rake: http://rake.rubyforge.org/
* Ruby-GetText: http://www.yotabanana.com/hiki/ruby-gettext.html?ruby-gettext (at least version 1.9.0)
* Ruby-sqlite3: http://rubyforge.org/projects/sqlite-ruby
* rcov: http://eigenclass.org/hiki/rcov
* Ferret: http://ferret.davebalmain.com/trac
* RMagick: http://rmagick.rubyforge.org/
* RedCloth: http://whytheluckystiff.net/ruby/redcloth/
* will_paginate: http://github.com/mislav/will_paginate/wikis
* contacts: http://github.com/cardmagic/contacts/tree/master
* iso-codes: http://pkg-isocodes.alioth.debian.org/
* feedparser: http://packages.debian.org/sid/libfeedparser-ruby
* Daemons - http://daemons.rubyforge.org/
* Mongrel: http://mongrel.rubyforge.org/
* tango-icon-theme: http://tango.freedesktop.org/Tango_Icon_Library
There are Debian packages available for all of them but contacts. Try:
# aptitude install ruby rake libgettext-ruby1.8 libsqlite3-ruby rcov librmagick-ruby libredcloth-ruby libwill-paginate-ruby iso-codes libfeedparser-ruby libferret-ruby libdaemons-ruby mongrel mongrel-cluster tango-icon-theme
contacts is bundled together with noosfero for now, so you don't need to install it.
If you have problems with the setup, use the development mailing list. In
special its possible that the requirements list above is not complete.
=== Setting up a production environment
* install memcached. Study whether you need to raise the ammount of memory it uses for caching, depending on the demand you expect for your site.
* copy config/ferret_server.yml.dist to config/ferret_server.yml.dist
* configure the mongrel cluster: `mongrel_rails cluster::configure`
** then edit config/mongrel_cluster.yml to suit your environment. Make sure your apache configuration matches the mongrel cluster configuration, specially in respect to the ports and numbers of mongrel instances.
* create needed temporary directories:
mkdir tmp
mkdir tmp/pids
mkdir log
* create database (example using PostgreSQL, YMMV)
root user
=========
# sudo apt-get install postgresql libpgsql-ruby
# su - postgres
postgres user
=============
postgres@HOST:~$ createuser noosfero
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) y
Shall the new role be allowed to create more new roles? (y/n) n
noosfero_user
=============
createdb noosfero_production
createdb noosfero_development
createdb noosfero_test
* configure database access in config/database.yml
* test database access:
** first create the development database
rake db:schema:load
** if everything goes right, then create the production database:
RAILS_ENV=production rake db:schema:load
* create sample data:
RAILS_ENV=production rake db:populate
* compile the translations:
rake makemo
* start the server:
./script/production start
* to stop the server:
./script/production stop
* to restart the server:
./script/production restart
=== Boostraping a test environment
You can copy and paste the commands below into a terminal (please review the
commands and make sure you understand what you are doing):
# checkout the code from repository
git clone git://git.colivre.coop.br/noosfero.git
# enter the directory
cd noosfero
# copy a sample config file
cp config/database.yml.sqlite3 config/database.yml
# create the database:
rake db:migrate
# compile translations:
rake makemo
# create some test data:
./script/populate
# install the test dependences:
aptitude install libtidy-ruby libhpricot-ruby libmocha-ruby imagemagick
# run the automated test suite to make sure your environment is sane:
rake test
You should now be ready to go. Issue the following command to start the Rails
development server:
./script/server
The server will be available at http://localhost:3000/ . If you want to use
another port than 3000, you can use the -p option of ./script/server:
./script/server -p 9999
The above command makes the server available at http://localhost:9999/
The populate script creates some test users, one of them has login 'ze' and
password 'test'. You can use it or you can register a new user.
== Reporting bugs
Use Noosfero Tracker application at http://www.colivre.coop.br/Noosfero.
== Helping with development
* It's recommended that you subscribe to the development mailing
list: http://ynternet.net/mailman/listinfo/noosfero
* If you have a patch, create an appropriate action item
(bugs/requirement/enhancement) in the Tracker web (see "Reporting bugs"
above) of type.
== Releasing noosfero
To prepare a release of noosfero, you must follow the steps below:
* finish all requirements and bugs assigned to the to-be-released version
* make sure all tests pass
* write release notes at the version's wiki topic.
* generate package with rake package. Your tarball will be under the pkg/
directory, named as noosfero-${VERSION}.tar.gz
* test that the package contains everything that is needed: explode the tarball
in a temporary directory, copy config/database.yml.sqlite3 to
config/database.yml, and make rake db:migrate and rake test. If
everything is ok, you are done. If not, maybe some files are not going into
the tarball. See lib/tasks/package.rake, probably you'll need to change it.
* Go to the version's wiki topic and edit it to reflect the new reality.
* Attach the generated package to that topic. Before attaching calculate the md5 of the package (with mu5sum and paste the MD5 hash as comment in the attachment form)
* Download the attached and verify the MD5 hash
* create a git tag for the released version with git tag.
* IMMEDIATELY change the version in lib/noosfero.rb to the next version. (e.g.
0.2.0 -> 0.3.0)
* update an eventual demonstration version that you run.
* write an announcement e-mail to the relevant maimling lists pointing to the release notes, and maybe to the demonstration version.
If you had any problem during these steps, you can do rake clobber_package to
completely delete the generated packages and start the process again.
== Working with translations
* Update translation files: rake updatepo. Then git commit them.
* Send the PO files to the translators.
* Get the PO files back from translators, put in po/ under the correct language
name (e.,g. po/pt_BR/) and git commit.
* test translations: rake makemo and browse the application on the web.