Description

A "CSpace-Django webapp", as used here, is an application written in Python using the Django web framework which accesses data in a Collectionspace server via its REST API. Such a webapp will need to authenticate itself to the target CSpace server using credentials provided by the user. A framework for doing this has been developed and is available in GitHub.

The following description assumes you'll be deploying your Django-based webapps using Apache2 under Linux (specifically RedHat 6).

If you wish to use another Django deployment option, please consult the Django documentation at: https://docs.djangoproject.com/en/1.5/.

This is a preliminary document. Treat it with caution.

Overview of steps

To deploy and operate a Django webapp for use with CSpace servers, you will need to:

Install Django on a suitable server. (See CSpace-Django webapps - setting up a production environment using Apache.)
Deploy your institution's CSpace authentication project. (See CSpace-Django webapps - setting up a code repository.)
Depending on details, you'll need to modify:
- The Django configuration parameters for running Django with WSGI under Apache2
- The project parameters for your project (logging, CSpace server to use, some Django parameters)
- Any parameters your webapp uses that are installation-dependent.

Your institution's CSpace authentication project

These instructions presume you have already created a Django project for your institution, which includes the Django authentication backend. This process is described in:

CSpace-Django webapps - setting up a code repository

That project will contain the example applications that make requests to and process responses from a CollectionSpace instance, as well as any other applications that have been developed for your institution. It is the starting point for creating new Django-based web applications that connect to a CollectionSpace instance.

Installing and Configuring

The process described below is a manual technique for a one-time deployment of a fresh CSpace-enabled Django webapp.

Make sure Apache, Python 2.6 (or higher), and Django 1.5 (or higher) is installed: see CSpace-Django webapps - setting up a production environment using Apache.

You'll want to update the Apache configuration and restart after you have your own code installed. Apache may not restart properly if you configure it first. The Apache configuration steps are described further below. For a similar discussion on configuring Apache for a 'hello world' Django project, see also: CSpace-Django webapps - setting up a production environment using Apache

Locate the Django deployment directory that was created during Django installation.

See CSpace-Django webapps - setting up a production environment using Apache.

cd /usr/local/share/django

Copy or 'git clone' the authentication webapp and your webapp(s)into this directory

sudo git clone https://github.com/{your-GitHub-organization-account}/pahma_django_project.git
sudo chgrp -R developers pahma_django_project/
sudo chmod -R g+w pahma_django_project/
cd pahma_django_project

This is your institution's GitHub repository, or your fork of it. This tutorial creates a project called pahma__django_project.

Configure your project for your CSpace server and deployment

This mainly entails editing 4 files in the cspace_django_site site directory:

main.cfg
wsgi.py
settings.py
urls.py

cd cspace_django_site

Setting the CollectionSpace connection properties in main.cfg

# update hostname for CSpace server, etc.
    vi main.cfg

    #main.cfg

    [info]
    shouldReloadConfig = True

    [cspace_authn_connect]
    shouldReloadConfig = True
    realm              = org.collectionspace.services
    uri                = cspace-services/accounts/0/accountperms
    hostname           = pahma-dev.cspace.berkeley.edu (for example)
    protocol           = http
    port               = 8180

    [cspace_services_connect]
    realm             = org.collectionspace.services
    hostname          = pahma-dev.cspace.berkeley.edu (for example)
    protocol          = http
    port              = 8180

Set the WSGI mount point in wsgi.py

vi wsgi.py

    [...]
    WSGI_BASE = '/pahma_project'
    [...]

Update project-specific parameters in settings.py

Time zone and language
Static url

Names of your webapp(s) in INSTALLED_APPS

vi settings.py
  [...]
  # Local time zone for this installation. Choices can be found here:
  # http://en.wikipedia.org/wiki/List_of_tz_zones_by_name
  # although not all choices may be available on all operating systems.
  # In a Windows environment this must be set to your system time zone.
  TIME_ZONE = 'America/Los_Angeles'

  # Language code for this installation. All choices can be found here:
  # http://www.i18nguy.com/unicode/language-identifiers.html
  LANGUAGE_CODE = 'en-us'
  [...]
  STATIC_URL = '/pahma_project_static/'
  [...]
  # add webapps here, e.g. ireports...
  INSTALLED_APPS = (
    [...]
    # cspace example webapps
    'hello',
    'service',

    # add any webapps of your own here and in urls.py
    #'ireports',
  )

    [...]

Add the base urls for your webapps to `urls.py`

cd ../cspace_django_site/
vi urls.py

