source: README.txt @ 362:afb7dc8758f5

Revision 362:afb7dc8758f5, 9.0 KB checked in by gibus, 3 months ago (diff)

add python pexpect in dependencies

Line 
1*******
2Comt
3*******
4
5Presentation
6============
7Comt is an free software Web-based text annotation platform.
8
9License
10=======
11GNU AFFERO GENERAL PUBLIC LICENSE
12http://www.gnu.org/licenses/agpl.html
13for software files
14
15CC-BY
16http://creativecommons.org/licenses/by/3.0/
17for translation files
18
19Dependencies
20============
21
22Environment
23-------------
24- Postgresql 8.3 or Mysql 5+ or sqlite
25- Python 2.5+
26- Abiword or Openoffice 3.0+ (headless)
27- Pandoc
28
29
30Requirements
31------------
32- python
33- python magic
34- python development headers
35- python setuptools
36- python pexpect
37- pandoc
38- abiword (or headless openoffice and python uno)
39- git
40- libyaml
41(all other python dependencies will be downloaded by buildout)
42
43Installation (development install)
44============
451. Install python2.5+ and all required libraries
46        (ubuntu users : 'sudo apt-get install python python-magic python-setuptools python-uno libyaml-0-1 python-yaml python-dev git-core python-utidylib python-pexpect')
472. Install pandoc
48        (ubuntu users : 'sudo apt-get install pandoc')
493. Install abiword
50  (ubuntu users: 'sudo apt-get install abiword')
51   Alternatively, install openoffice (headless mode) [used for document conversion]
52        (ubuntu users : 'sudo apt-get install sun-java6-jre openoffice.org openoffice.org-headless xvfb')
534. Install/configure database [skip this step if you plan to use a sqlite database]
54        4 a) Postgresql
55                - Install and configure database server [skip this step if use an external database server]
56                (ubuntu users : 'sudo apt-get install postgresql')             
57                - Install database client
58                (ubuntu users : 'sudo apt-get install postgresql-client')               
59                - Install python database connector: psycopg2
60                (ubuntu users : 'sudo apt-get install python-psycopg2')         
61        4 b) Mysql
62                -  Install and configure mysql server [skip this step if use an external database server]
63                (ubuntu users : 'sudo apt-get install mysql-server')           
64                - Install database client
65                (ubuntu users : 'sudo apt-get install mysql-client')
66                - Install python database connector: mysqldb
67                (ubuntu users : 'sudo apt-get install python-mysqldb')                                         
685. Create a database (we recommend UTF8 encoding) and a read/write access to it. [skip this step if you plan to use a sqlite database]
69   The database account accessing the database MUST have administrative privileges when running the 'syncdb command' (step 8)
70   (The reason for that is that Postgresql requires such privileges to create the C-based stored procedure that we use for full text indexing)
71   (ex. postgresql: 'sudo -u postgres createdb -E utf8 -e <db_name>)
726. Setup the project and get dependencies
73   - `python bootstrap.py`
74   - `./bin/buildout`
757. Configure Comt to your settings
76   - copy settings_local_sample.py to settings_local.py (this file will contain your personal settings) 
77   - edit settings_local.py to suit your settings (search for 'YOUR_SETTINGS' occurrences, those are mandatory settings)
788. Create the database structure (and test your database connection)
79   - `./bin/django syncdb --settings=settings`
80   - `./bin/django migrate --settings=settings`
819. Create basic right management system
82   - `./bin/django loaddata roles_generic --settings=settings`
8310. Launch development server
84   - `./bin/django runserver --settings=settings`
8511. Access your Comt instance by pointing your browser to http://127.0.0.1:8000/
86
87Installation (production environment)
88=============
89This README.txt does not cover in details a production environment because this kind of setup is too platform dependant for us to provide a guide.
90A few tips thought:
91- recommended way to install it is using apache and wsgi, check out django installation guide at http://www.djangoproject.com/documentation/modpython/
92- if you use apache as a frontend, you will need to create {{ APACHE_HOME: usually /var/www }}/.python-eggs and chown it to apache
93
94Upgrade
95=======
96
97Normal upgrade
98--------------
99Upgrading you database should only need one command:
100   - `./bin/buildout`
101   - `./bin/django migrate --settings=settings`
102   
103Upgrade from alpha releases
104----------------------------
105If your database was created using comt alpha prior to the revision 29, here are the commands you should run:
106   - `./bin/buildout`
107   - `./bin/django syncdb`
108   - `./bin/django migrate cm 0001_initial --fake`
109   - `./bin/django migrate`
110
111Abiword or Openoffice
112=====================
113Comt uses either abiword or openoffice to convert documents from ODT, MS Word, etc. to html.
114Abiword is a lighter and more performant solution. You have to add the configuration parameter `USE_ABI = True` in your settings_local.py to use Abiword. Otherwise openoffice is used.
115To use openoffice, on a development setup, you should make sure no openoffice process is left and launch `soffice -headless "-accept=socket,port=2002;urp;"` to start openoffice in background mode.
116
117Comt uses
118============
119
120Javascript libs used (and license) / shipped with the distribution
121------------------------------------------------------------------
122- Yahoo UI      http://developer.yahoo.com/yui/ BSD License
123- JQuery        http://jquery.com/      MIT
124- markItUp  http://markitup.jaysalvat.com/home/ MIT/GPL
125
126Python libraries used (and license) / NOT shipped with the distribution
127-----------------------------------------------------------------------
128- django                        http://www.djangoproject.com/                                   BSD License
129- python magic          http://hupp.org/adam/hg/python-magic                    permissive BSD style license
130- Beautiful soup        http://www.crummy.com/software/BeautifulSoup/   PSF license
131- python-chardet        http://chardet.feedparser.org/                                  LGPL
132- python-feedparser     http://feedparser.org/                                                  "Permissive" custom license
133- python-imaging        http://www.pythonware.com/products/pil/                 http://www.pythonware.com/products/pil/license.htm
134- python-pytz
135- html5lib
136- python-simplejson
137- python-uno
138- python-utidylib
139- python-yaml
140
141Icons
142-----
143- Icons derived from FatCow Icon Set http://www.fatcow.com/free-icons/index.bml (Creative Commons Attribution 3.0 License)
144
145FAQ
146====
147Q1: How can I check the distribution for errors (libraries etc.):
148R1: After configuring a database and access in your settings_local.py, you can launch the unit test suite with the following command: `./bin/django test cm`
149
150Q2: I'm getting the following error when launching the migrate command:
151`
152line 62, in handle
153    __import__(app_name + '.management', {}, {}, [''])
154  File "/usr/lib/python2.5/site-packages/uno.py", line 300, in _uno_import
155    raise ImportError( "type "+ name + "." +x + " is unknown" )
156ImportError: type django.contrib.sessions.management. is unknown
157`
158R2: This is due to a bug in uno (python openoffice bridge) that monkey patches the import system and messes with django's dynamic module loading system. A workaround to launch the migrate command is to set: `UNO_IMPORT = False` in file src/cm/converters/oo_converters.py and then to launch the migrate command. Set the value back to True and relaunch the server to use openoffice as a conversion backend.
159
160Q3: When using  co-ment Drupal module, I want that the name of commentators to be the same as the Drupal username
161R3: For this feature (commentator name = drupal login name) to be available, a configuration parameter should be set in settings_local.py: `DECORATED_CREATORS = True`
162
163Q4: I get 'import error' when starting the server (step #9)
164R4: Make sure you installed all required python dependencies
165                     
166Community
167=========
168The Comt web site is the place to ask questions, report bugs, check out the source code or download the releases of Comt.
169
170How to contribute
171=================
172
173Contribute using mercurial
174--------------------------
175We use mercurial as our source code management system.
176
1771. Create a mercurial profile (nickname/email) in ~/.hgrc (cf. http://mercurial.selenic.com/quickstart for more info).
178   This is important because your name will appear in your changeset once it gets accepted into the mainline
1792. Clone the repository `hg clone http://hg.co-ment.org/ comt`
180   OR update your copy of the source code: `hg update`
1813. Hack, hack
1824. Commit locally: `hg commit -m "MY COMMIT MESSAGE"`
1835. Export your changeset to a file: `hg export tip > my_patch.txt`
1846. Create a ticket describing your change and attach your patch to it: /newticket
1857. We will review the patch as soon as possible. If we judge it acceptable and useful, we will be back to you regarding copyright, licensing and other legalese.
186
187Contribute without using mercurial
188----------------------------------
189If you don't want to use mercurial, you can also create a ticket (/newticket) with a few modified files to the bugtracker.
190Make sure you leave us a nickname and an email for inclusion in the changelog. Point 7 above also applies to contributions without using mercurial.
191 
192Translation
193===========
194
195Update all po files
196---------------------
197cd src/cm
198../../bin/django makemessages -a
199../../bin/django makemessages -d djangojs -a
200
201Compile po files
202----------------
203cd src/cm
204../../bin/django compilemessages
205
206Create new file for lang 'LG'
207-----------------------------
208cd src/cm
209../../bin/django makemessages -l LG -e .html,.txt
210../../bin/django makemessages -d djangojs -l LG
Note: See TracBrowser for help on using the repository browser.