Custom Search

Friday, October 22, 2010

Set up Django on WebFaction Tutorial Example

Set up Django on WebFaction Tutorial Example
  1. Create a new WebFaction Shared hosting account (Shared-1 through Shared-4, according to your project's needs).
    1. You can do this at
  2. Create a new Django application on your local machine.
    1. I recommend keeping your projects in an easily accessible place, like /src/python/ (C:\src\python\ on Windows).
    2. At the command line, navigate to the directory where you keep your Web projects.
    3. Run:
      python /bin/ startproject
      to create a new project.
      1. Note: refers to the place where the Django source code exists on your machine.
        Additionally, will be the name of your new project.
      2. Concretely, I would do this on my machine:
        cd /src/python
        python /opt/local/lib/python2.5/django/bin/ startproject mikesproject
  3. Set up your project's static assets.
    1. I store my project's static assets in a directory named "elements." Create this directory.
      cd /src/python/
      mkdir elements
      mkdir elements/css # store all CSS here
      mkdir elements/img # store all HTML design images here
      mkdir elements/js # store JavaScript files here
      mkdir elements/swf # store Flash files here
      mkdir elements/media # store user-contributed media here
    2. To simplify local development and deployment, you can use Django's static media server to serve out the elements folder. Note: when the project is deployed to WebFaction, you must be certain that these files are served by Apache and not by the Django media server.
      1. In, add these new global settings variables (anywhere you want):
        DEVELOPMENT = True
        PROJECT_DIRECTORY = '/src/python//'
        ELEMENTS = PROJECT_DIRECTORY + 'elements/'
      2. In the global, add this code at the bottom of the file:
        # Catch elements URLs for working in development
        if settings.DEVELOPMENT:
        urlpatterns += patterns('',
        (r'^elements/(?P.*)$', 'django.views.static.serve', { 'document_root': settings.ELEMENTS, 'show_indexes': True }),
      3. You will also need to add this to the top of the file to avoid a run-time error:
        import settings
    3. If you want to use Django's admin interface, set ADMIN_MEDIA_PREFIX in like so:
      ADMIN_MEDIA_PREFIX = '/elements/admin/'
  4. Set up your project's database.
    1. To ease development, we typically use sqlite3. The sqlite3 database is stored in a single file and can be easily passed around without the need for a dump/load procedure.
    2. In, set the database settings like so:
      DATABASE_ENGINE = 'sqlite3'
    3. Leave the other database settings blank.
    4. If you want to use Django's admin interface, add this line to the end of the INSTALLED_APPS tuple in
    5. Finally, create the database file. On the command line (in your project directory), type:
      python syncdb
      1. You will need to enter your new administrator username, email and password as part of the initial sync.
  5. Create a settings file for WebFaction.
    1. will be different on WebFaction than on your local machine. Copy your local to a new file called In your project directory, type:
    2. Edit the new file.
      1. Set the DEVELOPMENT global to False. This will disable the static media server set up in step 3.2.
      2. Modify the PROJECT_DIRECTORY setting to the directory where your project will exist on WebFaction. Assuming that you set up your account as a Django account, it should look like:
        PROJECT_DIRECTORY = '/home//webapps/django//
    3. Maintaining a separate settings file for WebFaction is a reasonably efficient way to manage differences between your local machine and the WebFaction server; however, note that you will need to manually keep the two files in sync. Anything you add to your local will need to be added to as well.
  6. Set up Subversion on WebFaction.
    1. Log in to the WebFaction control panel at with the username and password provided for your new account by WebFaction.
    2. In the navigation menu, under "Domains/Websites" click on the "Applications" link.
      1. Click on the "Add" button in the bottom right to create a new application.
      2. Type "subversion" into the name field.
      3. Choose "Subversion" from the App type drop-down.
      4. Click the "Create" button.
    3. Now, create a subdomain for Subversion. In the navigation menu, under "Domain/Websites" click on the "Domains" link.
      1. Click on the "Edit" button in the row for ""
      2. Click on the "Add" button in the bottom right of the "Subdomains" section.
      3. Enter "svn" in the new "Prefix" field.
      4. Click the "Update" button.
    4. Create a Website to tie the subdomain to the application. In the navigation menu, under "Domains/Websites" click on the "Websites" link.
      1. Click the "Add" button in the bottom right to create a new Web site.
      2. Enter "subversion" in the name field.
      3. Select "" in the "Subdomains" field.
      4. Click the "Add" button under "Site apps".
      5. Choose "subversion" from the "App" drop-down, and enter "/" in the "URL path" field.
      6. Click the "Create" button.
      7. Now, the Subversion repository is set up and running at
    5. Next, you need to ssh into your WebFaction account to configure the Subversion repository permissions.
      1. At the command line, type:
      2. Enter your password to log in.
      3. Navigate to the Subversion directory and set up usernames and passwords to control access to the repository:
        cd ~/webapps/subversion
        1. View the .htpasswd file to see what usernames have been set up:
          less .htpasswd
        2. Delete the "test" username from .htpasswd
          htpasswd -D .htpasswd test
        3. Create a username and password for all the people who will have access to the repository (the example here uses md5 hashes to store the passwords):
          htpasswd -m .htpasswd
          (Enter the new password twice at the prompt.)
        4. Review the list of usernames to verify that you've added all desired users:
          less .htpasswd
    6. Congratulations! Subversion is ready to use.
  7. Check your Django project into Subversion.
    1. First, create the directories that you'll need in the repository, according to Subversion best practices. At your local command prompt, from your project folder type:
      svn mkdir -m "initial project directory structure for "
    2. Now, verify that your local subversion settings are correct before you check in any code. I recommend not storing .pyc files in the repository and also not checking in the file.
      1. Open this file for editing: ~/.subversion/config ("C:\Documents and Settings\\Application Data\Subversion\config" on Windows)
      2. In the [miscellany] section, uncomment the "global-ignores" line and add any filename patterns that you want Subversion to ignore. On my machine, where I'm primarily performing Django development using TextMate as my editor, my global-ignores settings looks like this:
        global-ignores = *.o *.lo *.la *.pyc *.tmproj .*
      3. The most imporant entries here are "*.pyc" and "" - these prevent Subversion from checking in and managing binary compiled Python (.pyc) and Django files.
    3. Now, you can import your new project into the Subversion trunk you set up in step 7.1. In your project's directory, type:
      svn import .
      1. Note: This will import all files and directories from your project with the exception of (because of your "global-ignores" setting).
    4. At this point, your code is stored in the repository, but your local files are not yet managed by your Subversion client. You need to check out the project you just imported to get a managed local copy. Starting in your project directory, perform these commands.
      cd .. # go up one directory
      mv _tmp # move the project to a temp directory
      svn co # check out the project
      cp _tmp/ # copy the original file into the checked out project.
      rm -rf _tmp # remove the temporary project folder
    5. Now you have a local working copy of the code stored in the Subversion repository.
  8. Check out the project on the WebFaction server.
    1. You must have a Django application set up on the server before you can perform this step. If you chose Django as the application type when you created your WebFaction account, this is already done. Otherwise, perform these steps:
      1. In the WebFaction control panel's navigation menu, under "Domains/Websites" click on the "Applications" link.
      2. Click the "Add" button in the bottom right.
      3. Enter "django" in the "Name" field.
      4. Choose a version of Django from the "App type" drop-down. At the time of this writing, I'm using "Django 0.96.2/mod_python 3.3.1/Python 2.5"
      5. Click the "Create" button.
    2. SSH into WebFaction. Navigate into your Django project directory and check out the project:
      cd ~/webapps/django
      svn co
    3. Create the file for the server by copying
      cd ~/webapps/django/
  9. Create a new application to serve static media in your project's elements folder.
    1. In the WebFaction control panel's navigation menu, under "Domains/Websites" click on the "Applicatins" link.
    2. Click the "Add" button in the bottom right.
    3. Enter "django_elements" in the "Name" field.
    4. Choose "Symbolic Link" from the "App type" drop-down.
    5. Enter the absolute path to the elements folder in the "Extra info" field. It should look like this:
    6. Click the "Create" button.
  10. Set up Apache to serve your Django application.
    1. SSH into the your WebFaction account. Navigate to the Apache configuration folder:
      cd ~/webapps/django/apache2/conf
    2. Edit the httpd.conf file. Modify this line:
      SetEnv DJANGO_SETTINGS_MODULE myproject.settings
      to read:
      SetEnv DJANGO_SETTINGS_MODULE .settings
  11. Finish the remaining tasks in the WebFaction control panel.
    1. In the WebFaction control panel's navigation menu, under "Domains/Websites" click on the "Websites" link.
    2. If you chose Django as the application type when you created your WebFaction account, there should already be a Web site called . If not, create one by following these steps:
      1. Click the "Add" button in the bottom right.
      2. Enter "" in the "Name" field.
      3. Choose the desired subdomain(s) (something other than
      4. Under "Site apps," click the "Add" button.
      5. Choose "django" from the "App" drop-down. Enter "/" in the "URL Path" field.
      6. Click the "Create" button.
    3. Now, edit the Web site by clicking the edit button in the "" row.
      1. Under "Site apps," click the "Add" button.
      2. Choose "django_elements" from the "App" drop-down. Enter "/elements" in the "URL Path" field.
      3. Now, your site is set up to serve out the elements files with Apache and to handle all other URLs with your Django application.
  12. Tie it all together.
    1. SSH into your WebFaction account.
    2. Check out the version of Django you require for your application:
      cd ~/lib/python2.5
      You may need to remove an existing copy of django: rm -rf django
      svn co django
      If you need a different revision than the latest trunk, do this: svn update -R django
    3. Set up a symbolic link to Django for you project:
      cd ~/webapps/django/lib/python2.5
      rm -rf django # remove the WebFaction-provided copy of Django
      ln -s ~/lib/python2.5/django django # create a symbolic link to your revision of Django
      Note: Here, we have modified the project-specific Python lib folder that Apache uses when it runs Django. If you need to run different revisions of Django for two different applications on the server, you could alternatively check out the required revision in the project-specific lib folder, rather than using a symbolic link to the global copy of Django.
    4. Create a symbolic link for serving Django's admin media files out of your elements folder:
      cd ~/webapps/django//elements
      ln -s ~/lib/python2.5/django/contrib/admin/media admin
      Note: the symbolic link name "admin" corresponds to the ADMIN_MEDIA_PREFIX in from step 3.3.
    5. Make Subversion ignore the new symbolic link. From the same directory, type:
      svn propset svn:ignore admin .
    6. Configure the Subversion client on WebFaction. Just like in step 7.2, you'll need to edit the Subversion config file:
      1. Open this file for editing: ~/.subversion/config
      2. In the [miscellany] section, uncomment the "global-ignores" line and change it to look like this:
        global-ignores = *.o *.lo *.la *.pyc *.tmproj .*
      3. Again, be sure to add "" to the list so that you don't clobber your local machine's version of this file.
    7. Check in the working copy from the server:
      cd ~/webapps/django/
      svn ci -m "working copy is now set up on WebFaction"
    8. Restart Apache:
      cd ~/webapps/django/
    9. You should now be able to view your project running in a Web browser at the subdomain you specified in step 11.2.
    10. Finally, you'll probably need to set up an alias to Python 2.5 if you intend to work in the Python interactive shell on WebFaction.
      1. SSH into your WebFaction account and edit the file ~/.bashrc
      2. At the bottom of the file, add this line:
        alias python=/usr/local/bin/python2.5
      3. Save the file and run the command source .bashrc to make the changes take effect. Now, running python will invoke Python 2.5, so Django will be available for import.
  13. Develop.
    1. Write your Django application incrementally in your local working copy.
    2. When you have created and tested a new feature, check it in to subversion.
    3. SSH into WebFaction and update the working copy to apply the checked-in changes.
      cd ~/webapps/django/
      svn update
    4. If you have modified any Python files (*.py files), restart Apache so that mod_python reloads your files:

No comments:

Post a Comment