Skip to content
This repository has been archived by the owner on Feb 14, 2018. It is now read-only.

Hosting and Installation Guide

Jump to bottom
juliangall edited this page Feb 27, 2015 · 27 revisions

#Hosting and Installation Guide

Notice: These instructions are for hosting the ruby version of the federated wiki server. Current development is taking place in node.js hosted in a different repository and distributed through the node package manager, npm. To install it type:

npm install -g wiki

See npm for project details or Deploying a wiki for a quick hosted solution.

Hosting

If you are interested in hosting a Federated Wiki server farm, you will need to have a dedicated computer that is always connected to the internet. Your options are:

  1. Have a desktop that is always connected to the internet.
  2. Purchase access to a Virtual Cloud Server.
  3. Have access to a web server through your ISP, university, or Hosting Service.
  4. Use a PaaS (Platform as a Service).

Desktop

This option gives you the most control. The disadvantage is that you probably are stuck with using an ISP like Comcast that restricts your upstream bandwidth to around 3-5MBPS. This is fine for a small scale web server, but it will not be enough for serious traffic. If you have a fiber optic connection, you should be fine with this option.

If you are connected through a router, you must go into the settings and open the port in which you intend on running your web server.

Virtual Private Cloud Server

With this option, you will have your own virtual machine instance running on a server in a data center. The advantage here is that you will have root access to your server, your internet connection will be fast, and you will not have to worry about your server being on all the time. There are several disadvantages. Firstly, if you want to pay a low price, you do not get much disk space or RAM. This shouldn't matter much at this point for hosting a Federated Wiki server farm. Also, there is a good chance you will have problems with your server, and it may unexpectedly go down. I am using Rackspace, and this happens relatively often. You will then be dependent on your service's tech support to resolve your problem.

Service Providers:

Server Access through ISP, University, Hosting Service

The main disadvantage here is that you probably will not have root access to the machine. You can still make this work by compiling NodeJS from source and running the server in user space. You get the same functionality, except you will not be able to run the server on port 80, since that requires root access. See the "From Source with No Root Privilege" section for more details.

Use a PaaS (Platform as a Service)

Like this Virtual Cloud Server option, you will have to subscribe to a hosting service provider. You will not have root access, but you will not need it. You will simply upload the Node or Sinatra project to their servers. They will then handle the details of administration and deployment.

Service Providers:

Requirements

This installation guide applies to Linux/Unix machines. It has been tested on Debian GNU/Linux 6.0.3 (Squeeze), Ubuntu 11.10 (Oneiric Ocelot) and Mac OS X 10.6 (Snow Leopard). If you have installed a server farm on a different system, contributions to this guide are welcome.

First, you must have installed Git. This may be downloaded at git-scm.com. If you are using Debian/Ubuntu, type:

sudo apt-get install git

Using NodeJS (Express)

Though NodeJS is not the reference implementation of the Federated Wiki server, it is the easiest method to get a production-ready Federated Wiki server farm. You will simply need to install NodeJS and pull the dependencies for the project. When using NodeJS, your Smallest Federated Wiki application is the actual web server, so Apache is not needed.

Using apt-get (Linux)

If you are using Debian, you will need to add the sid package repository.

root@host: ~ # echo deb http://ftp.us.debian.org/debian/ sid main > /etc/apt/sources.list.d/sid.list
root@host: ~ # apt-get update
root@host: ~ # apt-get install nodejs

If you are using Ubuntu, the oneiric universe repository must be included in your aptitude sources list. This will usually already be done for you.

Edit this file:

/etc/apt/sources.list

Add:

deb http://us.archive.ubuntu.com/ubuntu/ oneiric universe
deb-src http://us.archive.ubuntu.com/ubuntu/ oneiric universe
deb http://us.archive.ubuntu.com/ubuntu/ oneiric-updates universe
deb-src http://us.archive.ubuntu.com/ubuntu/ oneiric-updates universe

Then update:

sudo apt-get update

Run Install:

sudo apt-get install nodejs

Clone the Github repository (cd into any directory of your choice):

git clone https://github.com/WardCunningham/Smallest-Federated-Wiki.git

Install the required NodeJS package dependencies:

cd Smallest-Federated-Wiki/server/express
npm install

Now you are ready to run the server. We will be using screen so that the server remains active after you close your terminal window.

cd bin
screen node server.js

When you want to later see the log output of node or terminate your server process, you can get back to your old screen by typing:

screen -raAd

To terminate, type control-c.

From Source With No Root Privilege (Linux/Mac)

You will have to take this option if you do not have root access to your server or you are not using a PaaS. The functionality will be the same with this option, but you will not be able to run the server on port 80 without root access.

