MaxWiki Install

Here are detailed instruction on installing MaxWiki and its supporting environment on Linux. Even though the samples below are for RedHat, they should also work on most other Linux distributions with a little tweaking. For Windows and Mac, follow the alternate instructions for setting up Ruby/Gems/Rails then continue with the MySQL section.

Ruby

  1. Download and install Ruby 1.8.6

(From: RubyOnRails Download)

Gems

  1. Download RubyGems
  2. Extract then run: ruby setup.rb

(From: RubyOnRails Download)

Rails

  1. Run: gem install rails --include-dependencies

(From: RubyOnRails Download)

MySQL

  1. Install MySQL5
  2. Create database and user and assign rights:
    mysql -u root -p
      create database maxwiki;
      create database maxwiki_test;
      grant all on maxwiki.* to rails@localhost identified by 'password';
      grant all on maxwiki_test.* to rails@localhost;

Install MaxWiki

  1. Create and goto MaxWiki directory: /usr/local/rails/maxwiki
  2. Checkout from svn:
    svn checkout svn://rubyforge.org/var/svn/maxwiki/trunk     .
  3. For enterprise customers, get the additional plugins (username and password needed):
    cd /usr/local/rails/maxwiki/vendor/plugins
     svn checkout http://svn.maxwiki.com/svn/maxwiki_ent/plugins/maxwiki_multihost
    svn checkout http://svn.maxwiki.com/svn/maxwiki_ent/plugins/maxwiki_convert
    svn checkout http://svn.maxwiki.com/svn/maxwiki_ent/plugins/maxwiki_webdav
    svn checkout http://svn.maxwiki.com/svn/maxwiki_ent/plugins/maxwiki_webdav_auth
  4. Also for enterprise customers, get the files for your site (username and password needed):
    cd /usr/local/rails/maxwiki/public/files
    svn checkout http://svn.maxwiki.com/svn/maxwiki_ent/files/your_site_name

Rails User

  1. Create group: groupadd rails
  2. Create user:
    useradd -c “Rails Server” -g rails rails
    passwd rails
  3. Change owner of rails files: chown -R rails:rails /usr/local/rails

Setup MaxWiki

For the following files, copy the file to a new file without the .template extension, then customize. For instance, copy database.yml.template to database.yml.

  • config/database.yml
  • config/local_environment.rb

local_environment.rb

If you are running the Enterprise multi-host, change the top of this file to something like:

MY_CONFIG[:host_map] = [
   {:host => 'www.maxwiki.com', :name => 'maxwiki'},   
   {:host => 'maxwiki.com', :redirect_to => 'www.maxwiki.com'},   
]

Database Setup

  1. To setup the database tables run: rake db:migrate

Install Mongrel

  1. Install Mongrel: gem install mongrel mongrel_cluster --include-dependencies

Test

At this point, it is a good idea to test MaxWiki with Mongrel (and no Apache).

  1. Start Mongrel with: mongrel_rails start
  2. Access your server at port 3000. For instance, if installing locally use: http://localhost:3000
  3. Fill in the MaxWiki setup screen fields and save.

If you are setting up a development system, you can stop here. The following sections are for production servers.

Single Mongrel

For many installations, a singe mongrel instance under Apache will work fine (and is much easier to configure). Follow the instructions below, but change the RewriteRule line to:

  RewriteRule .* http://127.0.0.1:8000%{REQUEST_URI} [L,P,QSA]

And start Mongrel with:

  mongrel_rails start -d -p 8000 -e production -P /full/path/to/log/mongrel-1.pid

(From: Apache Best Practice Deployment)

Mongrel Cluster

For installations where it will be getting many simultaneous hits, setting up a mongrel cluster is required for best performance.

  1. In Rails home: /usr/local/rails/maxwiki
  2. Add file: conf/mongrel_cluster.yml
    ---
    cwd: /usr/local/rails/maxwiki
    port: "8000"
    environment: production
    address: 127.0.0.1
    pid_file: log/mongrel.pid
    servers: 3
    user: rails
    group: rails
  3. Add Mongrel as a system service:

    cd /etc/init.d
    sudo ln -s /usr/local/lib/ruby/gems/1.8/gems/mongrel_cluster-0.2.1/resources/mongrel_cluster mongrel_cluster
    sudo chmod +x mongrel_cluster
    sudo /sbin/chkconfig --level 345 mongrel_cluster on
    sudo mkdir /etc/mongrel_cluster
    sudo ln -s /usr/local/rails/maxwiki/config/mongrel_cluster.yml /etc/mongrel_cluster/maxwiki.yml

