--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/parts/django/docs/topics/install.txt Sat Jan 08 11:20:57 2011 +0530
@@ -0,0 +1,298 @@
+=====================
+How to install Django
+=====================
+
+This document will get you up and running with Django.
+
+Install Python
+==============
+
+Being a Python Web framework, Django requires Python.
+
+It works with any Python version from 2.4 to 2.7 (due to backwards
+incompatibilities in Python 3.0, Django does not currently work with
+Python 3.0; see :doc:`the Django FAQ </faq/install>` for more
+information on supported Python versions and the 3.0 transition).
+
+Get Python at http://www.python.org. If you're running Linux or Mac OS X, you
+probably already have it installed.
+
+.. admonition:: Django on Jython
+
+ If you use Jython_ (a Python implementation for the Java platform), you'll
+ need to follow a few additional steps. See :doc:`/howto/jython` for details.
+
+.. _jython: http://jython.org/
+
+Install Apache and mod_wsgi
+=============================
+
+If you just want to experiment with Django, skip ahead to the next section;
+Django includes a lightweight Web server you can use for testing, so you won't
+need to set up Apache until you're ready to deploy Django in production.
+
+If you want to use Django on a production site, use Apache with `mod_wsgi`_.
+mod_wsgi is similar to mod_perl -- it embeds Python within Apache and loads
+Python code into memory when the server starts. Code stays in memory throughout
+the life of an Apache process, which leads to significant performance gains over
+other server arrangements. Make sure you have Apache installed, with the
+mod_wsgi module activated. Django will work with any version of Apache that
+supports mod_wsgi.
+
+See :doc:`How to use Django with mod_wsgi </howto/deployment/modwsgi>` for
+information on how to configure mod_wsgi once you have it installed.
+
+If you can't use mod_wsgi for some reason, fear not: Django supports many other
+deployment options. A great second choice is :doc:`mod_python
+</howto/deployment/modpython>`, the predecessor to mod_wsgi. Additionally, Django
+follows the WSGI_ spec, which allows it to run on a variety of server platforms.
+See the `server-arrangements wiki page`_ for specific installation instructions
+for each platform.
+
+.. _Apache: http://httpd.apache.org/
+.. _mod_wsgi: http://code.google.com/p/modwsgi/
+.. _WSGI: http://www.python.org/dev/peps/pep-0333/
+.. _server-arrangements wiki page: http://code.djangoproject.com/wiki/ServerArrangements
+
+.. _database-installation:
+
+Get your database running
+=========================
+
+If you plan to use Django's database API functionality, you'll need to make
+sure a database server is running. Django supports many different database
+servers and is officially supported with PostgreSQL_, MySQL_, Oracle_ and
+SQLite_ (although SQLite doesn't require a separate server to be running).
+
+In addition to the officially supported databases, there are backends provided
+by 3rd parties that allow you to use other databases with Django:
+
+* `Sybase SQL Anywhere`_
+* `IBM DB2`_
+* `Microsoft SQL Server 2005`_
+* Firebird_
+* ODBC_
+
+The Django versions and ORM features supported by these unofficial backends
+vary considerably. Queries regarding the specific capabilities of these
+unofficial backends, along with any support queries, should be directed to the
+support channels provided by each 3rd party project.
+
+In addition to a database backend, you'll need to make sure your Python
+database bindings are installed.
+
+* If you're using PostgreSQL, you'll need the psycopg_ package. Django supports
+ both version 1 and 2. (When you configure Django's database layer, specify
+ either ``postgresql`` [for version 1] or ``postgresql_psycopg2`` [for version 2].)
+ You might want to refer to our :ref:`PostgreSQL notes <postgresql-notes>` for
+ further technical details specific to this database.
+
+ If you're on Windows, check out the unofficial `compiled Windows version`_.
+
+* If you're using MySQL, you'll need MySQLdb_, version 1.2.1p2 or higher. You
+ will also want to read the database-specific :ref:`notes for the MySQL
+ backend <mysql-notes>`.
+
+* If you're using SQLite and Python 2.4, you'll need pysqlite_. Use version
+ 2.0.3 or higher. Python 2.5 ships with an SQLite wrapper in the standard
+ library, so you don't need to install anything extra in that case. Please
+ read the :ref:`SQLite backend notes <sqlite-notes>`.
+
+* If you're using Oracle, you'll need a copy of cx_Oracle_, but please
+ read the database-specific :ref:`notes for the Oracle backend <oracle-notes>`
+ for important information regarding supported versions of both Oracle and
+ ``cx_Oracle``.
+
+* If you're using an unofficial 3rd party backend, please consult the
+ documentation provided for any additional requirements.
+
+If you plan to use Django's ``manage.py syncdb`` command to
+automatically create database tables for your models, you'll need to
+ensure that Django has permission to create and alter tables in the
+database you're using; if you plan to manually create the tables, you
+can simply grant Django ``SELECT``, ``INSERT``, ``UPDATE`` and
+``DELETE`` permissions. On some databases, Django will need
+``ALTER TABLE`` privileges during ``syncdb`` but won't issue
+``ALTER TABLE`` statements on a table once ``syncdb`` has created it.
+
+If you're using Django's :doc:`testing framework</topics/testing>` to test database queries,
+Django will need permission to create a test database.
+
+.. _PostgreSQL: http://www.postgresql.org/
+.. _MySQL: http://www.mysql.com/
+.. _psycopg: http://initd.org/pub/software/psycopg/
+.. _compiled Windows version: http://stickpeople.com/projects/python/win-psycopg/
+.. _MySQLdb: http://sourceforge.net/projects/mysql-python
+.. _SQLite: http://www.sqlite.org/
+.. _pysqlite: http://trac.edgewall.org/wiki/PySqlite
+.. _cx_Oracle: http://cx-oracle.sourceforge.net/
+.. _Oracle: http://www.oracle.com/
+.. _Sybase SQL Anywhere: http://code.google.com/p/sqlany-django/
+.. _IBM DB2: http://code.google.com/p/ibm-db/
+.. _Microsoft SQL Server 2005: http://code.google.com/p/django-mssql/
+.. _Firebird: http://code.google.com/p/django-firebird/
+.. _ODBC: http://code.google.com/p/django-pyodbc/
+.. _removing-old-versions-of-django:
+
+Remove any old versions of Django
+=================================
+
+If you are upgrading your installation of Django from a previous version,
+you will need to uninstall the old Django version before installing the
+new version.
+
+If you installed Django using ``setup.py install``, uninstalling
+is as simple as deleting the ``django`` directory from your Python
+``site-packages``.
+
+If you installed Django from a Python egg, remove the Django ``.egg`` file,
+and remove the reference to the egg in the file named ``easy-install.pth``.
+This file should also be located in your ``site-packages`` directory.
+
+.. admonition:: Where are my ``site-packages`` stored?
+
+ The location of the ``site-packages`` directory depends on the operating
+ system, and the location in which Python was installed. To find out your
+ system's ``site-packages`` location, execute the following:
+
+ .. code-block:: bash
+
+ python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()"
+
+ (Note that this should be run from a shell prompt, not a Python interactive
+ prompt.)
+
+.. _install-django-code:
+
+Install the Django code
+=======================
+
+Installation instructions are slightly different depending on whether you're
+installing a distribution-specific package, downloading the latest official
+release, or fetching the latest development version.
+
+It's easy, no matter which way you choose.
+
+Installing a distribution-specific package
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Check the :doc:`distribution specific notes </misc/distributions>` to see if your
+platform/distribution provides official Django packages/installers.
+Distribution-provided packages will typically allow for automatic installation
+of dependencies and easy upgrade paths.
+
+.. _installing-official-release:
+
+Installing an official release
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ 1. Download the latest release from our `download page`_.
+
+ 2. Untar the downloaded file (e.g. ``tar xzvf Django-NNN.tar.gz``,
+ where ``NNN`` is the version number of the latest release).
+ If you're using Windows, you can download the command-line tool
+ bsdtar_ to do this, or you can use a GUI-based tool such as 7-zip_.
+
+ 3. Change into the directory created in step 2 (e.g. ``cd Django-NNN``).
+
+ 4. If you're using Linux, Mac OS X or some other flavor of Unix, enter
+ the command ``sudo python setup.py install`` at the shell prompt.
+ If you're using Windows, start up a command shell with administrator
+ privileges and run the command ``setup.py install``.
+
+These commands will install Django in your Python installation's
+``site-packages`` directory.
+
+.. _bsdtar: http://gnuwin32.sourceforge.net/packages/bsdtar.htm
+.. _7-zip: http://www.7-zip.org/
+
+.. _installing-development-version:
+
+Installing the development version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. admonition:: Tracking Django development
+
+ If you decide to use the latest development version of Django,
+ you'll want to pay close attention to `the development timeline`_,
+ and you'll want to keep an eye on `the list of
+ backwards-incompatible changes`_. This will help you stay on top
+ of any new features you might want to use, as well as any changes
+ you'll need to make to your code when updating your copy of Django.
+ (For stable releases, any necessary changes are documented in the
+ release notes.)
+
+.. _the development timeline: http://code.djangoproject.com/timeline
+.. _the list of backwards-incompatible changes: http://code.djangoproject.com/wiki/BackwardsIncompatibleChanges
+
+If you'd like to be able to update your Django code occasionally with the
+latest bug fixes and improvements, follow these instructions:
+
+1. Make sure that you have Subversion_ installed, and that you can run its
+ commands from a shell. (Enter ``svn help`` at a shell prompt to test
+ this.)
+
+2. Check out Django's main development branch (the 'trunk') like so:
+
+ .. code-block:: bash
+
+ svn co http://code.djangoproject.com/svn/django/trunk/ django-trunk
+
+3. Next, make sure that the Python interpreter can load Django's code. There
+ are various ways of accomplishing this. One of the most convenient, on
+ Linux, Mac OSX or other Unix-like systems, is to use a symbolic link:
+
+ .. code-block:: bash
+
+ ln -s WORKING-DIR/django-trunk/django SITE-PACKAGES-DIR/django
+
+ (In the above line, change ``SITE-PACKAGES-DIR`` to match the location of
+ your system's ``site-packages`` directory, as explained in the
+ "Where are my ``site-packages`` stored?" section above. Change WORKING-DIR
+ to match the full path to your new ``django-trunk`` directory.)
+
+ Alternatively, you can define your ``PYTHONPATH`` environment variable
+ so that it includes the ``django-trunk`` directory. This is perhaps the
+ most convenient solution on Windows systems, which don't support symbolic
+ links. (Environment variables can be defined on Windows systems `from the
+ Control Panel`_.)
+
+ .. admonition:: What about Apache and mod_python?
+
+ If you take the approach of setting ``PYTHONPATH``, you'll need to
+ remember to do the same thing in your Apache configuration once you
+ deploy your production site. Do this by setting ``PythonPath`` in your
+ Apache configuration file.
+
+ More information about deployment is available, of course, in our
+ :doc:`How to use Django with mod_python </howto/deployment/modpython>`
+ documentation.
+
+4. On Unix-like systems, create a symbolic link to the file
+ ``django-trunk/django/bin/django-admin.py`` in a directory on your system
+ path, such as ``/usr/local/bin``. For example:
+
+ .. code-block:: bash
+
+ ln -s WORKING-DIR/django-trunk/django/bin/django-admin.py /usr/local/bin
+
+ (In the above line, change WORKING-DIR to match the full path to your new
+ ``django-trunk`` directory.)
+
+ This simply lets you type ``django-admin.py`` from within any directory,
+ rather than having to qualify the command with the full path to the file.
+
+ On Windows systems, the same result can be achieved by copying the file
+ ``django-trunk/django/bin/django-admin.py`` to somewhere on your system
+ path, for example ``C:\Python24\Scripts``.
+
+You *don't* have to run ``python setup.py install``, because you've already
+carried out the equivalent actions in steps 3 and 4.
+
+When you want to update your copy of the Django source code, just run the
+command ``svn update`` from within the ``django-trunk`` directory. When you do
+this, Subversion will automatically download any changes.
+
+.. _`download page`: http://www.djangoproject.com/download/
+.. _Subversion: http://subversion.tigris.org/
+.. _from the Control Panel: http://www.microsoft.com/resources/documentation/windows/xp/all/proddocs/en-us/sysdm_advancd_environmnt_addchange_variable.mspx