This is a fairly involved process, and I plan on providing a standalone .zip with everything you need so that you do not need to take these steps.

  1. cd into the directory in which you would like to install NodeJS.

  2. Clone the Github repository and install locally:

    git clone https://github.com/joyent/node.git cd node git checkout v0.6.7 ./configure make

  3. Do not run sudo make install. This will attempt to take what you just compiled and put it in system directories. You need root access for this. At this point, you can run node. It will just be the executable called "node" within the directory in which you checked out the repository.

  4. Clone The Smallest Federated Wiki Github repository.

    git clone https://github.com/WardCunningham/Smallest-Federated-Wiki.git

  5. Now you will need to get the project's dependencies. Since npm requires root access to be installed, you will have to get your dependencies (node_modules) on a machine that you DO have root access to. So, you will have to install node on that other machine, clone the wiki there, and then run npm install within the directory Smallest-Federated-Wiki/server/express. You then will need to copy the node_modules directory to the Smallest-Federated-Wiki project on the other machine.

  6. It should work now. To run your server, type:

    cd path/to/node screen ./node Smallest-Federated-Wiki/server/express/bin/server.js

  7. When you want to later see the log output of node or terminate your server process, you can get back to your old screen by typing:

    screen -raAd

  8. To terminate, type control-c.

Using Heroku (Sinatra)

Heroku is a platform as a service. You "git push" your code, and they run it. You can scale up more instances if you get heavy traffic, but the first instance is free. You have ruby console access, and can see logs, but have no shell access. This may seem strange at first, but with all this comes a lot of simplicity and scalability.

If you're new to heroku, check out http://www.heroku.com/ and https://devcenter.heroku.com/articles/quickstart -- or in short:

gem install heroku
heroku login

Create a directory for a local copy of the GitHub repository, cd to it and clone the repository from GitHub:

git clone https://github.com/WardCunningham/Smallest-Federated-Wiki.git

Then create the Heroku application:

heroku create sfw123   # sfw123 is the app name, choose anything you like

Heroku will tell you something like:

Creating sfw123... done, stack is cedar
https://sfw123.herokuapp.com/ | https://git.heroku.com/sfw123.git

Great, now you can:

git push heroku master

Heroku will identify the Sinatra app (from the presence of Gemfile), install your gems, deploy your app (running what it finds in Procfile), and remind you of its URL:

https://sfwjjg.herokuapp.com deployed to Heroku

Go visit this URL, you should have a SFW app running there.

But wait, there's more.
Heroku has an ephemeral filesystem -- meaning that on every deploy, your files will get reset to only what's in the git repo.
Not so good for a wiki that stores pages in the file system.

Fortunately, the Sinatra implementation of the Federated Wiki has an optional CouchStore for permanent storage instead of the file-system. The NodeJS implementation has not yet been updated in this way, see issue #241 to follow progress.

To store our data in Couch we can use a free CouchDB service. Heroku have discontinued their Cloudant add-on, so you'll need to use another provider such as Cloudant itself. Sign up on their web site, log in to your dashboard and create a database called sfw. N.B. This name is hard-coded into the SFW program so you can't use another name without modifying the code.

When you've created the database, click on it in the Dashboard and then click on the "API URL" link. You'll see something like this, which is where your database can be accessed:

https://ebenezerscrooge.cloudant.com/sfw/_all_docs

To tell your SFW instance to use the Cloudant service, set the following environment variables:

heroku config:set STORE_TYPE=CouchStore
heroku config:set COUCHDB_URL=xxx

The URL you need as xxx is:

https://ebenezerscrooge:mypassword@ebenezerscrooge.cloudant.com/

The user name and password need to be passed in the URL to authenticate the access. N.B. do not put the sfw database name in the URL because, as noted above, the program appends it.

Restart your app for good measure:

heroku restart

Go to your Heroku URL and you should see the wiki running with the Cloudant data store.

If you want to run in farm mode, set these too:

heroku config:set FARM_MODE=true
heroku config:set FARM_DOMAINS=fedwiki.mydomain.org

In this example, all subdomains *.fedwiki.mydomain.org will be served by your app. Of course you'll also have to point the DNS at Heroku -- remember you are on the Cedar stack when you look at these docs.

That's about it. One tip: when you're trying to push a branch, use

git push heroku HEAD:master --force

This will clobber whatever is on Heroku's master branch (which is what gets deployed) with the HEAD of your current branch.

Using WEBrick (Sinatra)

WEBrick is the easier option for setting up a Federated Wiki server farm, but note that this server was never really designed to be used in a production environment.