(From: Time For A Grown Up Server)

Apache mod_proxy

We need to add mod_proxy support to Apache 2.2 since the default doesn't include it.

  1. Download and expand Apache proxy module source:
    cd /usr/local/src
    wget http://apache.mirror.positive-internet.com/httpd/httpd-2.2.3.tar.gz
    tar –xzvf httpd-2.2.3.tar.gz
  2. Add proxy modules to apache:
    /usr/local/apache2/bin/apxs -i -a -c mod_proxy.c proxy_util.c
    /usr/local/apache2/bin/apxs -i -a -c mod_proxy_balancer.c
    /usr/local/apache2/bin/apxs -i -a -c mod_proxy_http.c

(From: Apache 2.2 + mod_proxy_balancer)

Apache Virtual Server

  1. Change to Apache directory: cd /usr/local/apache2
  2. At bottom of: conf/httpd.conf
    NameVirtualHost *:80
    NameVirtualHost *:443
    Include conf.d/*.conf 
  3. Create file: conf.d/1_maxwiki.conf
    <VirtualHost *:80>
      # This should remain the first virtual host because it will service all hosts
      # that are not explicitly defined in other VirtualHost sections
      # Also, we don't need to define any ServerName or ServerAlias
      DocumentRoot /usr/local/rails/maxwiki/public
      <Directory "/usr/local/rails/maxwiki/public">
        Options FollowSymLinks
        AllowOverride None
        Order allow,deny
        Allow from all
      </Directory>

      # this not only blocks access to .svn directories, but makes it appear
      # as though they aren't even there, not just that they are forbidden
      <DirectoryMatch "^/.*/\.svn/">
        ErrorDocument 403 /404.html
        Order allow,deny
        Deny from all
        Satisfy All
      </DirectoryMatch>

      # Rewrite to check for Rails cached page
      # Also for caching, take out :80 if present, and change : to _
      RewriteEngine On
      RewriteRule ^/$ /cache/%{HTTP_HOST}/index.html [QSA]  
      RewriteRule ^/([^.]+)$ /cache/%{HTTP_HOST}/$1.html [QSA]
      RewriteRule ^(.*):80(.*)$ $1$2 [QSA]
      RewriteRule ^(.*):(.*)$ $1_$2 [QSA]

      # Redirect all non-static requests to cluster
      RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-f
      RewriteRule ^(.*)$ balancer://mongrel_cluster_maxwiki%{REQUEST_URI} [P,QSA,L]
    </VirtualHost>

    <Proxy balancer://mongrel_cluster_maxwiki>
      BalancerMember http://127.0.0.1:8000
      BalancerMember http://127.0.0.1:8001
      BalancerMember http://127.0.0.1:8002
    </Proxy>
  4. Restart http:
    • Check syntax: bin/apachectl -t
    • Restart: bin/apachectl restart

Update Instructions

  1. Update the main MaxWiki files. In the MaxWiki Rails root directory: 
    svn update
  2. Update the site specific files (if you have Multi-Host). In /RAILS_ROOT/public/files/mysite directory:
    svn update
  3. Update the database: Back in the MaxWiki Rail root directory:
    rake db:migrate
  4. Restart Mongrel:
    mongrel_cluster_ctl restart

Update Test Instructions

It is always a good idea to test the update first. Here is a general outline of one method to do this.

  1. Create a test directory and checkout the code to it
  2. Copy over the public/cache, public/files and any other custom files in public
  3. Make sure that these directories have owner rails:rails - log, storage, public/cache, public/files/attachments
  4. Create a test database and update config/database.yml to point to it
  5. Use SQL commands to export the current database and then import into the test database
  6. Use rake db:migrate to update the database
  7. Modify config/mongrel_cluster.yml to add some new mongrels
  8. Add a new Apache .conf file to point a test domain to the test directory
  9. Restart Apache and startup the new mongrel
  10. Test the new installation

Once the testing is done, it is possible to use this as the updated site. The advantage of this is that the site will be down for less time since the data has already been upgraded and there is less of a chance that something will go wrong.

  1. Check to see if any pages have changed on the current site. If so, copy them over
  2. Check if any new files uploaded in public/files/attachments and copy them over
  3. Turn off mongrel_cluster
  4. Rename the current directory to _old
  5. Rename the test directory to the current name
  6. Take out the test Apache .conf file
  7. Restart Apache
  8. Restart mongrel_cluster
Revised on December 4, 2008 12:52:59 by Max Dunn (69.226.228.52)