urlpatterns = patterns('',
          # urls for CSpace authentication and example webapps

          url(r'^$', 'hello.views.home', name='home'),
          url(r'^accounts/login/$', views.login, name='login'),
          url(r'^admin/', include(admin.site.urls)),
          url(r'^service/', include('service.urls')),

	  # add the base urls for any wepapps of your own here and in settings.py
          # Example (without # character):
          #url(r'^ireports/', include('ireports.urls')),
           )

Create the static root folder (if necessary) and collect static files:

cd ../../pahma_django_project
sudo mkdir static_root
sudo sh -c "source ../venv26/bin/activate; python manage.py collectstatic"

At the prompt, type yes to continue

Initialize the sqlite3 database and log files

The CSpace authentication webapp needs this. Needs to be done for each of your projects. Note that when Django was installed on your server, the sysadmin will normally have created a project directory with a test app to verify the Django installation.
```
cd ../pahma_django_project
sh -c "source ../venv26/bin/activate; python manage.py syncdb"
```
Ed. note - In the documentation for setting up a development environment, we suggest that users create an sqlite3 superuser: "You will see a prompt asking if you'd like to create a superuser. Choose 'yes' and select something memorable for the username and password. (This is a superuser for the Django application and can be helpful if things break.)" Should the same advice apply for a production environment?

More documentation about manage.py.

set permissions

Change to the django directory:

cd ../../django

Set the following permissions:

sudo chown apache:apache *_project/db.sqlite3
sudo chcon -t httpd_sys_rw_content_t *_project/db.sqlite3

sudo chown -R apache:apache *_project
sudo chcon -t httpd_sys_rw_content_t *_project/

sudo chmod g+w *_project/db.sqlite3
sudo chmod g+w *_project

Change to the pahma_django_project directory.

cd pahma_project

Continue changing permissions:

