Server/site settings overview, deploying a Django site

Starting up Site Deploy

After you started Site Deploy for the first time, you will be presented with a very empty list of sites, and another empty list of servers on the first tab.

Later, it could look like this (first server anonymized):

List of servers

The first thing you should do is to create a server. Therefore, switch to the servers tab and click “Add server...”.

Creating the server configuration

General settings

Add server dialog, general settings

Let’s look at all the options:

  • UUID

    All servers and sites are identified by a UUID. It cannot be changed in the GUI. In case you really need to change it, just edit the configuration XML file (~/.site-deploy on Linux, ~\Application Data\Site Deploy on Windows XP, ~\AppData\Roaming\Site Deploy on Windows Vista or newer).

  • Displayed name

    This name will appear in the servers list. It is only used in the GUI.

  • Server type

    Here you can choose among all supported server types. In this example, we will configure an Apache 2.x server that runs on a Debian-like platform. The platform distinction is important so that Site Deploy knows in which directories to look for configuration files (in this example, Apache’s configuration is in /etc/apache2).

  • Hostname

    The hostname on which the server is reachable on your network. You may specify a domain name or an IP.

    This setting is used to connect via SSH, and for the “open site in browser” feature of the GUI.

  • SSH username and password

    Site Deploy relies on SSH access to the remote server in order to execute commands (and to upload via SFTP if necessary).

    This restriction might be removed in a later version as Windows platforms usually don’t have a SSH server installed.

    You may optionally enter the SSH password so that you don’t have to type it in everytime. Be warned: The password is stored in plaintext in the configuration file! A later version might introduce keyring support.

Sites and upload settings

Add server dialog, sites and upload settings
  • Directory for uploaded sites

    Specify to which directory sites should be uploaded. In general, something in /var is recommended.

    Important: You must create that directory on the server yourself! Ensure that permissions are correct so that the web server can access these files. In this example, I chose “www-data” (the Apache user) as the owner of anything that belongs to uploaded sites. So the sites directory /var/www/site-deploy-sites should also be readable by “www-data”.

  • Upload access type

    Nothing to chose from yet - only SFTP is supported yet. Of course subject to change.

  • Username for uploads

    As stated above, this is the user that is applied as owner to everything belong to uploaded sites.

  • Group name for uploads

    The GUI already warns you about Ubuntu-like platforms that don’t allow remote login by root. In that case, you might want to set the user (owner) to the user that has sudo rights, and the group name to “www-data”. But in this example, I’m using a Debian 6.0 (squeeze) server which allows me to login as “root” via SSH.

Configuration upload settings

Add server dialog, configuration upload settings
  • Configuration upload access type

    “Again?” you might ask. But these are different settings, applying only to the upload of configuration files. In our Apache example, Site Deploy will upload a single configuration file to some place in /etc/apache2, containing the configuration for all sites on named Apache server that were deployed using Site Deploy.

  • Username and group name for configuration uploads

    Configuration files usually get more protection than site files, so we choose “root” as owner here.

As you can see above, all necessary fields are filled, so you could add the server now. But let us look at the last tab with Apache-specific settings first.

Apache-specific settings

Add server dialog, Apache-specific settings
  • Configuration filename

    When creating a new server, this will be set to a sane default. In the case of Apache, a filename of “site-deploy.autogen.conf” is chosen. Common sense should tell you that “autogen” is a sign of an automatically generated file which you shouldn’t touch. This remark can also be found inside the file, should common sense be unavailable.

  • Globally include configuration

    If you tick this setting, the Apache handler will upload the configuration file to /etc/apache2/conf.d, which means the configuration is globally included in Apache’s configuration automatically. But it also means that the sites uploaded by Site Deploy are available on all “Apache sites”. So if you have set up Apache with multiple virtual hosts, deployed sites will be available on all virtual hostnames (maybe or maybe not what you want!).

    Unticking this setting means that the configuration file is uploaded /etc/apache2, where it remains unused until you manually include it somewhere in the Apache configuration, e.g. in /etc/apache2/sites-enabled/000-default.

    As the setting is unchecked in our example, we now need to add the line

    Include "site-deploy.autogen.conf"
    

    in our Apache site configuration (called /etc/apache2/sites-enabled/000-default by default).

Creating the site configuration

In this example, we will deploy a simple Django site to the Apache server we configured above. Mind that by creating the server in our servers list did not actually change anything on the server yet. We will see later what happens during deployment of a site.

