CSpace-Django webapps - setting up Python and Django in a development environment

Introduction

This document describes how to set up a development environment in which to create Django-based webapps for CollectionSpace. These instructions take advantage of the development server built into Django. For production deployment notes, see CSpace-Django webapps - setting up a production environment using Apache.

You'll start by installing Python, then creating a virtual environment and installing Django in it. You'll then download a pre-built project for developing your webapps. This project, the CollectionSpace Django Project, was created by developers at the University of California, Berkeley as a way to accelerate the process of writing web-based applications for Django that can connect to CollectionSpace via the /wiki/spaces/DOC/pages/2930127515.

The CollectionSpace Django Project, called cspace_django_project, is available from UC Berkeley's cspace_deployments GitHub repository. While it is intended to be the "starter project," you could just as well start with a project from a different repository that has already been customized in a manner that closely fits your needs.

Finally, you'll set up that project to the point that its webapp:

Display a "Hello, World"-type screen
Return content from a demonstration CollectionSpace server, to which it can connect via a username and password you provide.

Python

Django requires any Python version from 2.6.5 to 2.7,x. To ensure Python is installed and is the required version, type into the shell:

python -V
Python 2.7.1

Pip

Pip is a tool for installing and managing Python packages.

Begin by checking whether Pip is installed, and if so, which version:
```
which pip
```
or
```
sudo yum list installed | grep -i pip
```
If Pip is not installed, install it.
- For apt-based systems, the process is straight-forward:
```
sudo apt-get install python-pip python-dev build-essential
```
  The python-dev and build-essential packages are recommended to install along, because it isn't possible to install any Python module that ships with a C extension without them later on.
- On RedHat systems, this is a slightly roundabout process:
  1. Install the python-devel package:
    sudo yum install python-devel
  2. Install python-setuptools:
    sudo yum install python-setuptools
    python-distribute might work, too: http://docs.python-guide.org/en/latest/starting/install/linux/
  3. Install Pip:
    sudo easy_install pip
  4. Update setuptools using Pip:
    sudo pip install setuptools --upgrade
Upgrade Pip (same process for apt- and yum-compatible systems)
```
sudo pip install --upgrade pip
```
Please install any Python libraries that you might need.

Ed. note: Document installation of psycopg library? pgdb library?

Virtualenv

Virtualenv is a tool for creating isolated python environments specific to a project's dependencies. It creates a private installation directory, and, when a particular environment is activated, appends this directory to your $PATH. Virtualenv is not a strict requirement, but it is commonly used and extremely helpful in keeping environments separate between two (or many) projects.

Install virtualenv (same for apt- and yum-compatible systems)
```
sudo pip install virtualenv
```

Virtualenvwrapper

Virtualenvwrapper is a set of wrappers to Virtualenv to make it easier to create, delete, and switch between virtual environments.

Virtualenvwrapper is valuable for development machines on which developers may need to switch quickly and easily between various projects.

Install virtualenvwrapper (same for apt- and yum-compatible systems)
```
sudo pip install virtualenvwrapper
```
To setup virtualenvwrapper, we'll have to set the location where the virtual environments will live, and the location of virtualenvwrapper.sh. Add these lines to your login shell startup file (for me, .bash_profile):
```
vi ~/.bash_profile

export WORKON_HOME=$HOME/.envs
source /usr/local/bin/virtualenvwrapper.sh
```
Reload your startup file:
```
source ~/.bash_profile
```
More documentation on virtualenvwrapper here: http://virtualenvwrapper.readthedocs.org/en/latest/

Create a virtual environment for your project

To create a virtual environment for your project, enter the following:
```
mkvirtualenv cspace_django_project_env --no-site-packages
```
This creates a new virtual environment with just Python and Pip (--no-site-packages). Choose whatever name you like; for the purposes of this tutorial, I've chosen cspace_django_project_env.
When you create a new virtualenv, it is automatically activated, and you should see the name of your virtual environment preceding the shell prompt.
If you're using virtualenvwrapper and you don't see your virtual environment name preceding the shell prompt, you can activate your new virtualenv by entering:
workon cspace_django_project_env
(Note that the workon command offers tab-completion functionality.)
To deactivate the current virtualenv, enter:
```
deactivate
```

Install Django

