Skip to content

Commit

Permalink
Updated DEBIAN_HOW_TO.TXT to github flavoured markdown
Browse files Browse the repository at this point in the history
  • Loading branch information
@dhruvbird
dhruvbird committed Jun 5, 2012
1 parent 3049704 commit 0d24c0b
Showing 1 changed file with 51 additions and 106 deletions.
157 changes: 51 additions & 106 deletions DEBIAN_HOW_TO.TXT
View file
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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.

Expand Down

0 comments on commit 0d24c0b

Please sign in to comment.