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 namedcspace_django_project
, you might choosecspace_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 namedProjects
, and resides inside your home directory. You can create it withmkdir ~/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
)
- You're still working within the virtualenv set up for this project. (If not, enter:
- Build the database:
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.)
python manage.py syncdb
More documentation about manage.py.
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 seeThis confirms the Django server is working.Hello, world. This is the testapp.
- 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
- Username:
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.