SchoolTool ========== SchoolTool: the Global Student Information System | Website: http://www.schooltool.org/ | Documentation: http://book.schooltool.org/ | Mailing list: https://launchpad.net/~schooltoolers | Bug tracker: http://bugs.launchpad.net/schooltool Overview -------- SchoolTool is an open source, web based student information system designed for schools in the developing world, with strong support for translation, localization and automated deployment and updates on Ubuntu. System requirements ------------------- - Python (http://www.python.org/) - libicu-dev: International Components for Unicode libraries (http://icu.sourceforge.net/download/) - the Python Imaging Library (PIL) (http://www.pythonware.com/products/pil/) - (optional) the ReportLab Toolkit (http://www.reportlab.org), and Liberation TrueType fonts. ReportLab is only needed if you want to generate PDF reports and calendars. To enable PDF support you will need to specify the path to fonts in the configuration file. On Ubuntu (or Debian), you can install the needed tools and libraries by:: $ make ubuntu-environment If that suceeded, you can skip to `Building SchoolTool from Source`_. What is being installed, is detailed below. Basic C development tools:: $ sudo apt-get install build-essential Python development libraries and virtualenv:: $ sudo apt-get install python-dev python-virtualenv Unicode library:: $ sudo apt-get install libicu-dev Python Imaging Library, to build it you need freetype and jpeg development libraries:: $ sudo apt-get install libfreetype6-dev libjpeg62-dev gettext, needed to compile translations:: $ sudo apt-get install gettext For PDF generation to work need fonts:: $ sudo apt-get install ttf-liberation Other tools:: $ sudo apt-get install libxslt1-dev enscript Building SchoolTool from source ------------------------------- Run ``make`` to download and install all the required zope packages into the eggs folder:: $ make It is a good idea to run tests to check the installation:: $ make test ftest If you are running from a bzr checkout, you need to compile translation catalogs:: $ make compile-translations Creating a SchoolTool Instance ------------------------------ An "instance" is a set of configuration files and data directories, that contain everything needed to run a server for one school. Let's create one:: $ make instance An instance of SchoolTool is created in the ``instance`` directory. Database is ZODB_, in a single file ``instance/Data.fs``. Location of the database, logs, and a few other options can be changed in a configuration file ``instance/schooltool.conf``. One of the options is developer mode, that allows you to add sample data, introspect the database, read API docs, and other useful things. Uncomment a line that says ``devmode on``. You don't want to leave this on for a production server, however. .. _ZODB: http://zodb.org Running SchoolTool ------------------ To start:: $ make run Once the server is running, go to http://127.0.0.1:7080 in the browser. Server is started on local port 7080. You can change the port in the file ``instance/paste.ini``. You will most likely want to make SchoolTool available on port 80. But this port is reserved for the web the server. You will have to configure a virtual host or a path in web server configuration. See `Virtual Hosting`_. Securing SchoolTool ------------------- Beware that the file which contains the database, `Data.fs`, is not given any special permissions to prevent it from being read by other users by default. You will have to change the umask or the permissions of the file manually to prevent unauthorized access. By default a user with administrator privileges is created in the new database. | Username: manager | Password: schooltool You SHOULD change the password after your first login by clicking on `SchoolTool Administrator` in the top right and then `Change password` in the left sidebar. Project structure ----------------- :: GPL.txt the GNU General Public License, version 2 README.txt this file CHANGES.txt release change log Makefile makefile for building extension modules setup.py distutils setup script for building extension modules bin/ scripts build/ temporary files are placed here during build process coverage/ unit test coverage reports (produced by make coverage) reports/ html version of the above (make coverage-reports-html) docs/ documentation instance/ configuration and data log/ log files paste.ini WSGI server configuration schooltool.conf schooltool configuration site.zcml site definition var/ data files Data.fs the database src/ source code schooltool/ Python package 'schooltool' Testing ------- There are two sets of automated tests: unit tests and functional tests. Unit tests (sometimes also called programmer tests) test individual components of the system. Functional tests (also called customer or acceptance tests) test only externally visible behaviour of the whole system. Tests themselves are scattered through the whole source tree. Subdirectories named `tests` contain unit tests, while subdirectories named `ftests` contain functional tests. To run all unit tests:: $ bin/test -u To run all functional tests:: $ bin/test -f The test runner has more options and features. To find out about them:: $ bin/test -h Unit test coverage ------------------ All code should be covered by unit tests. The test runner can help you look for untested code by producing code coverage reports. To generate unit test coverage reports, run:: $ make coverage This command will run the full SchoolTool unit test suite and produce a number of files (one for each Python module) in `./coverage/`. Every report file contains the source of the corresponding Python module. Each source line is annotated with a number that shows how many times this line was reached during testing. Watch out for lines marked with ``>>>>>>`` as they indicate code that is not unit tested. A prettier HTML version of the coverage reports can be generated with:: $ make coverage-reports-html Look at HTML files in `./coverage/reports/`. You should have enscript installed for syntax highlighting source files. The HTML version of coverage reports is published nightly at http://source.schooltool.org/coverage/ Translation ----------- Translation template is `src/schooltool/locales/schooltool.pot`, there are translatable strings extracted from source. Translation templates are used to update translations and create new ones. To regenerate the template:: $ make extract-translations Translation files live in `src/schooltool/locales`. There is a directory for each language that contains a subdirectory `LC_MESSAGES` that contains the compiled `.mo` files. The `.mo` files must be present if schooltool is to use them and are built by the command:: $ make compile-translations To start a new translation, use `src/schooltool/locales/schooltool.pot` as a template (copy it to YOUR_LANG.po). Generate `.mo` files with ``msgfmt`` (or ``make compile-translations``). Virtual hosting --------------- SchoolTool provides support for virtual hosting with Apache's mod_proxy_. The standard instance is running on port 7080. You want to make it available on ``school1.example.org`` port 80. Add the following to your Apache configuration, best place it in a separate file ``/etc/apache/sites-available/school1.example.org``:: ServerName school1.example.org order allow,deny allow from all deny from none ProxyPass / http://127.0.0.1:7080/++vh++http:school1.example.org:80/++/ You need to enable Apache modules ``mod_proxy`` and ``mod_proxy_http``:: $ sudo a2enmod proxy_http Then enable the site and restart apache:: $ sudo a2ensite school1.example.org $ sudo service apache reload If you cannot, or don't want to, setup a subdomain for schooltool, you can make it available at a custom path on another site, e.g. ``example.org/schooltool``. Place the path before the last ``++`` in the URL, and put it somewhere in the configuration of that site:: ProxyPass /schooltool http://127.0.0.1:7080/++vh++http:example.org:80/schooltool/++/ For more information, see `Setting Up Virtual Hosting`_ in Zope documentation. .. _mod_proxy: http://httpd.apache.org/docs/current/mod/mod_proxy.html .. _Setting Up Virtual Hosting: http://wiki.zope.org/zope3/virtualhosting.html HTTPS ----- It is recommmended to use HTTPS/SSL to best protect your users. The configuration is similar, just use port 443 and https instead of http:: ServerName school1.example.org SSLEngine On SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.pem order allow,deny allow from all deny from none ProxyPass / http://localhost:7080/++vh++https:school1.example.org:443/++/ For SSL to work, you need a SSL certificate. Read Ubuntu documentation on OpenSSL_ about creating one. .. _OpenSSL: https://help.ubuntu.com/community/OpenSSL#SSL_Certificates The ``mod_ssl`` module has to be enabled:: $ sudo a2enmod ssl When you get this working, you may want to redirect users that connect through regular HTTP to the secure site. Remove the ``ProxyPass`` for port 80 and replace it with a ``Redirect``:: ServerName school1.example.org Redirect / https://school1.example.org/ Copyright information --------------------- SchoolTool is copyright (c) 2003-2011 Shuttleworth Foundation All files in the src/schooltool directory are part of SchoolTool, and are (c) Shuttleworth Foundation, with the exception of translations in src/schooltool/locales, which are under the copyright of their original contributors via Launchpad at http://launchpad.net . Unless otherwise stated, files in src/schooltool are released under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. Files in the same directory as this README file are (c) Shuttleworth Foundation, with the exception of GPL, which is a copy of the Free Software Foundation's General Public License, and is (c) FSF. SchoolTool is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA You can find the full copy of the GNU General Public License in a file called GPL.txt in the project directory.