README for the FFM web app

Authors

Christian Tanzer <tanzer@swing.co.at>

Ralf Schlatterbeck <rsc@runtux.com>

The FFM web app is an application that serves data about the network nodes deployed by www.funkfeuer.at.

Object model

This object model (in SVG format) is automagically rendered using graph.py, the result of the last run is kept under version control (so you can see our progress) in nodedb.svg.

Some notes on the object model: We try to keep only the relevant attributes of a real-world object in the object itself — everything else is modelled as a relation. The blue arrows denote inheritance relationships ("IS_A"). The yellow arrows are attributes, e.g., the Node has an attribute manager of type Person which is required (this is implemented as a foreign key in the database).

The black arrows are 1:N relationships (also implemented as foreign keys in the database) but the relation objects have their own identity. This is used to separate the attribute of an object from its links to other objects. It also implements referential integrity constraints: A link is deleted if the object to which it points is deleted.

There are different link attributes. A two-way link (implementing an N:M relationship) has a left and a right side which are also the default attribute names. An example is Wireless_Interface_uses_Wireless_Channel, in the diagram this link object is displayed as _uses_ between the FFM.Wireless_Channel and FFM.Wireless_Interface. The black arrows connecting these are labelled left and right which indicates how this should be read. Note that in this case the left attribute is on the right side in the diagram. A two-way link like this has an identity and can have additional attributes besides left and right.

There are also unary links with only a left side. An example is the Device which cannot exist without its left attribute, the Device_Type. There can be several devices with the same device type. This relationship is inherited by Antenna and Antenna_Type and Net_Device and Net_Device_Type.

System requirements

