From 70e2e7b0f576ccb3a00c898c64c48ca388b993b4 Mon Sep 17 00:00:00 2001 From: Antonio Terceiro Date: Thu, 29 Jul 2010 18:26:39 -0300 Subject: [PATCH] General review of installation instructions --- INSTALL | 311 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++------------------------------------------------------------------------ 1 file changed, 239 insertions(+), 72 deletions(-) diff --git a/INSTALL b/INSTALL index cfa504b..d363475 100644 --- a/INSTALL +++ b/INSTALL @@ -13,13 +13,14 @@ You need to install some packages Noosfero depends on. On Debian GNU/Linux or Debian-based systems, all of these packages are available through the Debian archive. You can install them with the following command: - # 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 + # apt-get install ruby rake po4a libgettext-ruby-util 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 On other systems, they may or may not be available through your regular package management system. Below are the links to their homepages. * Ruby: http://www.ruby-lang.org/ * Rake: http://rake.rubyforge.org/ +* po4a: http://po4a.alioth.debian.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 @@ -33,78 +34,168 @@ management system. Below are the links to their homepages. * Mongrel: http://mongrel.rubyforge.org/ * tango-icon-theme: http://tango.freedesktop.org/Tango_Icon_Library -If you manage to install Noosfero successfully, please feel free to contact the -Noosfero development mailing with the instructions for doing so, and we'll -include it here. +Note: the tango-icon-theme package is not available in Debian Lenny's main +repository, because back then it was not DFSG-free (Debian Squeeze will have it +in main). You can either add the non-free repository to your sources.list file, +or download the .deb directly and install it manually with `dpkg -i`. In this +case will need do install hicolor-icon-theme as well bacause tango-icon-theme +depends on it. After that you can try the command line above again, but +without "tango-icon-theme". + +If you manage to install Noosfero successfully on other systems than Debian, +please feel free to contact the Noosfero development mailing with the +instructions for doing so, and we'll include it here. === Setting up a production environment +As root user +============ + NOTE: these instructions are for seting up a *production* environment. If you -are going to do Noosfero development, you don't need to do these steps. See the -HACKING file instead. +are going to do Noosfero development, you don't need to do these steps. Stop +here and see the HACKING file instead. + +Install memcached. On Debian: + +# sudo apt-get 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. If you are going to run a +high-traffic site, you will want to raise the ammount of memory reserved for +caching. + +It is recommended that you run noosfero with its own user account. To create +such an account, please do the following: + +# sudo adduser --system --group noosfero --shell /bin/sh --home /var/lib/noosfero noosfero + +(note that you can change the $HOME directory of the user if you wish, here we +are using /var/lib/noosfero) + +The --system option will tell adduser to create a system user, i.e. this user +will not have a password and cannot login to the system directly. To become +this user, you have to use sudo: + +# sudo -u noosfero -i + +or + +# sudo su - noosfero + +As noosfero user +================ + +Enter the directory where you unpacked noosfero (or do it now and enter the +directory). Here we are cloning the noosfero repository from git, but you can +do it with a tarball as well. + +$ git clone git://git.colivre.coop.br/noosfero.git current +$ cd current +$ git checkout -b stable origin/stable + +Copy config/ferret_server.yml.dist to config/ferret_server.yml. You will +probably not need to customize this configuration, but have a look at it. + +Create the mongrel configuration file: + +$ mongrel_rails cluster::configure + +Edit config/mongrel_cluster.yml to suit your needs. Make sure your apache +configuration matches the mongrel cluster configuration, specially in respect +to the ports and numbers of mongrel instances. + +Note: currently Noosfero only supports Rails 2.1.0, which is the version in +Debian Lenny. If you have a Rails version newer than that, Noosfero will +probably not work. You can install Rails 2.1.0 into your Noosfero installation +with the following procedure: + +$ cd /var/lib/noosfero/current/vendor +$ wget http://ftp.de.debian.org/debian/pool/main/r/rails/rails_2.1.0.orig.tar.gz +$ tar xzf rails_2.1.0.orig.tar.gz +$ ln -s rails-2.1.0 rails + +As root user +============ + +Setup Noosfero log and tmp directories: + +# cd /var/lib/noosfero/current +# sudo etc/init.d/noosfero setup + +Now it's time to setup the database. In this example we are using PostgreSQL, +so if you are planning to use a different database this steps won't apply. + +# apt-get install postgresql libpgsql-ruby +# su postgres -c '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 + +As noosfero user +================ + +Now create the databases: -* 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. -* enter the directory where you unpacked noosfero -* copy config/ferret_server.yml.dist to config/ferret_server.yml -* create the mongrel configuration file: `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) +$ cd /var/lib/noosfero/current +$ createdb noosfero_production +$ createdb noosfero_development +$ createdb noosfero_test - root user - ========= - # sudo apt-get install postgresql libpgsql-ruby - # su - postgres +The development and test databases are actually optional. If you are creating a +stricly production server, you will probably not need them. - 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 +Now we want to configure Noosfero for accessing the database we just created. +To do that, you can 1) copy config/database.yml.pgsql to config/database.yml, +or create config/database.yml from scratch with the following content: - noosfero_user - ============= - createdb noosfero_production - createdb noosfero_development - createdb noosfero_test + production: + adapter: postgresql + encoding: unicode + database: noosfero_production + username: noosfero -* configure database access in config/database.yml +Now, to test the database access, you can fire the Rails database console: -* 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 +$ ./script/dbconsole production -* create sample data: - RAILS_ENV=production rake db:populate +If it connects to your database, then everything is fine. If you got an error +message, then you have to check your database configuration. -* Add the domain name you will be using for your noosfero site to the list of - environment domain, like this: +Create the database structure: - ./script/runner "Environment.default.domains << Domain.new(:name => 'your.domain.com')" +$ RAILS_ENV=production rake db:schema:load - (of course, replace your.domain.com with your real domain) +Now we have to create some initial data. To create your default environment +(the first one), run the command below: -* compile the translations: - rake makemo +$ RAILS_ENV=production ./script/runner 'Environment.create!(:name => "My environment", :is_default => true)' -* start the server: - ./script/production start +(of course, replace "My environment" with your environment's name!) -* to stop the server: +And now you have to add the domain name you will be using for your noosfero +site to the list of domains of that default environment you just created: - ./script/production stop +$ RAILS_ENV=production ./script/runner "Environment.default.domains << Domain.new(:name => 'your.domain.com')" -* to restart the server: +(replace "your.domain.com" with your actual domain name) - ./script/production restart +Compile the translations: -* enable the following apache modules: +$ RAILS_ENV=production rake noosfero:translations:compile + +To start the Noosfero application servers: + +$ ./script/production start + +At this point you have a functional Noosfero installation running, the only +thing left is to configure your webserver as a reverse proxy to pass requests +to them. + +==================== +Apache configuration +==================== + +Firts you have to enable the following some apache modules: deflate expires @@ -113,26 +204,32 @@ HACKING file instead. proxy_http rewrite - On Debian GNU/Linux system, these modules can be enabled with the following - command line, as root: +On Debian GNU/Linux system, these modules can be enabled with the following +command line, as root: + +# a2enmod deflate expires proxy proxy_balancer proxy_http rewrite - a2enmod deflate expires proxy proxy_balancer proxy_http rewrite +In other systems the way by which you enable apache modules may be different. - In other systems the way by which you enable apache modules may be different. +Now with the Apache configuration. You can use the template below, replacing +/var/lib/noosfero/current with the directory in which your noosfero +installation is, your.domain.com with the domain name of your noosfero site. +We are assuming that you are running two mongrel instances on ports 3000 and +3001. If your setup is different you'll need to adjust section. If you +don't understand something in the configuration, please refer to the apache +documentation. -* Configure apache web server as a reverse proxy. You can use the template - below, replacing /path/to/noosfero with the directory in which your noosfero - installation is, your.domain.com with the domain name of your noosfero site. - We are assuming that you are running two mongrel instances on ports 4000 and - 4001. If your setup is different you'll need to adjust section. If - you don't understand something in the configuration, please refer to the - apache documentation. +Add a file called "mysite" (or whatever name you want to give to your noosfero +site) to /etc/apache2/sites-available with the following content, and customize +as needed (as usual, make sure you replace "your.domain.com" with you actual +domain name, and "/var/lib/noosfero/current" with the directory where Noosfero +is installed): ServerName your.domain.com - DocumentRoot "/path/to/noosfero/public" - + DocumentRoot "/var/lib/noosfero/current/public" + Options FollowSymLinks AllowOverride None Order Allow,Deny @@ -156,18 +253,88 @@ HACKING file instead. LogLevel warn CustomLog /var/log/apache2/noosfero.access.log combined - Include /path/to/noosfero/etc/noosfero/apache/cache.conf + Include /var/lib/noosfero/current/etc/noosfero/apache/cache.conf - BalancerMember http://127.0.0.1:4000 - BalancerMember http://127.0.0.1:4001 + BalancerMember http://127.0.0.1:3000 + BalancerMember http://127.0.0.1:3001 Order Allow,Deny Allow from All - The cache.conf file included in the end of the section is - important, since it will tell apache to pass expiration and cache headers to - clients so that the site feels faster for users. Do we need to say that using - that configuration is strongly recommended? +The cache.conf file included in the end of the section is +important, since it will tell apache to pass expiration and cache headers to +clients so that the site feels faster for users. Do we need to say that using +that configuration is strongly recommended? + +Enable that site with (as root, replace "mysite" with the actual name you gave +to your site configuration): + +# a2ensite mysite + +Now restart your apache server (as root): + +# invoke-rc.d apache2 restart + +============ +Maintainance +============ + +To ease the maintainance, install a symbolic link for the Noosfero startup +script in your server and add it to the system initialization and shutdown +sequences (as root): + +# ln -s /var/lib/noosfero/current/etc/init.d/noosfero /etc/init.d/noosfero +# update-rc.d noosfero defaults + Adding system startup for /etc/init.d/noosfero ... + /etc/rc0.d/K20noosfero -> ../init.d/noosfero + /etc/rc1.d/K20noosfero -> ../init.d/noosfero + /etc/rc6.d/K20noosfero -> ../init.d/noosfero + /etc/rc2.d/S20noosfero -> ../init.d/noosfero + /etc/rc3.d/S20noosfero -> ../init.d/noosfero + /etc/rc4.d/S20noosfero -> ../init.d/noosfero + /etc/rc5.d/S20noosfero -> ../init.d/noosfero + +Now to start Noosfero, you do as root: + +# invoke-rc.d noosfero start + +To stop Noosfero: + +# invoke-rc.d noosfero start + +To restart Noosfero: + +# invoke-rc.d noosfero restart + +Noosfero will be automatically started during system boot, and automatically +stopped if the system shuts down for some reason (or during the shutdown part +of a reboot). + +========= +Upgrading +========= + +If you followed the steps in this document and installed Noosfero from the git +repository, then upgrading is easy. As the noosfero user, do the following: + +$ cd /var/lib/noosfero/current +$ ./script/git-upgrade + +The git-upgrade script will take care of everything for you. It will first stop +the service, then fetch the current source code, upgrade database, compile +translations, and then start the service again. + +Note 1: make sure your local git repository is following the "stable" branch, +just like the instructions above. The "master" branch is not recommended for +use in production environments. + +Note 2: always read the release notes before upgrading. Sometimes there will be +steps that must be performed manually. If that is the case, you can invoke the +git-upgrade script with the special parameter "--shell" that will give you a +shell after the upgrade, which you can use to perform any manual steps +required: + +$ ./script/git-upgrade --shell -- libgit2 0.21.2