First, make sure you're working in the virtualenv you set up for this project. If you don't see that virtualenv's name preceding your shell prompt, enter the activate command, followed by the name of that virtualenv; e.g.
```
activate cspace_django_project_env
```
If you're using virtualenvwrapper, type instead:
workon cspace_django_project_env
Then install Django:
```
pip install django
```
Django itself is the only dependency for the cspace_django_project. However, if you're working on a fork (modification by another developer) of the cspace_django_project and it has other dependencies (such as requirements for additional Python libraries), install those dependencies now.

Verify that Git is installed

Git is a version control system for managing source code and other artifacts. You can use Git to download a project for developing Django-based webapps for CollectionSpace:

Check whether the Git command-line client is installed:
```
git --version
```
If Git is not currently installed (git: command not found), install it:
```
sudo apt-get install git
```
Ed. note: Add instructions for installing Git on yum-compatible systems

Download cspace_django_project (or a fork of cspace_django_project)

Navigate to a folder where you would like the source code for your project to live. For our purposes, I'm going to download the project to ~/Projects. (You can create this folder with mkdir ~/Projects if it doesn't already exist.)
```
cd ~/Projects/
```
For production deployments, the virtual environment and the project code should both be installed within the /usr/local/share/django directory

PyCharm is a useful integrated development environment for Python and Django projects. (Open Source projects can apply for a free license.) By default, PyCharm places project code in the ~/PycharmProjects/ directory.
Clone the cspace_django_project repository on GitHub into your current folder:
```
git clone git@github.com:cspace-deployment/cspace_django_project.git
```
You may also download another fork of this project or clone another project if you wish.
If you are a contributor to this project, you'll clone the project instead via:
git clone git@github.com:cspace-deployment/cspace_django_project.git
Change into the newly-created project folder:
```
cd cspace_django_project
```

Build the database

Before you can run the basic cspace_django_project, you'll have to build a database. The default database is a sqlite database, and the default location for the database file, once created, will be cspace_django_project/db.sqlite3.

These values are specified in cspace_django_project/cspace_django_site/settings.py. You can have a look at the Django documentation or the [Django Tutorial|https://docs.djangoproject.com/en/1.5/intro/tutorial01 for more information about settings.py.

Make sure:
- You're still working within the virtualenv set up for this project. (If not, enter: workon followed by the name of your virtualenv; e.g. workon cspace_django_project_env)
- Have your current directory set to the project directory. (If not, change into that directory; e.g. cd ~/Projects/cspace_django_project)
Build the database:
```
python manage.py syncdb
```
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.)

Start the Django development server

Django comes with a built-in, "lightweight" web server. This web server isn't suitable for production, but it's eminently usable for development and testing.

Start the built-in Django web server:
```
python manage.py runserver
```

Changing the port

By default, runserver starts the development server at port 8000. To change the server's port, pass it as a command-line argument:

python manage.py runserver 8080

To change the server's IP address, pass it as an argument along with the port, separated by a colon (":"). (The special IP address 0.0.0.0 will cause Django to listen on all of your host's network interfaces: for localhost, its Ethernet and/or wireless networks, etc.)

python manage.py runserver 0.0.0.0:8000

More documentation about Django's runserver command.

Test

Navigate your browser to http://127.0.0.1:8000

In your browser window, you should see
```
Hello, world. This is the testapp.
```
This confirms the Django server is working.

Navigate your browser to http://127.0.0.1:8000/service/intakes/

You should get redirected to a login screen. By default, the CollectionSpace Django Project is configured to connect to the demonstration CollectionSpace system at demo.collectionspace.org.

Login with the credentials for the Admin user for the core tenant:
- Username: admin@core.collectionspace.org
- Password: Administrator

In your browser window, you should see an XML payload, listing the Intake records on that system.

Next Steps

If you're just starting a new project built off the cspace_django_project, read about how to create a new CollectionSpace Django project in GitHub here:

CSpace-Django webapps - setting up a code repository.

For documentation on setting up a production environment, see:

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

To learn more about building Django-based CollectionSpace webapps for your museum:

Browse examples of existing webapps, which you can find in various repositories on the cspace-deployment GitHub page.
Refer to the Django documentation.
Ask questions on the CollectionSpace /wiki/spaces/collectionspace/pages/666276158.

CollectionSpace Deployments