Linux or OS X
- its best to set up a separate account that runs FFM
Apache, with mod-fcgid installed
- or another webserver, e.g. nginx...
PostgreSQL (preferred) or mySQL
- an account for the web app that can create databases and tables
git
Python (> 2.6, < 3)
- virtualenv, distribute
- Depending on the OS (I'm looking at you, Debian), some packages, e.g., werkzeug, should be installed into virtualenv to get versions a bit younger than a couple of years
- This might require the installation of a build environment (for python packages that need the C compiler)
Python packages
- Babel
- BeautifulSoup
- python-dateutil
- docutils
- flup
- jinja2
- plumbum
- psycopg2 or the mysql package needed by sqlalchemy
- pyquery
- pytz
- passlib
- py-bcrypt
- rcssmin, rjsmin (for minimization of CSS and Javascript files)
- rsclib
- sqlalchemy
- werkzeug
- pyOpenSSL
- pyasn1
Most packages are available via the Python Package Index

Package Installation for Debian Stable aka Squeeze

The following is an example installation on Debian Wheezy. It contains some information that is applicable to other distributions but is quite Debian-specific in other parts.

If you are running in a virtual machine, you need at least 384 MB of RAM, 256 MB isn't enough.

Some of the needed Packages are either not in Debian or are too old to be useful. The following packages can be installed via the Debian installer:

apt-get install git libapache2-mod-fcgid postgresql python-pip \
    python-virtualenv python-distribute build-essential python-babel \
    python-bs4 python-dateutil python-docutils python-flup python-jinja2 \
    python-psycopg2 python-dev apache2-mpm-worker python-tz \
    python-sqlalchemy python-werkzeug python-passlib python-openssl \
    python-pyquery swig

Other packages can be installed using pip — note that you may want to install some of these into a virtual python environment (virtualenv), see later in sectioni How to install — depending on your estimate how often you want to change external packages:

pip install plumbum py-bcrypt rcssmin rjsmin rsclib pyasn1 pyspkac

Create user and database user permitted to create databases:

adduser ffm
createuser -d ffm -P

How to install

Assuming an account ffm located in /home/ffm, you'll need something like the following:

### Logged in as `ffm`
$ cd /home/ffm

### Define config
$ vi .ffm.config
  ### Add the lines (using the appropriate values for **your** install)::
    cookie_salt   = 'some random value, e.g., the result of uuid.uuid4 ()'
    db_name       = "ffm"
    db_url        = "postgresql://<account>:<password>@localhost"
    languages     = "de", "en"
    locale_code   = "de"
    smtp_server   = "localhost"
    target_db_url = db_url
    time_zone     = "Mars/Olympos Mons"

### create a virtual environment for Python
$ mkdir bin
$ mkdir PVE
$ python -m virtualenv --system-site-packages PVE/std
$ (cd PVE ; ln -s std active)

Depending on the packages you have already installed system-wide, you may want to install some packages into the virtual environment if you anticipate that these will change:

### install Python packages into the virtualenv
### if one of these packages is already installed in the system
### Python, you'll need to say `pip install --upgrade`, not `pip install`
$ source PVE/active/bin/activate
$ pip install Babel plumbum pytz werkzeug

Then we continue with the setup of an active and a passive branch of the web application. With this you can upgrade the passive application while the active application is running without risking a non-functional system should something go wrong during the upgrade:

### create a directory with an `active` and `passive` branch of the
### web application
###
### * the active branch will be the one that serves apache requests
###
### * the passive branch can be used for updating the software and
###   testing it. It all works will the branches can be switched
###

$ mkdir fcgi
$ mkdir v
$ mkdir v/1
$ mkdir v/1/www
$ mkdir v/1/www/media
$ ln -s v/1 active
$ ln -s v/2 passive
$ git clone git://github.com/Tapyr/tapyr.git v/1/lib
$ git clone git://github.com/FFM/FFM.git     v/1/www/app
$ cp -a v/1 v/2

$ vi active/www/.ffm.config
  ### Add the lines (using the appropriate values for **your** install)::
    db_name       = "ffm1"
$ vi passive/www/.ffm.config
    db_name       = "ffm2"

### Define PYTHONPATH
$ export PYTHONPATH=/home/ffm/active/lib

### Create a fcgi script for Apache
$ python active/www/app/deploy.py fcgi_script > fcgi/app_server.fcgi

Then we configure an Apache virtual host, for instance:

<VirtualHost *:80>
  ServerName   xxx.funkfeuer.at
  DocumentRoot /home/ffm/active/www

  AddDefaultCharset utf-8

  Alias /media/GTW/ /home/ffm/active/lib/_GTW/media/
  Alias /media/     /home/ffm/active/www/media/

  <Directory /home/ffm/active/lib/_GTW/media>
    Order deny,allow
    Allow from all
    ExpiresActive On
    ExpiresDefault "access plus 1 day"
    <FilesMatch "\.(gif|jpeg|jpg|png)$">
      ExpiresDefault "access plus 1 year"
    </FilesMatch>
    <FilesMatch "\.(css|js)$">
      ExpiresDefault "access plus 1 day"
    </FilesMatch>
  </Directory>

  <Directory /home/ffm/active/www/media>
    Order deny,allow
    Allow from all
    ExpiresActive On
    ExpiresDefault "access plus 1 day"
    <FilesMatch "\.(gif|jpeg|jpg|png)$">
      ExpiresDefault "access plus 1 year"
    </FilesMatch>
    <FilesMatch "\.(css|js)$">
      ExpiresDefault "access plus 1 day"
    </FilesMatch>
    FileETag None
  </Directory>

  <Directory /home/ffm/active/www/media/v>
    ExpiresActive On
    <FilesMatch "\.(css|js)$">
      ExpiresDefault "access plus 1 year"
    </FilesMatch>
  </Directory>

  <Directory /home/ffm/active/www/media/pdf>
    FileETag all
  </Directory>

  <Directory /home/ffm/active/www/app>
    Order deny,allow
    Deny from all
  </Directory>

  AddOutputFilterByType DEFLATE text/html text/plain text/css text/javascript

  AddHandler fcgid-script .fcgi
  Options +ExecCGI

  ScriptAliasMatch .* /home/ffm/fcgi/app_server.fcgi

  UseCanonicalName On
  <Directory /home/ffm/www>
    DirectoryIndex index.html
    Order allow,deny
    Allow from all
  </Directory>
</VirtualHost>

To configure Apache to always use https, use something like:

<VirtualHost *:80>
  ServerName   xxx.funkfeuer.at
  RewriteEngine On
  RewriteRule ^/(.*)$ https://xxx.funkfeuer.at/$1 [L,R]
  RewriteRule ^$ https://xxx.funkfeuer.at [L,R]
</VirtualHost>

<VirtualHost *:443>
  ServerName   xxx.funkfeuer.at
  DocumentRoot /home/ffm/active/www

  SSLEngine on
  SSLCertificateFile    /etc/ssl/certs/xxx.pem
  SSLCertificateKeyFile /etc/ssl/private/xxx.key
  SSLCipherSuite HIGH
  SSLProtocol all -SSLv2

  AddDefaultCharset utf-8
  ### as above for the http case
</VirtualHost>

For Debian the apache configuration should be placed into /etc/apache2/sites-available/, e.g., into the file nodedb2.example.com and enabled. You probably will have to disable the default site installed. We used the following commands — we also enable some needed modules:

a2ensite nodedb2.example.com
a2dissite default
a2enmod mod_expires
a2enmod fcgid
/etc/init.d/apache2 restart

For https sites, you'll also need the modules:

a2enmod rewrite
a2enmod ssl

Finally we create a database and populate it with data:

### Create a database
$ python active/www/app/deploy.py create

### Put some data into the database

Whenever we need to upgrade the installation, we can update the passive configuration, set up everything, migrate the data from the active to the passive configuration, and if everything went OK, enable it by exchanging the symbolic links to the active and passive configuration:

### Test deployment script and generate some needed files
  ### Update source code
  $ python passive/www/app/deploy.py update

  ### Byte compile python files
  $ python passive/www/app/deploy.py pycompile

  ### Compile translations
  $ python passive/www/app/deploy.py babel compile

  ### Migrate database from active to passive
  $ python passive/www/app/deploy.py migrate -A -P

  ### Setup app cache
  $ python passive/www/app/deploy.py setup_cache

### Switch active and passive branches
$ python passive/www/app/deploy.py switch

Contact

Christian Tanzer <tanzer@swing.co.at> and Ralf Schlatterbeck <rsc@runtux.com>

Name		Name	Last commit message	Last commit date
Latest commit History 515 Commits
-I18N		-I18N
_FFM		_FFM
doc		doc
history		history
html		html
olsr		olsr
spider		spider
.dirin		.dirin
.gitignore		.gitignore
AGPL_v3		AGPL_v3
Media_Parameters.py		Media_Parameters.py
README.rst		README.rst
RST_addons.py		RST_addons.py
_Base_Command_.py		_Base_Command_.py
babel.cfg		babel.cfg
babel.sh		babel.sh
convert_0xff.py		convert_0xff.py
convert_cnml.py		convert_cnml.py
convert_graz.py		convert_graz.py
deploy.py		deploy.py
doit.sh		doit.sh
fixtures.py		fixtures.py
makestats.py		makestats.py
model.py		model.py
rst_top.py		rst_top.py
update.sh		update.sh

IngoGaucho/FFM

Folders and files

Latest commit

History

Repository files navigation

README for the FFM web app

Object model

System requirements

Package Installation for Debian Stable aka Squeeze

How to install

Contact

About

Resources

Stars

Watchers

Forks