ref: master
./INSTALL.md
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 |
Noosfero installation instructions from source for production environments ========================================================================== The instructions below can be used for setting up a Noosfero production environment from the Noosfero sources. Before you start installing Noosfero manually, see the information about the Noosfero Debian package at http://noosfero.org/Development/DebianPackage. Using the Debian packages on a Debian stable system is the recommended method for installing production environments. If you want to setup a development environment instead of a production one, stop reading this file right now and read the file `HACKING.md` instead. For a complete installation guide, please see the following web page: http://noosfero.org/Development/HowToInstall If you have problems with the setup, please feel free to ask questions in the development mailing list. Requirements ------------ **DISCLAIMER**: this installation procedure is tested with Debian stable, which is currently the only recommended operating system for production usage. It is possible that you can install it on other systems, and if you do so, please report it on one of the Noosfero mailing lists, and please send a patch updating these instructions. 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. 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: # 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 libdaemons-ruby thin \ 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-sqlite3: http://rubyforge.org/projects/sqlite-ruby * rcov: http://eigenclass.org/hiki/rcov * RMagick: http://rmagick.rubyforge.org * RedCloth: http://redcloth.org * will_paginate: http://github.com/mislav/will_paginate/wikis * iso-codes: http://pkg-isocodes.alioth.debian.org * feedparser: http://packages.debian.org/sid/libfeedparser-ruby * Daemons - http://daemons.rubyforge.org * Thin: http://code.macournoyer.com/thin * tango-icon-theme: http://tango.freedesktop.org/Tango_Icon_Library 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. As root user ============ Install memcached. On Debian: # 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: # adduser --system --group noosfero --shell /bin/sh --home /var/lib/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 # su - noosfero As noosfero user ================ downloading from git -------------------- Here we are cloning the noosfero repository from git. Note: you will need to install git before. $ git clone https://gitlab.com/noosfero/noosfero.git current $ cd current $ git checkout -b stable origin/stable downloading tarball ------------------- Note: replace 0.39.0 below from the latest stable version. $ wget http://noosfero.org/pub/Development/NoosferoVersion00x39x00/noosfero-0.39.0.tar.gz $ tar -zxvf noosfero-0.39.0.tar.gz $ ln -s noosfero-0.39.0 current $ cd current Create the thin configuration file: $ thin -C config/thin.yml -e production config Edit config/thin.yml to suit your needs. Make sure your apache configuration matches the thin cluster configuration, specially in respect to the ports and numbers of thin instances. *Note*: currently Noosfero only supports Rails 2.3.5, which is the version in Debian Squeeze. If you have a Rails version newer than that, Noosfero will probably not work. You can install Rails 2.3.5 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.3.5.orig.tar.gz $ tar xzf rails_2.3.5.orig.tar.gz $ ln -s rails-2.3.5 rails As root user ============ Setup Noosfero log and tmp directories: # cd /var/lib/noosfero/current # ./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. Pay special attention to the default collation defined on your setup by the environment variable LC_COLLATE because it might interfere in some sorting operations on your database. For more information checkout `man locale`. # apt-get install postgresql libpgsql-ruby # su postgres -c 'createuser noosfero -S -d -R' By default Rails will try to connect on postgresql through 5432 port, you can check it on `/etc/postgresql/8.4/main/postgresql.conf` file. Restart postgresql: # invoke-rc.d postgresql restart Noosfero needs a functional e-mail setup to work: the local mail system should be able to deliver e-mail to the internet, either directly or through an external SMTP server. Please check the documentation at the INSTALL.email file. As noosfero user ================ Now create the databases: $ cd /var/lib/noosfero/current $ createdb noosfero_production $ createdb noosfero_development $ createdb noosfero_test The development and test databases are actually optional. If you are creating a stricly production server, you will probably not need them. 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: production: adapter: postgresql encoding: unicode database: noosfero_production username: noosfero Now, to test the database access, you can fire the Rails database console: $ ./script/dbconsole production If it connects to your database, then everything is fine. If you got an error message, then you have to check your database configuration. Create the database structure: $ RAILS_ENV=production rake db:schema:load Compile the translations: $ RAILS_ENV=production rake noosfero:translations:compile Now we must create some initial data. To create your default environment (the first one), run the command below: $ RAILS_ENV=production ./script/runner 'Environment.create!(:name => "My environment", :is_default => true)' (of course, replace "My environment" with your environment's name!) 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: $ RAILS_ENV=production ./script/runner "Environment.default.domains << Domain.new(:name => 'your.domain.com')" (replace "your.domain.com" with your actual domain name) Add at least one user as admin of environment: $ RAILS_ENV=production ./script/runner "User.create(:login => 'adminuser', :email => 'admin@example.com', :password => 'admin', :password_confirmation => 'admin', :environment => Environment.default, :activated_at => Time.new)" (replace "adminuser", "admin@example.com", "admin" with the login, email and password of your environment administrator) 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 instalation ================== # apt-get install apache2 Configuration - noosfero at / ----------------------------- First you have to enable the following some apache modules: * deflate * expires * proxy * proxy_balancer * proxy_http * rewrite 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 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 thin instances on ports 3000 and 3001. If your setup is different you'll need to adjust `<Proxy>` 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): <VirtualHost *:80> ServerName your.domain.com DocumentRoot "/var/lib/noosfero/current/public" <Directory "/var/lib/noosfero/current/public"> Options FollowSymLinks AllowOverride None Order Allow,Deny Allow from all </Directory> RewriteEngine On # Rewrite index to check for static index.html RewriteRule ^/$ /index.html [QSA] # Rewrite to check for Rails cached page RewriteRule ^([^.]+)$ $1.html [QSA] RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f RewriteRule ^.*$ balancer://noosfero%{REQUEST_URI} [P,QSA,L] ErrorDocument 503 /503.html ErrorLog /var/log/apache2/noosfero.log LogLevel warn CustomLog /var/log/apache2/noosfero.access.log combined Include /var/lib/noosfero/current/etc/noosfero/apache/cache.conf </VirtualHost> <Proxy balancer://noosfero> BalancerMember http://127.0.0.1:3000 BalancerMember http://127.0.0.1:3001 Order Allow,Deny Allow from All </Proxy> The cache.conf file included in the end of the <VirtualHost> 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 Configuration - noosfero at a /subdirectory ------------------------------------------- This section describes how to configure noosfero at a subdirectory, what is specially useful when you want Noosfero to share a domain name with other applications. For example you can host noosfero at yourdomain.com/social, a webmail application at yourdomain.com/webmail, and have a static HTML website at yourdomain.com/. **NOTE:** Some plugins might not work well with this setting. Before deploying this setting, make sure you test that everything you need works properly with it. The configuration is similar to the main configuration instructions, except for the following points. In the description below, replace '/subdirectory' with the actual subdirectory you want. 1) add a `prefix: /subdirectory` line to your thin configuration file (thin.yml). 1.1) remember to restart the noosfero application server whenever you make changes to that configuration file. # service noosfero restart 2) add a line saying `export RAILS_RELATIVE_URL_ROOT=/subdirectory` to /etc/default/noosfero (you can create it with just this line if it does not exist already). 3) You should add the following apache configuration to an existing virtual host (plus the `<Proxy balancer://noosfero>` section as displayed above): ``` Alias /subdirectory /path/to/noosfero/public <Directory "/path/to/noosfero/public"> Options FollowSymLinks AllowOverride None Order Allow,Deny Allow from all Include /path/to/noosfero/etc/noosfero/apache/cache.conf RewriteEngine On RewriteBase /subdirectory # Rewrite index to check for static index.html RewriteRule ^$ index.html [QSA] # Rewrite to check for Rails cached page RewriteRule ^([^.]+)$ $1.html [QSA] RewriteCond %{REQUEST_FILENAME} !-f RewriteRule ^(.*)$ http://localhost:3000%{REQUEST_URI} [P,QSA,L] </Directory> ``` 3.1) remember to reload the apache server whenever any apache configuration file changes. # sudo service apache2 reload Enabling exception notifications ================================ This is an optional step. You will need it only if you want to receive e-mail notifications when some exception occurs on Noosfero. First, install this version of the gem. Others versions may not be compatible with Noosfero: # gem install exception_notification -v 1.0.20090728 You can configure the e-mails that will receive the notifications. Change the file config/noosfero.yml as the following example, replacing the e-mails by real ones: production: exception_recipients: [admin@example.com, you@example.com] 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). Rotating logs ============= Noosfero provides an example logrotate configuation to rotate its logs. To use it, create a symbolic link in `/etc/logrotate.d/`: # cd /etc/logrotate.d/ # ln -s /var/lib/noosfero/current/etc/logrotate.d/noosfero Note that the provided file assumes Noosfero logging is being done in `/var/log/noosfero` (which is the case if you followed the instructions above correctly). If the logs are stored elsewhere, it's recommended that you copy the file over to `/etc/logrotate.d/` and modify it to point to your local log directly. Upgrading ========= If you followed the steps in this document and installed Noosfero from the git repository, then upgrading is easy. First, you need to allow the noosfero user to restart the memcached server with sudo, by adding the following line in `/etc/sudoers`: noosfero ALL=NOPASSWD: /etc/init.d/memcached Then, to perform an upgrade, do the following as the noosfero user: $ 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 |