[TODO]

Using Apache/Passenger (Sinatra)

Apache is the de-facto standard of web http servers. Passenger is a popular Apache module for running Rack applications, including Sinatra. This is your most robust option for hosting a Sinatra based server farm.

(See Issue #228 regarding session stores in ec2.)

The instructions are for Ubuntu, tested on a brand new vanilla EC2 micro instance running 10.04 LTS.

Packages

sudo apt-get update
sudo apt-get upgrade
sudo apt-get install -y curl git-core build-essential zlib1g-dev libssl-dev libreadline5-dev apache2 apache2-prefork-dev exim4 libapr1-dev libaprutil1-dev libcurl4-openssl-dev

RVM

bash -s stable < <(curl -s https://raw.github.com/wayneeseguin/rvm/master/binscripts/rvm-installer)
. ~/.bash_login
rvm install 1.9.2 --default   # go get a coffee.  heck, get dinner.

Install SFW in a known location

cd /home/ubuntu     # if your home dir is something else, be sure to apply it throughout the steps below...
git clone https://github.com/WardCunningham/Smallest-Federated-Wiki.git sfw
cd sfw 
mkdir data/farm    
mv .htaccess .htaccess.disabled     # the current .htaccess caused no wiki content to render, and an error: "Error on /page/welcome-visitors/action:"
gem install bundler --no-rdoc --no-ri
bundle install --deployment --without=development:test

Passenger

gem install rack -v 1.3.5 --no-rdoc --no-ri         # you might want to check the SWF Gemfile
gem install sinatra -v 1.2.6 --no-rdoc --no-ri      # to make sure these are still the canonical versions...
gem install passenger --no-rdoc --no-ri

passenger-install-apache2-module      # follow the instructions, and pay attention to the output...

sudo su -   # become root

cat >> /etc/apache2/apache2.conf      # ...paste in the lines it tells you from the output above, something like these:
LoadModule passenger_module /home/ubuntu/.rvm/gems/ruby-1.9.2-p318/gems/passenger-3.0.11/ext/apache2/mod_passenger.so
PassengerRoot /home/ubuntu/.rvm/gems/ruby-1.9.2-p318/gems/passenger-3.0.11
PassengerRuby /home/ubuntu/.rvm/wrappers/ruby-1.9.2-p318/ruby
^D

Configure apache2

# still as root...

cd /etc/apache2/sites-available

cat > custom                    # replace "sfw.remixfreeip.org" in the config below with your domain or subdomain
<VirtualHost *:80>
  ServerName sfw.remixfreeip.org
  ServerAlias *.sfw.remixfreeip.org
  DocumentRoot /home/ubuntu/sfw/client
  PassengerAppRoot /home/ubuntu/sfw/server/sinatra
  <Directory /home/ubuntu/sfw/client>
     AllowOverride all
     Options -MultiViews
  </Directory>
  ErrorLog /var/log/apache2/error.log
  LogLevel warn
  CustomLog /var/log/apache2/access.log combined
</VirtualHost>
^D

a2ensite custom
a2enmod rewrite  # optional
/etc/init.d/apache2 restart

^D   # give up root superpowers, human again : /

Point the DNS for your domain at the server you have just configured. You should have SFW instances available at (in the example config above):

  • sfw.remixfreeip.org
  • any-subdomin.sfw.remixfreeip.org
  • multi.level.subdomins.work.too.sfw.remixfreeip.org

Serving Static Files with PHP

You should be able to host static json files on a server and have them pulled in via an SFW client from elsewhere.

However note a couple of constraints :

  1. Your files must be available through a URL of the form http://my.domain.tld/pageslug.json without an extraneous path before the pageslug.

  2. Note that although page files in your file-system have no ".json" extension, the SFW client will try to access them with one. You need to compensate for this.

I found I only had a simple PHP server which I could set up as the access to a static site. But I didn't want to host the page files in the same place. Here's my simple solution :

 <?php
   $url = "http://MY.DOMAIN.TLD/LONG/CONVOLUTED/PATH/TO/PAGES/DIRECTORY/";
   $path = $_SERVER["REQUEST_URI"];
   $word = substr($path,1);
   $word = str_replace(".json","",$word);

   $word = strtolower($word);
   if ($word != "") {
      $url .= $word;
   }
   $p = file_get_contents($url);
   echo $p;
?>

Hints

  1. You can store a favicon.png in the same directory as the PHP script and the SFW client should find it.

Installation on Windows

See https://github.com/WardCunningham/Smallest-Federated-Wiki/blob/master/Windows.md.

Clone this wiki locally