Index: docs/install.txt =================================================================== --- docs/install.txt (revision 6275) +++ docs/install.txt (working copy) @@ -11,59 +11,97 @@ It works with any Python version 2.3 and higher. -Get Python at http://www.python.org. If you're running Linux or Mac OS X, you -probably already have it installed. +Python is available from http://www.python.org. If you are running Linux or +Mac OS X, you probably already have a suitable version installed. If you are +running Windows, you will almost certainly need to download the latest Windows +MSI installer package for your particular machine architecture (Intel x86, +AMD 64 or Itanium). Double-clicking on the MSI file will then begin the +installation process. Install Apache and mod_python ============================= -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 just want to experiment with Django, skip ahead to the next section; +Django includes a lightweight web server you can use for testing, until you're +ready to deploy Django in production. -If you want to use Django on a production site, use Apache with `mod_python`_. -mod_python 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_python module activated. Django requires Apache 2.x and mod_python 3.x. +If you want to use Django on a production site, use the Apache_ web server +with `mod_python`_. mod_python 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. Django +requires Apache 2.x and mod_python 3.x. -See `How to use Django with mod_python`_ for information on how to configure -mod_python once you have it installed. +Apache is available as source code for all major platforms. If you are +running Windows, you will probably be better off `downloading it in binary +form`_ as an MSI package. If you require SSL support, make sure that you +download the 'openssl' version of the installer, not the 'no_ssl' version. +The installer will prompt you to supply basic information such as domain, +server name, administrator email address and port number (normally 80) as part +of the installation procedure, and you will also be able to choose whether +to run Apache as a service. +mod_python should be installed after Apache. It, too, can be compiled from +source or downloaded as a Windows binary installer program. If you do +the latter, be sure to use the version of the installer that matches the +versions of Python and Apache running on your system. After installing, you +will need to edit ``httpd.conf`` and activate mod_python by adding the +following line to the file:: + + LoadModule python_module modules/mod_python.so + +If you can then get Apache to restart successfully, you will be ready to +configure it for use with Django -- see `How to use Django with mod_python`_ +for further details. + If you can't use mod_python for some reason, fear not: 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. +.. admonition:: What about Internet Information Server? + + If you are a Windows user, you may be wondering whether it is possible + to run Django on Microsoft's own web server, IIS. Considerable progress + has been made towards this goal, `summarized on the Django wiki`_, but + the current procedure is not trivial, and some issues remain unresolved. + If you have expertise in IIS and ISAPI extensions, your assistance in + dealing with these issues would be much appreciated! + .. _Apache: http://httpd.apache.org/ .. _mod_python: http://www.modpython.org/ +.. _downloading it in binary form: http://www.apache.org/dyn/closer.cgi/httpd/binaries/win32/ .. _WSGI: http://www.python.org/peps/pep-0333.html .. _How to use Django with mod_python: ../modpython/ .. _server-arrangements wiki page: http://code.djangoproject.com/wiki/ServerArrangements +.. _summarized on the Django wiki: http://code.djangoproject.com/wiki/DjangoOnWindowsWithIISAndSQLServer 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 works with PostgreSQL_, -MySQL_, Oracle_ and SQLite_ (although SQLite doesn't require a separate server -to be running). +make sure that a database is available. Django works with the PostgreSQL_, +MySQL_ and Oracle_ database servers and with the SQLite_ embedded database. +The latter is a good choice if you are just experimenting with Django. -Additionally, you'll need to make sure your Python database bindings are +Additionally, you'll need to make sure that 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].) - If you're on Windows, check out the unofficial `compiled Windows version`_. + If you're on Windows, check out the unofficial `compiled Windows versions`_ + and choose the one that matches your versions of Python and PostgreSQL. * If you're using MySQL, you'll need MySQLdb_, version 1.2.1p2 or higher. You will also want to read the database-specific notes for the `MySQL backend`_. -* If you're using SQLite, you'll need pysqlite_. Use version 2.0.3 or higher. +* If you're using SQLite with Python 2.3 or 2.4, you'll need pysqlite_, version + 2.0.3 or higher. Python 2.5 comes with the necessary SQLite bindings as + standard. If you are running Windows, note that the binary distributions + of pysqlite include SQLite itself, so using one of these will save you + some time. * If you're using Oracle, you'll need cx_Oracle_, version 4.3.1 or higher. @@ -81,7 +119,7 @@ .. _MySQL: http://www.mysql.com/ .. _Django's ticket system: http://code.djangoproject.com/report/1 .. _psycopg: http://initd.org/tracker/psycopg -.. _compiled Windows version: http://stickpeople.com/projects/python/win-psycopg/ +.. _compiled Windows versions: http://stickpeople.com/projects/python/win-psycopg/ .. _MySQLdb: http://sourceforge.net/projects/mysql-python .. _SQLite: http://www.sqlite.org/ .. _pysqlite: http://initd.org/tracker/pysqlite @@ -131,7 +169,7 @@ Check the `distribution specific notes`_ to see if your platform/distribution provides official Django packages/installers. Distribution-provided packages will typically allow for automatic -installation of dependancies and easy upgrade paths. +installation of dependencies and easy upgrade paths. Installing an official release ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -151,7 +189,8 @@ privileges and run the command ``setup.py install``. These commands will install Django in your Python installation's -``site-packages`` directory. +``site-packages`` directory -- see "Where are my ``site-packages`` stored?" +above for information on how to locate this directory. .. _distribution specific notes: ../distributions/ .. _bsdtar: http://gnuwin32.sourceforge.net/packages/bsdtar.htm @@ -163,17 +202,35 @@ 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.) +1. Make sure that you have Subversion_ installed. You can download it + as source and compile it yourself, or use one of the unofficial binary + packages. If you are running Windows, make sure that you download + the binary that matches your version of Apache (2.0 or 2.2), as this + will allow you to then run Apache as a Subversion server if you wish. + If you are a Windows user, you will probably also want to install + TortoiseSVN_, a Subversion client implemented as a Windows shell + extension. -2. Check out Django's main development branch (the 'trunk') like so:: + After installing, make sure that you can run Subversion commands + commands from a shell. Enter ``svn help`` at a shell prompt to test + this. If you are using TortoiseSVN on Windows, make sure that the + *TortoiseSVN* menu is visible in the *File* menu of Windows Explorer. +2. Check out Django's main development branch (the 'trunk') from a + a command shell like so:: + svn co http://code.djangoproject.com/svn/django/trunk/ django-trunk + If you are using TortoiseSVN on Windows, go to the folder within which + you wish to check out the trunk, right-click to bring up the context + menu and select *TortoiseSVN*, followed by *Checkout..*. In the + resulting dialog box, enter http://code.djangoproject.com/svn/django/trunk/ + as the URL of the repository and the name of a new or empty folder as the + checkout directory. + 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:: + Linux, Mac OS X or other Unix-like systems, is to use a symbolic link:: ln -s `pwd`/django-trunk/django SITE-PACKAGES-DIR/django @@ -205,13 +262,17 @@ any directory, rather than having to qualify the command with the full path to the file. -You *don't* have to run ``python setup.py install``, because you've already -carried out the equivalent actions in steps 3 and 4. +You *don't* have to run ``python setup.py install`` here, 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. +command ``svn update`` from within the ``django-trunk`` directory. Or, if +you are using TortoiseSVN on Windows, right-click on this directory and +choose *TortoiseSVN*, followed by *Update*, from the Windows Explorer +context menu. When you do this, Subversion will automatically download any +changes. .. _`download page`: http://www.djangoproject.com/download/ .. _Subversion: http://subversion.tigris.org/ +.. _TortoiseSVN: http://tortoisesvn.tigris.org/ .. _from the Control Panel: http://www.microsoft.com/resources/documentation/windows/xp/all/proddocs/en-us/sysdm_advancd_environmnt_addchange_variable.mspx