gramps/src/web/README

Setting up everything for gramps webapp grampsweb:

This example will allow you to create a Django Database, populate it
through a GRAMPS export plugin, and then access/edit the data via the
web.

There are two ways to run this example: using a SQL engine via a
webserver, or using a local SQL database. With either way, you'll be
able to access/edit the data over the web. The only difference is
whether GRAMPS and the webserver accesses the data locally or through
a server.

First, the easy way with a local sqlite database (steps 2 and 3 are
the same for both):

1/packages

sudo yum install subversion sqlite

2/DO STEP 2 BELOW

3/DO STEP 3 BELOW

4/Django settings

Go to the branches/geps/gep-013-server/webapp/grampsweb dir and edit
settings.py to reflect your setup:

$ cd webapp/grampsweb
$ gedit settings.py

and make sure to set to the correct values:

----------------------------------------------
DATABASE_ENGINE = 'sqlite3'   
# Set the DATABASE_NAME to a full name and path to database file
# This file will be created, so make sure it is in a readable/writeable place.
DATABASE_NAME = '/home/dblank/gramps/gep-013-server/webapp/grampsweb/gramps.sql'      
# See file for examples for these:
TIME_ZONE: your time zone
LANGUAGE_CODE: your code
# Full path:
TEMPLATE_DIRS = (
    "/home/dblank/gramps/gep-013-server/webapp/html/templates",
)
----------------------------------------------

5/Make database, and then run a webserver:

make clean
make
make run

6/Run the Django Export plugin in this version of GRAMPS:

(you may need to ./autogen.sh; make in top level of branch)

python ../../src/gramps.py

Open a family tree, and select in menu Family Tree the export
entry. Select Django export. (You used to have to give a filename;
that is fixed now.) The django installation is querried and the django
backend as given in the settings is used to write to.

NOTE: You must manually empty the tables or delete them and regenerate
for now if you reexport your data, as the export plugin expects an
empty database. If the database is not empty, duplication errors will
occur.

7/You can (after this plugin has finished running) go back to eg
pgadmin or the http://127.0.0.1:8000/admin to see that the objects
have been saved. You can edit them here, too.

See the following for more details, and for setting up a more
sophisticated database server.

----------------------------------------------

1/packages 

benny@antec:sudo apt-get install python-psycopg python-psycopg2 postgresql apache2 libapache2-mod-python subversion pgadmin3 pgadmin3-data

2/get the django code.and install it

See http://docs.djangoproject.com/en/dev/topics/install/


3/get webapp sourcecode

benny@antec:mkdir branches/geps;cd branches/geps
**** extract data here ***
svn co https://gramps.svn.sourceforge.net/svnroot/gramps/branches/geps/gep-013-server/ gep013-server

Now go to the gramps code, and set it up

cd gep013-server
./autogen.sh
make

4/set up PostgreSQL
Reset the password for the 'postgres' admin account for the server 

benny@antec:cd ~
benny@antec:sudo su postgres -c psql template1
template1=# ALTER USER postgres WITH PASSWORD 'password';
template1=# \q

Add a new user into postgresql: 

benny@antec:sudo su postgres -c createuser gramps
Enter name of role to add: gramps
Shall the new role be a superuser? (y/n) y

Now define the access rules for the database. The easiest is to give access to all databases via md5:

benny@antec:sudo kate /etc/postgresql/8.3/main/pg_hba.conf

and end of file should look like: 
# "local" is for Unix domain socket connections only
local   all         all                               md5
# IPv4 local connections:
host    all         all         127.0.0.1/32          md5
# IPv6 local connections:
host    all         all         ::1/128               md5

Restart the server:

benny@antec:~$ sudo /etc/init.d/postgresql-8.3 restart

5/Use pgAdmin3 to access the database server. 

benny@antec:pgadmin3

In the new server registration dialog, give a name for your server, and set:
Host: localhost
Maintenance DB: postgres
Username: postgres
Password: 'password'   ==> the password entered above in 4/

Do not store the password! Next click to connect (Menu Tools->Connect).

If all is well, postgresql is set up and you see your server running. The login roles should contain the user ´gramps` you created in 4/

First step is to make a database which gramps webapp can use, so right click on your server, and add a database:
name: db_gramps
owner: gramps
encoding: UTF-8

Next, go to the role 'gramps' and assign a password with which the user can 
access.

That's it, the tables will be created with django.


6/Django settings

Go to the webapp code and change your settings to reflect your setup.

benny@antec:cd webapp/grampsweb
benny@antec:kate settings.py

and make sure to set to the correct values:

DATABASE_USER: as given in 4/, standard is gramps
DATABASE_PASSWORD: the password for the user in the database grampsonrails will create
TIME_ZONE: your time zone
LANGUAGE_CODE: your code
TEMPLATE_DIRS = (
    "/yourfullpath/gep-013-server/webapp/html/templates",
)
....

See the Django site for more info when changing variables: 
http://docs.djangoproject.com/en/dev/topics/settings/#topics-settings

7/run your webserver

For production, you should use Apache. For testing locally, you can use the django webserver, which is available via the manage.py file in the webapp directory.
Note that we need GRAMPS libraries, so we give the GRAMPS path for inclusion in PYTHONPATH. For effective distribution, we will ship the required libraries of GRAMPS in the application grampsweb. For my case this is

benny@antec: PYTHONPATH=~/programs/gramps/branches/geps/gep013-server/src/ python manage.py runserver &

Try it in your webbrowser by going to:

http://127.0.0.1:8000/admin

8/Create tables and start the django application

benny@antec: python manage.py syncdb

Create the superuser for django at this moment if needed.

9/To see the SQL to create the tables, do:

PYTHONPATH=~/programs/gramps/branches/geps/gep013-server/src/ python manage.py sqlall grampsdb


10/Now that a beginning of the tables is present, we need to pump data into it. For now, we assume all tables are empty, and we add new data to it. If the tables are not empty, drop them first, eg via pgAdmin for postgresql. 
A new export plugin that can write to your django backend is written, ExportDjango. If your database exists, then you can just open a family tree, and select to export this to the django backend. At the moment only markertype and part of the person object are exported as a proof of concept.

11/You can after this plugin is finished go back to eg pgadmin or the http://127.0.0.1:8000/admin to see the objects have been saved.

References:
[1]  http://ianlawrence.info/random-stuff/set-up-django-apache-and-postgresql-on-ubuntu-feisty/
[2]  http://www.postgresql.org/docs/8.1/static/app-createuser.html
[3]  http://antoniocangiano.com/2007/12/26/installing-django-with-postgresql-on-ubuntu/
[4] http://www.mail-archive.com/django-users@googlegroups.com/msg36675.html