sudo chown apache:apache logs/*
sudo chcon -t httpd_sys_rw_content_t logs/*

sudo chown -R apache:apache logs
sudo chcon -t httpd_sys_rw_content_t logs

sudo chmod g+w logs/*
sudo chmod g+w logs

sudo chown -R apache:apache static_root/*
sudo chcon -t httpd_sys_rw_content_t static_root/*

sudo chown -R apache:apache static_root
sudo chcon -t httpd_sys_rw_content_t static_root

Ed. note - Python needs to be able to write to static_root, not Apache. Are these last four lines correct? Also, sudo chown -R apache:apache logs seems to supercede sudo chown apache:apache logs/*. Do we need both?

Update Django configuration for Apache

Typically in a file named django.conf. The following is a config file for two projects installed described further down on this page in #Typical Django directory structure

$ sudo cat /etc/httpd/conf.d/django.conf
$ sudo vi /etc/httpd/conf.d/django.conf

LoadModule wsgi_module modules/mod_wsgi.so

WSGIDaemonProcess pahma_project_wsgi python-path=/usr/local/share/django/pahma_django_project:/usr/local/share/django/venv26/lib/python2.6/site-packages user=apache group=apache

WSGIScriptAlias /pahma_project /usr/local/share/django/pahma_django_project/cspace_django_site/wsgi.py

WSGISocketPrefix run/wsgi

<Location /pahma_project>
     WSGIProcessGroup pahma_project_wsgi
</Location>

<Directory "/usr/local/share/django/pahma_django_project">
        Order allow,deny
        Allow from all
</Directory>

Alias /pahma_project_static/ /usr/local/share/django/pahma_project/static_root
<Directory "/usr/local/share/django/pahma_django_project/static_root">
      Order deny,allow
      Deny from all
      Allow from all
</Directory>

Ed. note: Is it necessary to grant Apache permissions beyond the django/ directory?

Note to UC Berkeley deployers: Existing Django projects that include the imageserver app require an image_cache directory that is writable by Apache. This cache is defined in cspace_django_site/settings.py. Without the properly-configured image_cache directory, the server will return a 500: Internal Server Error.

Follow these instructions to create and configure the image_cache directory:

cd /tmp
# If the image_cache directory doesn't exist, make it
sudo mkdir image_cache
# Set configuration on the directory
sudo chown apache:apache image_cache
sudo chcon -t httpd_sys_rw_content_t image_cache

UC Berkeley projects also require PIL – the Python Imaging Library. PIL has its own requirement: libjpeg-turbo-devel. (The '-devel' is important.)

To install:

cd /usr/local/share/django/venv26/
source bin/activate
yum install libjpeg-turbo-devel
# As sudo, first re-activate virtualenv, then install package in the correct Python library
sudo sh -c "source bin/activate; easy_install PIL"
# Create a symbolic link to PIL so Python/Django can find the package
cd lib/python2.6/site-packages/
sudo ln -s PIL-1.1.7-py2.6-linux-x86_64.egg/ PIL

Restart Apache

Check for errors as you do this.

sudo service httpd restart
sudo tail  /var/log/httpd/ssl_error_log

Test your configuration

If all is correct, you should be able to access the hello project web site. (Hello is a sample project that comes as part of the cloned code.)

Browse to http://your_server_name/pahma_project

Your screen should display:

Hello, world. This is the testapp.

on a white background.

Success!

The next steps would be to build out your webapp as a project alongside cspace_django_site and hello within your pahma_django_project directory.

Typical Django directory structure

Below is an example of a Django directory with two projects (pahma_project and botgarden_project), each pointing to a different CSpace server, and each have one "custom webapp" called ireports.

cd <django_base_directory>
# perhaps something like /usr/local/share/webapps

Ed. note - The list below looks like it might contain some errors or "out-of-dateness."

pahma_project:

-rw-r--r--. 1 apache apache     0 May  2 21:34 __init__.py
-rwxrwxrwx. 1 apache apache 51200 May  3 14:19 db.sqlite3
-rw-r--r--. 1 apache apache   254 May  2 21:34 manage.py

drwxr-xr-x. 2 apache apache  4096 May  2 21:34 authn
drwxr-xr-x. 2 apache apache  4096 May  2 21:34 common
drwxr-xr-x. 3 apache apache  4096 May  2 23:02 cspace_auth

    botgarden_project/cspace_django/site:
    -rw-r--r--. 1 apache apache    0 May  2 21:34 __init__.py
    -rw-r--r--. 1 apache apache 1434 May  2 21:34 wsgi.py
    drwxr-xr-x. 4 apache apache 4096 May  2 21:34 templates
    -rw-r--r--. 1 apache apache 3252 May  2 21:34 main.py
    -rw-r--r--. 1 apache apache 1199 May  2 21:34 urls.py
    -rw-r--r--. 1 apache apache 7478 May  2 22:34 settings.py
    -rw-r--r--. 1 apache apache  609 May  2 23:03 ucbapp.wsgi
    -rw-r--r--. 1 apache apache  473 May  3 15:53 main.cfg

drwxr-xr-x. 2 apache apache  4096 May  2 23:02 service
drwxr-xr-x. 2 apache apache  4096 May  2 23:02 hello

drwxr-xr-x. 3 apache apache  4096 May  2 23:02 ireports

botgarden_project:

-rw-r--r--. 1 apache apache     0 May  2 21:34 __init__.py
-rwxrwxrwx. 1 apache apache 51200 May  3 14:19 db.sqlite3
-rw-r--r--. 1 apache apache   254 May  2 21:34 manage.py

drwxr-xr-x. 2 apache apache  4096 May  2 21:34 authn
drwxr-xr-x. 2 apache apache  4096 May  2 21:34 common
drwxr-xr-x. 3 apache apache  4096 May  2 23:02 cspace_auth

drwxr-xr-x. 2 apache apache  4096 May  2 23:02 service
drwxr-xr-x. 2 apache apache  4096 May  2 23:02 hello

drwxr-xr-x. 3 apache apache  4096 May  2 23:02 ireports

CollectionSpace Deployments

CSpace-Django webapps - setting up configuration for your project

Description

Overview of steps

Your institution's CSpace authentication project

Installing and Configuring

Locate the Django deployment directory that was created during Django installation.

Copy or 'git clone' the authentication webapp and your webapp(s)into this directory

Configure your project for your CSpace server and deployment

Setting the CollectionSpace connection properties in main.cfg

Set the WSGI mount point in wsgi.py

Update project-specific parameters in settings.py

Add the base urls for your webapps to `urls.py`

Create the static root folder (if necessary) and collect static files:

Initialize the sqlite3 database and log files

set permissions

Update Django configuration for Apache

Restart Apache

Test your configuration

Typical Django directory structure

Description

Overview of steps

Your institution's CSpace authentication project

Installing and Configuring

Locate the Django deployment directory that was created during Django installation.

Copy or 'git clone' the authentication webapp and your webapp(s)into this directory

Configure your project for your CSpace server and deployment

Setting the CollectionSpace connection properties in main.cfg

Set the WSGI mount point in wsgi.py

Update project-specific parameters in settings.py

Add the base urls for your webapps to urls.py

Create the static root folder (if necessary) and collect static files:

Initialize the sqlite3 database and log files

set permissions

Update Django configuration for Apache

Restart Apache

Test your configuration

Typical Django directory structure

Add the base urls for your webapps to `urls.py`