Let’s first define the term “site”. A site is something (usually a web application or web site) mounted under a certain relative URL on one or more web servers. You will see below how Site Deploy implements this definition and what the difference between relative and absolute URL is.

General settings

Add site dialog, general settings
  • UUID

    Sites are also identified by UUIDs. This identifier is also used when uploading sites to a server. For each site, the directory will be <sites directory>/<site's uuid>. That site directory probably contains further subdirectories, e.g. Django sites are Python modules so they must live in <site directory>/<Django site module name>.

    Other than that, site UUIDs are referenced by servers. Site Deploy keeps track of which sites are currently deployed on which server(s). This enables the software to rewrite the server configuration for multiple deployed sites correctly, even if only one site is getting uploaded at a time (implementation detail, don’t worry about this if you don’t understand it).

  • Displayed name

    Again, this is just the “friendly name” as shown in the sites list and in log messages. It is only used by the GUI.

  • Site type

    Choose one of the supported site types here. In this example, we will configure a Django 1.3 site that comes with the source code of Site Deploy. So if you are following this like a tutorial, make sure you have the test directory of the source code. You can download Site Deploy using Bazaar (bzr co lp:site-deploy --lightweight).

  • Absolute URL

    Depending on the site type, this might be relevant as the GUI already tells you. If you are using multiple web servers on the same host, for example nginx as frontend and Apache as backend, make sure that the absolute URL is correct. For instance, if nginx’s location /django-sites/ is proxied to Apache’s /, the absolute URL must be /django-sites/todosite/ in the shown example. Or put differently: The absolute URL is the public URL which users have to type into their browser.

  • Relative URL

    Warning: Even if these settings are called absolute/relative URL, full URLs like http://my.favorite.cdn/static/ are not possible. Might be implemented in the future if it’s helpful in some way. Wording might also change to “URL path” later...

    As opposed to the absolute URL, the relative URL is the “mount URL”, i.e. the URL path on which the site should be accessible on the selected web server. So, using the proxy example from above again, if you’re deploying a site to the Apache backend server, you must remove /django-sites from the absolute URL. In our example, we only have one server, so both absolute and relative URL path are identical.

    Mind that Site Deploy cares about your URL design, so trailing slashes are significant. As the entered relative URL is /todosite/, the site will not be available under /todosite! This is not possible for all types of sites and servers because of server configuration limitations. Warnings about the applying behavior might get added later (in GUI and documentation).

Packaging settings

Add site dialog, packaging settings

In this tab, I already selected our previously created server “My server”. The selection dialog is straightforward and does not need any explanation. Just one hint: You can select multiple servers in case you want to deploy the site to multiple servers (with the same site configuration!). If you do so and choose to deploy the site, you will be asked to which server(s) (from the selected ones) it should be deployed.

  • Source directory

    This is where your site lives. For example with Django, this must be the project (“Django site”) directory. For static sites, this is a directory containing files that should get served.

    As said above, I chose the Django test site that ships with Site Deploy’s source code. It requires Django 1.3 (beta 1 or newer) on the server (for older versions it will still start up but show you a version conflict error)!

  • Packaging type

    The way your site is packaged and uploaded. Not all packaging types apply to all types of sites/servers. For example, WAR files are of course not Django-compatible.

    Sure, for big sites, ZIP or direct upload is not very efficient. Maybe there will be rsync support in the future.

    We choose the ZIP packaging type here. It will archive our Django site, upload it to the server (remember, we chose SFTP for site uploads in the server’s configuration), and extract it there. Unfortunately, this requires the zip program on both this computer and the server. If you’re using Linux, installation should be easy (à la apt-get install zip, often preinstalled) - on Windows, please use the gnuwin32 zip package (put the bin directory on your PATH).

Static file serving

Add site dialog, static file serving settings

This settings tab allows you to specify URL paths under which files are served statically. The server configuration is server-specific (e.g. alias directive). You can choose from two different types:

  • Site-relative path

    The path of the directory containing static files must be given relative to the site’s directory (remember, the one ending with the site UUID).

    In our Django example, the site has static files in the static directory, and the Django setting STATIC_URL is set to /static/. Thus I created a site-relative static serving entry which serves django_simple_todo_list/static (this is a directory, don’t mind about trailing slashes) under the URL /static/. Note that this URL path is always relative to the site, so as the site is on /todosite/, Site Deploy derives the static URL as /todosite/static/ (no double slash).

  • Absolute path

    If you want to serve certain files from the server host’s filesystem, you can also define an absolute path to a directory containing static files.

