There are many posts that outline the steps to deploy a Django app onto a Dreamhost shared server. This is my experience.
I used a couple of pages as references, both to help me know what to do and to learn what not to do. Installing django 1.3 on DreamHost on oscarcp.com helped with the virtualenv setup, and the Passenger and WSGI section on the Dreamhost Wiki page on Passenger showed how to use the correct python interpreter.
Python
I’ve previously setup the Python 2.6.5 interpreter to be my default on Dreamhost (see this post), so I’m not sure what version they offer currently as the default. Be sure that the version you are running is supported by your desired Django version.
Setup Passenger for you Domain
It’s an option on the Dreamhost panel. When editing your domain, check the box labeled “Passenger (Ruby/Python apps only)“. This will add a /public directory in the domain root. (It may take a few minutes for this work to finish.)
Install Virtualenv
There is a version of virtualenv available on Dreamhost which will work fine. However, I wanted the latest, so I downloaded and installed it. First, I opened a terminal window and ssh’ed to my Dreamhost account. I have a downloads folder setup, so I switched to that before running the download. (As of this writing, 1.6.4 is the latest released version.)
wget http://pypi.python.org/packages/source/v/virtualenv/virtualenv-1.6.4.tar.gz tar -xvf virtualenv-1.6.4.tar.gz python setup.py install
Create the Virtual Environment for the Project
My naming convention for virtual environments is to use the project name followed by ‘env’. Pretty creative, huh? Since my project is an art gallery, I called it ‘galleryenv’.
Before running the command, switch to the root directory for the domain. This is the folder containing the /public directory created by the Passenger selection earlier. The Dreamhost default is to name this the same as the domain, but yours may be different.
virtualenv envname --no-site-packages
The –no-site-packages argument is pretty important, as it instructs virtualenv to ignore all python packages installed in the base interpreter. Everything you need for the project should be installed in this new environment. This means that your project will be insulated from changes to the base install, and will allow different projects/environments to use different versions of the same packages.
Next, activate the interpreter in the virtual environment you just created. Basically, you’re switching to this new copy of Python rather than the default for your account.
source envname/bin/activate
Your command prompt should now be prefixed with the name of the environment.
Run Django Setup Script? I Say No
Dreamhost provides a script, django-setup.py, that will create your settings file with database settings and the passenger_wsgi.py file for your application. This works pretty well for a new project, but most of the work has to be backed out when an existing application using a different directory structure or settings is being setup. Since I develop my projects on a local development machine (as should you), this isn’t much help. Instead, there are just a few manual steps to perform that will get things ready to go.
Also, you’ll notice that we haven’t install Django yet. Since we used the –no-site-packages option when creating the virtual environment, any Django version installed on your account earlier will not be accessible while you are using the new interpreter. The Dreamhost script won’t run unless Django and the MySQL library for Python are installed. No worries! We’ll get to that soon enough.
Bring On the Source code
At this point, it is time to load the source for your Django project onto the server. My convention is to create a directory with the project name in the root directory for the domain – so mine would be called ‘gallery’. You can put these wherever you like, just remember the path for a later step.
I use the Subversion version control system, also provided by Dreamhost, to store my code, so I would use the ‘svn copy’ command to install my source code. Any VCS or DVCS is fine, or the age old FTP approach will work as well.
PIP and Requirements
I’ve just started using PIP recently, although it has been around the Python world for a while. PIP is a general Python install tool, and we’re going to use it to quickly install the libraries we need for our application. Since it is installed with virtualenv (at least in 1.6.4), it is already setup and ready to go.
Before this step, ensure that the virtualenv interpreter is still activated – see the source command above. The goal is to install the needed Python libraries only for this environment and not for use by the default Python install.
PIP offers the option to include a list of libraries to be installed in a batch run. Following convention, I’ve included a file with my application called requirements.txt. Here’s what mine looks like:
Django<1.4 PIL django-photologue
First, I want to install the latest release of Django 1.3, so I ask for the most recent less than v1.4. Next, I need to use the Python Image Library, or PIL. (This library has operating system dependencies that will need to be satisfied before the install.) Finally, the package django-photologue is requested. Prepare your own requirements in this format.
To run PIP with your requirements, use the following syntax:
pip install -r requirements.txt
It's just that easy! Watch the output carefully for any errors or warnings.
Since I'm using MySQL for my database on the server, I also need the mysql-python library.
pip install mysql-python
Passenger Configuration
The django-setup.py script I mentioned earlier builds a file called passenger_wsgi.py that links Apache to the django application. For your install, you can either run the script, or use my example as a starting point. Either way, some edits will be needed to use the virtual environment. Here's is my file:
import sys, os
INTERP = os.path.join(os.environ['HOME'], 'gallery.gentryart.us', 'galleryenv', 'bin', 'python')
if sys.executable != INTERP:
os.execl(INTERP, INTERP, *sys.argv)
sys.path.append(os.getcwd())
sys.path.append(os.path.join(os.getcwd(),'gallery'))
os.environ['DJANGO_SETTINGS_MODULE'] = "gallery.settings"
import django.core.handlers.wsgi
application = django.core.handlers.wsgi.WSGIHandler()
The second line of the script sets a variable (INTERP) to the path of the virtual environment's python interpreter. Basically, the os.path.join command builds the path using the directory names we created earlier. Starting at the home directory, we add in the domain name and the environment name, followed by 'bin/python'. Replace my gallery references with your application's directories.
Lines 3 and 4 will switch to the new python interpreter referenced by the variable.
The sys.path.append lines include our application directory in the search path used by Python, and the next line points to our settings.py file. In these lines, replace 'gallery' with the path to your application source code.
passenger_wsgi.py should be placed in the root directory for the domain. Feel free to copy my example and edit to taste.
Static Media
Better bloggers than I have written about serving static media, and this is just one of many ways to do it. Since I store these files (CSS, JS, images) in version control, they are installed in the application directory created earlier. A simple symbolic link will point Apache to the correct files.
First, switch the the /public directory located in the root directory for the domain. Then, setup the symbolic link to refer to the files. Since my files are located in a directory called 'static', this command takes care of it.
ln -s ../gallery/static static
Next, setup a link for the Django admin media.
ln -s ../galleryenv/lib/python2.6/site-packages/django/contrib/admin/media admin_media
One Last Thing
Since I had already been running my app on this domain using a pre-passenger method for hosting Django, I had a leftover (and hidden) .htaccess file that was messing things up. A quick note to the Happy Dreamhost Support Team and they found and fixed the problem. No .htaccess settings are needed for this type of configuration.
Ready To Go
Hopefully, everything is working for you at this point. In my case, Django came up and told me my database settings were wrong, but I see that as progress. The site is now working fine.
Good luck!
