- 1 Overview
- 2 Installation/Deployment
- 3 Technical Documentation
eSciDocEnhanced Scientific Documentation admin is a a solution for the management of master data in an installation of the eSciDocEnhanced Scientific Documentation core services. Currently it is implemented as TurboGears web application talking to the core service handler's RESTRepresentational State Transfer interfaces.
It implements (parts of) the use cases specified in
Repository URLUniform Resource Locator: https://subversion.mpdl.mpg.de/admin/
- Python (>= 2.4, < 2.6),
- TurboGears 1.0 (>= 1.0.1, <= 1.0.4) (see http://docs.turbogears.org/1.0/Install for details),
- SQLAlchemy (>= 0.3.10, <= 0.4.9) (download from http://www.sqlalchemy.org/download.html and install from source package with easy_install),
- Depending on your platform it may be necessary to upgrade to a newer version of pysqlite.
- the easy_install command from the python setuptools package is recommended to proceed with the installation.
It is recommended to install the following exact requirements using virtualenv:
easy_install virtualenv virtualenv escidocadmin_env cd escidocadmin_env source bin/activate easy_install sqlalchemy==0.3.9 easy_install turbogears==1.0.3 easy_install cheetah==2.0.1
when running python 2.4:
then you can checkout the escidocadmin source into the environment:
When using virtualenv, be sure to call the startup script with the correct python, i.e. escidocadmin_env/bin/python.
You can run eSciDocEnhanced Scientific Documentation admin from a subversion repository checkout: run
in a suitable directory.
Note: If you want eSciDocEnhanced Scientific Documentation admin to work with escidoc core service version 1.0, you'd need to checkout
To configure eSciDocEnhanced Scientific Documentation admin, you need to provide several settings in a configuration file (possibly using test.cfg as a template). Details about syntax and semantic of the runtime configuration can be found on the TurboGears site. In the following we explain eSciDocEnhanced Scientific Documentation admin specific settings.
You need to supply some basic configuration settings for the application by adding the following lines to the global section of the configuration file.
Configure the core services instance to which to talk
When the core services instance is accessed over HTTPSHyperText Transfer Protocol Secured, set
Provide a database connection string:
Note: If you give an absolute path to the sqlite db file, the connection URIUniform Resource Identifier should start with "sqlite:////", i.e. 4 slashes.
When deploying the web application behind a proxy (e.g. apache), make sure to set
Depending on your usage of the admin application, you have to specify
To enable sessions you need to set:
session_filter.on = True
If you run eSciDocEnhanced Scientific Documentation admin in development mode, i.e. started from the command line (see below), you may want to set
to be able to follow the complete communication between application and core services in the shell.
You may rename the configuration file (here: test.cfg) to dev.cfg to have it picked up by TurboGears automatically.
eSciDocEnhanced Scientific Documentation admin stores session data in a sqlite database. To initialize this database run
tg-admin sql create
in the application directory, i.e. in the directory where the configuration file resides.
Note: The tg-admin command was installed with TurboGears.
Controlling the Application
You may use the start-escidocadmin.py script to start the application from the commandline.
Testing the Installation
- The following tests assume that escidocadmin is configured to access a running core services instance.
- If escidocadmin is installed in a virtualenv, the environment has to be activated (i.e. bin/activate has to be sourced) before running tests or starting the application.
1. You can test your installation by running the unit tests with nose.
in the application directory should result in something like
.......... ---------------------------------------------------------------------- Ran 10 tests in 7.039s
2. You can test your running application with twill as follows. Start the application
python twill_tests.py --cfg=/path/to/config USER PASSWORD
Warning: Running the twill tests assumes a set of existing resources in the framework administration. The tests will alter these resources and add new ones. So don't run these tests on a framework with valuable data.
Running eSciDocEnhanced Scientific Documentation admin behind ApacheOpen Source and Most Widely Used Web Server HTTPDHypertext Transfer Protocol Daemon
To run eSciDocEnhanced Scientific Documentation admin behind ApacheOpen Source and Most Widely Used Web Server HTTPDHypertext Transfer Protocol Daemon add the following to your apache configuration:
RewriteRule ^/escidoc/admin/path/(.*) http://127.0.0.1:8080/$1 [proxy,L] <Location /escidoc/admin/path> Order allow,deny Allow from all </Location>
If you also want the static files to be served by apache directly, add the following in your apache config (before the above snippet):
Alias /escidoc/admin/path/static/ "/filesystem/path/to/escidocadmin/escidocadmin/static/" RewriteRule ^/escidoc/admin/path/static/(.*) - [L]
eSciDocEnhanced Scientific Documentation admin manages resources of the following kinds:
- Organizational Units, abbreviated ou,
- Contexts, abbreviated ctx,
- User Accounts (and Grants), subsumed under aa (for authentication and authorization).
Automatically generated package documentation is available in the repository.
eSciDocEnhanced Scientific Documentation admin - as a web interface to a RESTRepresentational State Transfer APIApplication Programming Interface supporting basic CRUDCreate, Retrieve, Update and Delete operations - has a very simple architecture:
- All communication with the core services resource handlers is implemented in a core services client library
- As a TurboGears aplication, escidocadmin subscribes to the MVCModel View Controller pattern, or better the VC pattern, because the persistence layer is implemented by the eSciDocEnhanced Scientific Documentation core services.
- The management logic for each resource is implemented in one controller class.
- The views for each resource are implemented in one (or several) templates.
Core services Client Library
Since resources are transferred between core service resource handlers and clients as xml representations, the client library treats resources basically as (wrapped) xml dom objects (more precisely as etree.Element instances). A Resource instance is initialized with an appropriate Element of a parsed core service resource handler response, and can be serialized for passing it back to the core service resource handler.
eSciDocEnhanced Scientific Documentation admin uses eSciDocEnhanced Scientific Documentation user accounts to access the core services resource handlers. After successful authentication with the external identity provider the admin application receives a token which is subsequently used to authenticate requests to the core service resource handlers (see login_finish).
Note: Currently, eSciDocEnhanced Scientific Documentation admin does only support the core services' default form based authentication.