Though Hanji has a lot of dependencies, we are trying to keep the installation simple and skip with one of Python’s moto: batteries included.
Note
These instructions are for Unix-like systems. Windows users are on their own for the time being.
As prerequisites, Python and pip should be installed on your system. See Python below.
In few words, getting a running Hanji is as simple as: First, dowload the Hanji source. Next, install the python requirements. Finally, install and build dojo.
Attention
Do not name the base directory (as defined with the HANJI_DIR shell variable below) as simply ‘hanji’: this would create ambiguities in python imports and generate bad headaches.
All together, you can copy the block of commands below and paste it in a terminal (the first 2 lines being just temporary shell variables):
HANJI_DIR=hanji_directory
DEV_PACKAGE_URL=http://hg.hanji.info/archive/tip.tar.gz
curl $DEV_PACKAGE_URL -o $HANJI_DIR.tar.gz || wget $DEV_PACKAGE_URL -O $HANJI_DIR.tar.gz
tar zxvf $HANJI_DIR.tar.gz
cd $HANJI_DIR
./setup.py get_dojo_custom
sudo pip install -r requirements.txt
If an error occurs, check the terminal output and refer to Detailed installation.
You can now start Hanji from this development installation: Start Hanji from a development environment.
To install Hanji as system-wide application (using a standard location given by the Python installation), simply run:
sudo pip install $HANJI_DIR
Under the hood: this installs a twisted plugin (copying twisted/plugins/hanji_plugin.py to the standard twisted plugins directory), creates a bunch of directories, runs scripts related to applets and optimization, and installs Hanji as a Python module.
Then refer to Start the Hanji application for starting this system-wide installation.
Note
Hanji won’t work yet with Python 3.x, due to the multiple dependencies on Python 2.x.
Check that setuptools is installed on your system: the easy_install command should be available in the command line.
If easy_install is not present, install setuptools from this link.
We highly recommend using pip, a cool tool for installing Python stuff, cleaner than the old setuptools’s easy_install. Still, for installing pip:
sudo easy_install pip
Instead of getting a simple tarfile, you can clone the Mercurial repository:
HG_SOURCE=http://hg.hanji.info/
hg clone $HG_SOURCE $HANJI_DIR
Later on, update Hanji to the latest development version with:
hg pull -u
Before installing ou need to install the development environment (all as root):
echo "deb http://repository.maemo.org fremantle/sdk free non-free" > /etc/apt/sources.list.d/maemo-dev.list
apt-get update
apt-get install build-essential
apt-get install python-dev
apt-get install python-imaging
The /tmp filesystem is too small by default for building any non native Python package (that requires compiling of libraries, like Twisted or PIL). If you see this error message: No space left on device, this simple command will extend the /tmp:
mount -t tmpfs tmpfs /tmp -o remount,size=64M
Next you can proceed with the installation instructions.
You can get all prerequisites in a single directory: $HANJI_DIR/requirements. Then, install them with:
pip install -r $HANJI_DIR/requirements.txt --no-index --find-links=file://$(pwd)/$HANJI_DIR/requirements
pip install $HANJI_DIR
Using virtualenv, you can work in a specific environment with its own python modules.
Snippet:
MY_ENV=test_environment
virtualenv $HANJI_DIR # or virtualenv --no-site-packages $MY_ENV for a blank environment
source $MY_ENV/bin/activate
Then proceed to Quick setup.
The setup.py file provides all commands for installing and maintaining a Hanji installation. Alternatively, for Unix users, a Makefile is also provided, but will be depreciated in future release.
setup.py --help-commands gives more commands for fine-tuning the Hanji installation.
The following are often included in standard installations.
- sqlite: very simple database, Python has bindings for it by default
Dojo is the default javascript toolkit for Hanji, providing a rich, browser independent user interface.
Dojo is split across hundreds of well documented files, making easy for developers to work with, at the cost of performance, response time and network use. Hopefully, Dojo comes also with a build mechanism.
For Hanji, there are 2 options:
- Build it yourself - for javascript developers
- Get a Dojo source package and build it: ./setup.py build_dojo_custom
- Get a standard build
- ./setup.py get_dojo_custom - by default it will get the latest build from hanji.info and unpack it.
See also the --help option on both commands.
The Dojo build has 2 versions, with or without cross-domain definitions. When a portal is used, the static pages are served by directly (speeding up network access), which requires a cross-domain Dojo build.
Additionally, some useful developer’s tools:
Mercurial (a DCVS written mainly in Python). If you have pip installed, just type: sudo pip install mercurial.
For generating the documentation, sphinx. Again, sudo pip install sphinx.
Hanji is a flexible framework, the instructions above are for a basic setup suitable for personal use and low traffic: Twisted as web frontend, and a simple sqlite database. This is the default setup and does not require additional effort.
Note
This might change in the future with final versions of WebSocket.
Request hanling used in the Hanji demo site:
twisd static
(http:8899) files
\ /
\ /
twistd nginx
(ws:8899) (http:8000)
\ /
\ /
\ /
haproxy
(*:80)
In summary: the haproxy frontend is used as a multiplexer. Websockets are sent directly to the Hanji Twisted server, while the traditional http requests are sent to a second layer of backend (nginx). In turn, Nginx serves the static files like images and javascripts, adding gzip compression and expiring headers for browser side chache. The non static requests are sent to the Hanji Twisted port.
Finally, the twistd and nginx ports can be filtered from external access with a port-based firewall like iptables.
Copy and adapt this haproxy configuration file (used in the demo.hanji.info site):
global
log 127.0.0.1 local0
log 127.0.0.1 local1 notice
daemon
maxconn 256
user haproxy
group haproxy
defaults
retries 3
maxconn 2000
contimeout 5000
clitimeout 50000
srvtimeout 50000
mode http
timeout client 86400000
#option http-server-close
#option keepalive
frontend http_in
bind *:80
default_backend nginx
option nolinger
acl WEBSOCKET hdr(Upgrade) -i WebSocket
acl WEBSOCKET hdr_beg(Host) -i ws
acl DEMO_WEBSOCKET hdr(Host) demo.hanji.info
acl DEMO hdr(Host) demo.hanji.info
use_backend twisted_8899 if WEBSOCKET DEMO_WEBSOCKET
use_backend nginx_8000 if DEMO
backend nginx_8000
server server1 127.0.0.1:8000 check
backend twisted_8899
server server1001 127.0.0.2:8899 check
Copy and adapt this nginx configuration file (used in the demo.hanji.info site):
server {
listen 8000;
server_name demo.hanji.info;
gzip on;
gzip_http_version 1.0;
gzip_comp_level 9;
gzip_proxied any;
gzip_min_length 1100;
gzip_buffers 16 8k;
gzip_types text/plain text/css application/json application/x-javascript text/xml application/xml application/xml+rss text/javascript application/javascript;
gzip_vary on;
gzip_static on;
gzip_disable "MSIE [1-6].(?!.*SV1)";
expires modified +60d;
location / {
expires epoch;
proxy_pass http://127.0.0.5:8899/ ;
proxy_set_header Host $host;
access_log /var/log/nginx/demo.hanji.info.access.log;
}
location /favicon.ico {
alias /usr/local/lib/python2.6/dist-packages/hanji/static/favicon.png;
}
location /dojo {
root /usr/local/lib/python2.6/dist-packages/hanji/dojo-custom-build;
}
location /static/dojo {
alias /usr/local/lib/python2.6/dist-packages/hanji/dojo-custom-build/dojo;
}
location /static {
root /usr/local/lib/python2.6/dist-packages/hanji;
}
location ~ /static/applet/([^/]+?)/(.*)$ {
alias /usr/local/lib/python2.6/dist-packages/hanji/applets/$1/static/$2;
}
}
For http://demo.hanji.info/, Hanji is launched with the following command (note the setup for subdomain name management for the portal applet):
/usr/local/bin/twistd --pidfile=/var/run/hanji.pid --logfile=/var/log/hanji.log hanji --port=8899 --no-mdns --dns-domain=hanjinet.org --dns-subdomain= --front-end-address=demo.hanji.info