Browse files

Updated DEBIAN_HOW_TO.TXT to github flavoured markdown

  • Loading branch information...
1 parent 3049704 commit 0d24c0bb4cdc351e90fb9fa266f870df0cdf94df @dhruvbird committed Jun 5, 2012
Showing with 51 additions and 106 deletions.
  1. +51 −106 DEBIAN_HOW_TO.TXT
View
157 DEBIAN_HOW_TO.TXT
@@ -1,163 +1,108 @@
-#summary A step-by-step help to install and configure node-xmpp-bosh on a Debian system.
+# A step-by-step help to install and configure node-xmpp-bosh on a Debian system.
-= Introduction =
+## Introduction
node-xmpp-bosh installation can be really hard without knowledge of the UNIX shell and associated commands. In this help section, we shall provide instructions for a step-by-step installation of node-xmpp-bosh on Debian and Debian-based systems, like Ubuntu.
-= node.js installation =
+## node.js installation
-node.js installation is pretty slow, because it involves compiling it. On some Debian systems, the _nodejs_ package is available in the official repository, so that you can switch this step.
+node.js is generally installed by compiling it from source. If you are unsure how to do this and would prefer installing the binaries, you can get hold of a Debian based system which has the _nodejs_ package in the official repository. If you install pre-compiled binaries, you can skip the step of compiling node.js.
-Firstly, we install the dependencies:
+First, we install the dependencies:
-`apt-get install libssl-dev python subversion git git-core libexpat1 libexpat1-dev`
+```apt-get install libssl-dev python subversion git git-core libexpat1 libexpat1-dev```
-Then, we get nodejs v0.4.7 (node-xmpp-bosh does not work with the newer versions of node.js since the TLS API from v0.4.8 has been changed):
+Then, we install the latest node.js from source
-`wget http://nodejs.org/dist/node-v0.4.7.tar.gz`
+```wget http://nodejs.org/dist/v0.6.19/node-v0.6.19.tar.gz```
-`tar -zxvf node-v0.4.7.tar.gz`
+```tar -zxvf node-v0.6.19.tar.gz```
-`cd ./node-v0.4.7`
+```cd ./node-v0.6.19```
-Finally, we launch the compilation (can take some minutes):
+Finally, we start compiling node.js (this can take a few minutes):
`./configure --prefix=/usr; make; make install`
-Note: configure may tell you to install some missing packages if the required compilation tools are not present on the system.
+Note: configure may ask you to install some missing packages if the required compilation tools are not present on the system.
-= Installation of External Modules =
+## Installation of External Modules
-node-xmpp-bosh depends on external node.js modules. These module dependencies may change with future node-xmpp-bosh versions, so that you will need to manually update them by checking the "dependencies" section in the "package.json" file of the version that you are using.
+node-xmpp-bosh depends on external node.js modules. For simplicity, we let [npm](http://npmjs.org/) manage these dependencies. See [INSTALL.md](https://github.com/dhruvbird/node-xmpp-bosh/blob/master/INSTALL.md) for details on how to install npm and node-xmpp-bosh using npm.
-Alternatively, you may completely leave the dependency bits to [http://npmjs.org/ npm] and follow the installation instructions in INSTALL.TXT
+**Either ways, npm needs to be installed.**
-First, we create the required folders:
+Alternatively, we can fetch just node-xmpp-bosh from github and let npm install the dependencies.
-`mkdir /usr/local/lib/node`
+## node-xmpp-bosh installation
-`mkdir /usr/local/lib/node/.libs`
-
-Then, we get the external modules:
-
-`cd ./.libs`
-
-`git clone git://github.com/astro/node-expat.git`
-
-`git clone git://github.com/astro/ltx.git`
-
-`git clone git://github.com/broofa/node-uuid.git`
-
-`git clone git://github.com/akaspin/tav.git`
-
-`git clone git://github.com/documentcloud/underscore.git`
-
-`git clone git://github.com/dhruvbird/eventpipe.git`
-
-`git clone git://github.com/dhruvbird/dns-srv.git`
-
-Then, we build the node-expat library:
-
-`./node-expat/configure`
-
-Finally, we create symbolic links:
-
-`cd ../`
-
-`ln -s ./.libs/node-expat/build/default/node-expat.node ./node-expat.node`
-
-`ln -s ./.libs/ltx/lib ./ltx`
-
-`ln -s ./.libs/node-uuid/uuid.js ./node-uuid.js`
-
-`ln -s ./.libs/tav/index.js ./tav.js`
-
-`ln -s ./.libs/underscore/underscore.js ./underscore.js`
-
-`ln -s ./.libs/eventpipe/eventpipe.js ./eventpipe.js`
-
-`ln -s ./.libs/dns-srv/srv.js ./dns-srv.js`
-
-You can update the external modules from their development repositories using this script (put it in an executable file):
-
-{{{
-#!/usr/bin/env zsh
-
-cd /usr/local/lib/node/.libs
-
-for i in *(/)
-do
- cd "$i"
- git pull -a
- cd ../
-done
-}}}
+Once node.js and node-xmpp-bosh dependencies are installed, we can install node-xmpp-bosh itself and change its configuration.
-Don't forget to build node-expat again if anything was updated.
+## node-xmpp-bosh itself (from GIT)
-= node-xmpp-bosh installation =
+Get the latest node-xmpp-bosh version from [here](https://github.com/dhruvbird/node-xmpp-bosh/tags), or get the master branch from (github)[https://github.com/dhruvbird/node-xmpp-bosh].
-Once node.js and node-xmpp-bosh dependencies are installed, we can install node-xmpp-bosh itself and change its configuration.
+```cd /usr/local/lib/bosh```
-== node-xmpp-bosh itself (from SVN) ==
+```git clone git://github.com/dhruvbird/node-xmpp-bosh.git```
-Get the last node-xmpp-bosh version on the downloads page, or get its trunk using Subversion (recommended):
+Now, we use npm to automatically fetch the dependencies for us.
-`svn checkout http://node-xmpp-bosh.googlecode.com/svn/trunk/ /usr/local/lib/bosh`
+```npm install .```
-The use of SVN offers you the possibility to update node-xmpp-bosh quickly to the last development version using the following commands:
+Using GIT allows you to update node-xmpp-bosh quickly to the last development version using the following commands:
-`cd /usr/local/lib/bosh`
+```cd /usr/local/lib/bosh```
-`svn up`
+```git pull```
After an update, you will need to restart node-xmpp-bosh using the init.d command (see after).
-== node-xmpp-bosh configuration ==
+## node-xmpp-bosh configuration
Copy the node-xmpp-bosh sample configuration file in a new file:
-`cp /usr/local/lib/bosh/bosh.conf.example.js /etc/bosh.js.conf`
+```cp /usr/local/lib/bosh/bosh.conf.example.js /etc/bosh.js.conf```
-Then, open it and start configuring it to meet your needs!
+Then, open it and configure it to meet your needs!
-A little warn about the logging feature: if your BOSH server will receive a huge amount of data, please consider setting the _logging_ option to _FATAL_ to avoid getting your disk system full quickly.
+A little warning about the logging feature: if your BOSH server will receive a huge amount of data, please consider setting the _logging_ option to _FATAL_ to avoid getting your disk system full quickly.
-== node-xmpp-bosh logs ==
+## node-xmpp-bosh logs
To be able to report the crash logs to the node-xmpp-bosh issue tracker, you have to create the logging folder and the logging files:
-`mkdir /var/log/bosh`
+```mkdir /var/log/bosh```
Then, the two logging files:
-`touch /var/log/bosh.log /var/log/bosh.err`
+```touch /var/log/bosh.log /var/log/bosh.err```
Finally, apply permissive rights to the whole:
-`chmod 777 -R /var/log/bosh`
+```chmod 777 -R /var/log/bosh```
-= Startup scripts installation =
+## Startup scripts installation =
Some startup scripts may be useful to make the node-xmpp-bosh process management faster.
-== init.d script ==
+### init.d script
node-xmpp-bosh will not be launched on system startup once installed, that's why you'd better use the following init.d script. Firstly, create the file:
-`touch /etc/init.d/bosh`
+```touch /etc/init.d/bosh```
Then, apply permissive rights:
-`chmod 777 /etc/init.d/bosh`
+```chmod 777 /etc/init.d/bosh```
Open the file:
-`nano /etc/init.d/bosh`
+```nano /etc/init.d/bosh```
Paste the following content:
-{{{
+```
#! /bin/sh
#
# bosh Start/stop node-xmpp-bosh server
@@ -222,46 +167,46 @@ else
fi
exit 0
-}}}
+```
Save it (CTRL+O using nano).
Then, you have to create the related command script:
-`touch /usr/local/bin/bosh`
+```touch /usr/local/bin/bosh```
Then, apply permissive rights:
-`chmod 777 /usr/local/bin/bosh`
+```chmod 777 /usr/local/bin/bosh```
Open the file:
-`nano /usr/local/bin/bosh`
+```nano /usr/local/bin/bosh```
Paste the following content:
-{{{
+```
#!/usr/bin/env sh
exec /usr/local/lib/bosh/run-server.js "$@" >> /var/log/bosh/bosh.log 2>> /var/log/bosh/bosh.err &
-}}}
+```
Save it (CTRL+O using nano).
Once done, you will be able to start, stop or restart node-xmpp-bosh using this command:
-`/etc/init.d/bosh {start|stop|restart}`
+```/etc/init.d/bosh {start|stop|restart}```
-== cronjob ==
+## cronjob
To avoid any downtime of your BOSH service, you may want to use a cronjob to start node-xmpp-bosh if not started (the check is proceeded every minute).
First, execute this:
-`crontab -e`
+```crontab -e```
Then, at the end of the file, paste this:
-`*/1 * * * * /etc/init.d/bosh start >>/dev/null`
+```*/1 * * * * /etc/init.d/bosh start >>/dev/null```
Save it (CTRL+O using nano), the cronjobs will be updated.

0 comments on commit 0d24c0b

Please sign in to comment.