Setting up a development environment for Django webapps

This document describes how to set up a personal development environment to develop Django-based webapps for CollectionSpace.

You'll start by creating a virtual environment and installing Django. 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 Services Layer REST API.)

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

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.

Requirements

The following instructions requires that you have first completed all of the steps in Setting up Python for Django webapps.

Procedure

Create a virtual environment for your project

To create a virtual environment for your project, initially containing just Python and Pip, enter the following, replacing myproject-env with a name of your choosing for your project's environment:
```
mkvirtualenv myproject_env --no-site-packages
```
You can choose whatever name you like for your project. For instance, if your project is named cspace_django_project, you might choose cspace_django_project_env as its environment name; e.g.:
```
mkvirtualenv cspace_django_project_env --no-site-packages
```

When you create a new virtualenv, it is automatically activated, and you should see the name of your virtual environment name preceding the shell prompt.
If you don't see your virtual environment name preceding the shell prompt, 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 workon command, followed by the name of that virtualenv; e.g.
```
workon cspace_django_project_env
```

Then install Django:
```
sudo 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
```

Download the CollectionSpace Django Project

Navigate to a folder where you would like the source code for your project to be stored.

(In the following examples, this folder is named Projects, and resides inside your home directory. You can create it with mkdir ~/Projects if it doesn't already exist):
```
cd ~/Projects
```

Clone the cspace_django_project repository on GitHub into your current folder:
```
git clone https://github.com/cspace-deployment/cspace_django_project.git
```

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 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 web 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

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.