Django-specific settings

Sites of type Django 1.2+ require some extra settings. For an explanation of specific settings for other site types, see the respective tutorial in this documentation.

Add site dialog, Django-specific settings

For Django, you can change the following settings:

  • Project name

    Also called Django site name. This is simply the name of the Django site’s top directory, the one that contains the root URLconf and settings.py by default. Click “Set from source directory” to fill this automatically with the selected source directory name.

  • Settings sub-module

    Often you want different settings on the production server. Therefore you could create a file settings_production.py with the content

    from .settings import *
    # Production settings go here...
    

    and then enter settings_production as settings sub-module name instead.

  • Absolute URL compatibility

    This is about a problem inherent to all Django 1.2 sites - they are all meant to be accessed on /. Manually deploying a Django site using mod_wsgi’s WSGIScriptAlias will soon make you aware of problems with HTTP redirects and URL resolution (e.g. {% url ... %} tag).

    Site Deploy offers a reliable workaround for this by wrapping the specified settings module. The setting FORCE_SCRIPT_NAME is used to specify the absolute URL, and other settings like STATIC_URL are prefixed correctly. Check out the Django sites chapter for a more detailed explanation.

    In our example, we didn’t care about absolute URLs when writing the Django test application, so we leave the compatibility unticked. Check the option if you have your own workaround or just want it because the site deployed to / anyway.

  • virtualenv

    If you provide your Django site with a virtual environment, Python and all dependencies are installed into that environment. This needs special configuration on the server so that the environment instead of the global Python installation is used - but Site Deploy automatically configures that for you. The only thing you have to ensure is that the virtualenv is made for the target system because they might not be compatible, e.g. a virtualenv created on Windows may not work on Linux (at the time of writing)!

Deploying the site

Procedure

So now we saved both the server and a Django-powered test site, deployment is as easy as a few mouse clicks. Select the site from the list and click on “Deploy...”. If you only selected one server for your site, it will automatically be selected as the deployment target. Nothing more to do here, so click “Deploy now”.

A task dialog will open up, showing you the rough progress of the deployment.

Result

If deployment is successful, output will be something like this:

Packaging 'Django test site'
Using filename 'c:\[...]\temp\site-deploy-packaged-site-7807872c-5023-4d15-b01e-23456f7cdd95.zip'
Creating directory structure for sites on server 'My server'
Removing sites from server 'My server'
Uploading site 'Django test site' to server 'My server'
Creating and uploading configuration for sites to server 'My server'
Writing configuration file '/etc/apache2/site-deploy.autogen.conf' on server 'My server'
Writing extra configuration file '/var/www/site-deploy-sites/7807872c-5023-4d15-b01e-23456f7cdd95/wsgi_autogen.py' on server 'My server'
Writing extra configuration file '/var/www/site-deploy-sites/7807872c-5023-4d15-b01e-23456f7cdd95/django_simple_todo_list/settings_site_deploy_absolute_url_compatibility.py' on server 'My server'
Restarting server 'My server'

Most of this is self-explaining. The file wsgi_autogen.py was created because on Apache, the mod_wsgi module is used for deploying Django sites. And you might be scared about “Removing sites from server” - this only means that the site that should be deployed is removed first (before packaging and uploading it again). By the way, you can deploy multiple sites at once (but only to servers that are selected for all of them).

Now it’s a good idea to log in to your server and look at what Site Deploy created. As we didn’t include the Apache configuration file /etc/apache2/site-deploy.autogen.conf in the Apache configuration yet, it’s time to do so. Then you can select the site from the list and click “Open in browser...” (or just type in the URL http://<server hostname>/todosite/ yourself). If everything went well, it will look like this:

Working Django test site

With the absolute URL compatibility workaround in place, the site should correctly redirect you to http://<server hostname>/todosite/todo, and then to http://<server hostname>/todosite/login/?next=/todosite/todo/ because you are not yet logged in.

But most probably something went wrong at the first attempt. Here are some items to check:

  • mod_wsgi is required and must be enabled (apt-get install libapache2-mod-wsgi; a2enmod wsgi)
  • Django 1.3 is required for the test site (that version should be in package repositories soon, so you can use apt-get install python-django)
  • Include the configuration file as aforementioned