tox: Update versions of Django to be tested

[patchwork] / docs / INSTALL

diff --git a/docs/INSTALL b/docs/INSTALL
index 0ed2cea78e3afa18fddca6d370c1c3a1edc00515..bd9577023deed4e75d72be67575e0599f40f7e62 100644 (file)
--- a/docs/INSTALL
+++ b/docs/INSTALL
@@ -3,16 +3,18 @@ Deploying Patchwork
 Patchwork uses the django framework - there is some background on deploying
 django applications here:
 
 Patchwork uses the django framework - there is some background on deploying
 django applications here:
 

- http://www.djangobook.com/en/1.0/chapter20/
+ http://www.djangobook.com/en/2.0/chapter12/

 
 You'll need the following (applications used for patchwork development are
 in brackets):
 
   * A python interpreter
 
 You'll need the following (applications used for patchwork development are
 in brackets):
 
   * A python interpreter

-  * django
+  * django >= 1.5

   * A webserver (apache)
   * mod_python or flup
   * A webserver (apache)
   * mod_python or flup

-  * A database server (postgresql)
+  * A database server (postgresql, mysql)
+  * relevant python modules for the database server (e.g: python-mysqldb)
+

 
 1. Database setup
 
 
 1. Database setup
 


@@ -21,7 +23,7 @@ in brackets):
     either, email me.
 
     For the following commands, a $ prefix signifies that the command should be
     either, email me.
 
     For the following commands, a $ prefix signifies that the command should be

-    entered at your shell prompt, and a > prefix signifies the commant-line
+    entered at your shell prompt, and a > prefix signifies the command-line

     client for your sql server (psql or mysql)
 
     Create a database for the system, add accounts for two system users: the
     client for your sql server (psql or mysql)
 
     Create a database for the system, add accounts for two system users: the


@@ -29,7 +31,10 @@ in brackets):
     user that your mail server runs as). On Ubuntu these are
     www-data and nobody, respectively.
 
     user that your mail server runs as). On Ubuntu these are
     www-data and nobody, respectively.
 

-    For PostgreSQL
+    As an alternative, you can use password-based login and a single database
+    account. This is described further down.
+
+    For PostgreSQL (ident-based)

 
         $ createdb patchwork
         $ createuser www-data
 
         $ createdb patchwork
         $ createuser www-data


@@ -39,126 +44,173 @@ in brackets):
           will only be accessible for processes running as the same username.
           This means that no passwords need to be set.
 
           will only be accessible for processes running as the same username.
           This means that no passwords need to be set.
 

-     For MySQL:
+    For PostgreSQL (password-based)
+
+        $ createuser -PE patchwork
+        $ createdb -O patchwork patchwork
+
+        Once that is done, you need to tell Django about the new Database
+        settings, using local_settings.py (see below) to override the defaults
+        in settings.py:
+
+        DATABASES = {
+            'default': {
+                'ENGINE': 'django.db.backends.postgresql_psycopg2',
+                'HOST': 'localhost',
+                'PORT': '',
+                'USER': 'patchwork',
+                'PASSWORD': 'my_secret_password',
+                'NAME': 'patchwork',
+            },
+        }
+
+    For MySQL:

         $ mysql
         $ mysql

-        > CREATE DATABASE 'patchwork';
+        > CREATE DATABASE patchwork CHARACTER SET utf8;

         > CREATE USER 'www-data'@'localhost' IDENTIFIED BY '<password>';
         > CREATE USER 'nobody'@'localhost' IDENTIFIED BY '<password>';
 
         > CREATE USER 'www-data'@'localhost' IDENTIFIED BY '<password>';
         > CREATE USER 'nobody'@'localhost' IDENTIFIED BY '<password>';
 

+       Once that is done, you need to tell Django about the new Database
+       settings, using local_settings.py (see below) to override the defaults
+       in settings.py:
+
+        DATABASES = {
+            'default': {
+                'ENGINE': 'django.db.backends.mysql',
+                'HOST': 'localhost',
+                'PORT': '',
+                'USER': 'patchwork',
+                'PASSWORD': 'my_secret_password',
+                'NAME': 'patchwork',
+                'TEST_CHARSET': 'utf8',
+            },
+        }
+
+        TEST_CHARSET is used when creating tables for the test suite. Without
+        it, tests checking for the correct handling of non-ASCII characters
+        fail.
+
+

 2. Django setup
 
 2. Django setup
 

-        Set up some initial directories in the patchwork base directory:
+    Set up some initial directories in the patchwork base directory:

 
 

-         mkdir -p lib/packages lib/python
+      mkdir -p lib/packages lib/python

 
 

-        lib/packages is for stuff we'll download, lib/python is to add
-        to our python path. We'll symlink python modules into lib/python.
+    lib/packages is for stuff we'll download; lib/python is to add
+    to our python path. We'll symlink python modules into lib/python.

 
 

-        At the time of release, patchwork depends on django version 1.0 or
-        later. Your distro probably provides this. If not, do a:
+    At the time of release, patchwork depends on django version 1.5 or
+    later. Your distro probably provides this. If not, do a:

 
 

-         cd lib/packages
-         svn checkout http://code.djangoproject.com/svn/django/tags/releases/1.2
-         cd ../python
-         ln -s ../packages/django/django ./django
+      cd lib/packages
+      git clone https://github.com/django/django.git -b stable/1.5.x
+      cd ../python
+      ln -s ../packages/django/django ./django

 
 

-        We also use the django-registration infrastructure from
-        http://bitbucket.org/ubernostrum/django-registration/. Your distro
-        may provide the django-registration python module (in Ubuntu/Debian it's
-        called 'python-django-registration'). If not, download the module
-        and symlink it to lib/python/ :
+    The patchwork/settings/*.py files contain default settings for patchwork,
+    you'll need to configure settings for your own setup.

 
 

-         cd lib/packages/
-         hg clone http://bitbucket.org/ubernostrum/django-registration/
-         cd ../python
-         ln -s ../lib/packages/django-registration/registration ./registration
+    Rather than editing these files (which will cause conflicts when you
+    update the base patchwork code), create a file 'production.py', based on
+    the example:

 
 

-        We also use some Javascript libraries:
+       cp patchwork/settings/production.example.py \
+          patchwork/settings/production.py

 
 

-         cd lib/packages
-         mkdir jquery
-         cd jquery
-         wget http://jqueryjs.googlecode.com/files/jquery-1.3.min.js
-         wget http://www.isocra.com/articles/jquery.tablednd_0_5.js.zip
-         unzip jquery.tablednd_0_5.js.zip jquery.tablednd_0_5.js
-         cd ../../../htdocs/js/
-         ln -s ../../lib/packages/jquery/jquery-1.3.min.js ./
-         ln -s ../../lib/packages/jquery/jquery.tablednd_0_5.js ./
+    and override or add settings as necessary. You'll need to define the
+    following:

 
 

-        The settings.py file contains default settings for patchwork, you'll
-        need to configure settings for your own setup.
+      SECRET_KEY
+      ADMINS
+      DATABASES
+      TIME_ZONE
+      LANGUAGE_CODE
+      DEFAULT_FROM_EMAIL
+      NOTIFICATION_FROM_EMAIL

 
 

-        Rather than edit settings.py, create a file 'local_settings.py', and
-        override or add settings as necessary. You'll need to define the
-        following:
+    You can generate the SECRET_KEY with the following python code:

 
 

-          SECRET_KEY
-          ADMINS
-          TIME_ZONE
-          LANGUAGE_CODE
+      import string, random
+      chars = string.letters + string.digits + string.punctuation
+      print repr("".join([random.choice(chars) for i in range(0,50)]))

 
 

-        You can generate the SECRET_KEY with the following python code:
+    If you wish to enable the XML-RPC interface, add the following to
+    your local_settings.py file:

 
 

-          import string, random
-          chars = string.letters + string.digits + string.punctuation
-          print repr("".join([random.choice(chars) for i in range(0,50)]))
+      ENABLE_XMLRPC = True

 
 

-        If you have patchwork installed in somewhere other than /srv/patchwork,
-        you'll also need to define:
+    Then, get patchwork to create its tables in your configured database:

 
 

-          MEDIA_ROOT
-          TEMPLATE_DIRS
+     PYTHONPATH=lib/python ./manage.py syncdb

 
 

-        If you wish to enable the XML-RPC interface, add the following to
-        your local_settings.py file:
+    and initialise the static content:

 
 

-          ENABLE_XMLRPC = True
+     PYTHONPATH=lib/python ./manage.py collectstatic

 
 

-        Then, get patchwork to create its tables in your configured database:
+    You'll also need to load the initial tags and states into the
+    patchwork database:

 
 

-         cd apps/
-         PYTHONPATH=../lib/python ./manage.py syncdb
+     PYTHONPATH=lib/python ./manage.py loaddata default_tags default_states

 
 

-        And add privileges for your mail and web users:
+    Finally, add privileges for your mail and web users. This is only needed if
+    you use the ident-based approach. If you use password-based database
+    authentication, you can skip this step.

 
 

-        Postgresql:
-          psql -f lib/sql/grant-all.postgres.sql patchwork
+    Postgresql:
+      psql -f lib/sql/grant-all.postgres.sql patchwork

 
 

-        MySQL:
-          mysql patchwork < lib/sql/grant-all.mysql.sql
+    MySQL:
+      mysql patchwork < lib/sql/grant-all.mysql.sql

 
 
 3. Apache setup
 
 
 
 3. Apache setup
 

-Example apache configuration files are in lib/apache/.
+    Example apache configuration files are in lib/apache2/.
+
+    wsgi:
+
+        django has built-in support for WSGI, which supersedes the fastcgi
+        handler. It is thus the preferred method to run patchwork.
+
+        The necessary configuration for Apache2 may be found in
+
+         lib/apache2/patchwork.wsgi.conf.
+
+        You will need to install/enable mod_wsgi for this to work:
+
+         a2enmod wsgi
+         apache2ctl restart
+

 
 

-mod_python:
+     mod_python:

 
 

-        This should be the simpler of the two to set up. An example apache
-        configuration file is in:
+        An example apache configuration file for mod_python is in:

 
 

-          lib/apache/patchwork.mod_python.conf
+          lib/apache2/patchwork.mod_python.conf

 
         However, mod_python and mod_php may not work well together. So, if your
         web server is used for serving php files, the fastcgi method may suit
         instead.
 
 
         However, mod_python and mod_php may not work well together. So, if your
         web server is used for serving php files, the fastcgi method may suit
         instead.
 

-fastcgi:
+
+    fastcgi:

 
         django has built-in support for fastcgi, which requires the
         'flup' python module. An example configuration is in:
 
 
         django has built-in support for fastcgi, which requires the
         'flup' python module. An example configuration is in:
 

-          lib/apache/patchwork.fastcgi.conf
+          lib/apache2/patchwork.fastcgi.conf

 
         - this also requires the mod_rewrite apache module to be loaded.
 
         Once you have apache set up, you can start the fastcgi server with:
 
 
         - this also requires the mod_rewrite apache module to be loaded.
 
         Once you have apache set up, you can start the fastcgi server with:
 

-          cd /srv/patchwork/apps
+          cd /srv/patchwork/

           ./manage.py runfcgi method=prefork \
                               socket=/srv/patchwork/var/fcgi.sock \
                               pidfile=/srv/patchwork/var/fcgi.pid
 
           ./manage.py runfcgi method=prefork \
                               socket=/srv/patchwork/var/fcgi.sock \
                               pidfile=/srv/patchwork/var/fcgi.pid
 

+

 4. Configure patchwork
     Now, you should be able to administer patchwork, by visiting the
     URL:
 4. Configure patchwork
     Now, you should be able to administer patchwork, by visiting the
     URL:


@@ -168,14 +220,16 @@ fastcgi:
     You'll probably want to do the following:
 
       * Set up your projects
     You'll probably want to do the following:
 
       * Set up your projects

-      * Configure your website address (in the Sites) section of the admin
+      * Configure your website address (in the Sites) section

 
 

+    

 5. Subscribe a local address to the mailing list
 
 5. Subscribe a local address to the mailing list
 

-     You will need an email address for patchwork to receive email on - for
-     example - patchwork@, and this address will need to be subscribed to the
-     list. Depending on the mailing list, you will probably need to confirm the
-     subscription - temporarily direct the alias to yourself to do this.
+    You will need an email address for patchwork to receive email on - for
+    example - patchwork@, and this address will need to be subscribed to the
+    list. Depending on the mailing list, you will probably need to confirm the
+    subscription - temporarily direct the alias to yourself to do this.
+

 
 6. Setup your MTA to deliver mail to the parsemail script
 
 
 6. Setup your MTA to deliver mail to the parsemail script
 


@@ -183,14 +237,48 @@ fastcgi:
     directory. (Note, do not use the parsemail.py script directly). Something
     like this in /etc/aliases is suitable for postfix:
 
     directory. (Note, do not use the parsemail.py script directly). Something
     like this in /etc/aliases is suitable for postfix:
 

-      patchwork: "|/srv/patchwork/apps/patchwork/bin/parsemail.sh"
+      patchwork: "|/srv/patchwork/patchwork/bin/parsemail.sh"

 
     You may need to customise the parsemail.sh script if you haven't installed
     patchwork in /srv/patchwork.
 
     Test that you can deliver a patch to this script:
 
 
     You may need to customise the parsemail.sh script if you haven't installed
     patchwork in /srv/patchwork.
 
     Test that you can deliver a patch to this script:
 

-     sudo -u nobody /srv/patchwork/apps/patchwork/bin/parsemail.sh < mail
+     sudo -u nobody /srv/patchwork/patchwork/bin/parsemail.sh < mail
+
+
+7. Set up the patchwork cron script
+
+    Patchwork uses a cron script to clean up expired registrations, and
+    send notifications of patch changes (for projects with this enabled).
+
+    Something like this in your crontab should work:
+
+      # m h  dom mon dow   command
+      */10 * * * * cd patchwork; ./manage.py cron
+
+
+    - the frequency should be the same as the NOTIFICATION_DELAY_MINUTES
+    setting, which defaults to 10 minutes.
+
+
+8. Optional: Configure your VCS to automatically update patches
+
+    The tools directory of the patchwork distribution contains a file
+    named post-receive.hook which is an example git hook that can be
+    used to automatically update patches to the Accepted state when
+    corresponding comits are pushed via git.
+
+    To install this hook, simply copy it to the .git/hooks directory on
+    your server, name it post-receive, and make it executable.
+
+    This sample hook has support to update patches to different states
+    depending on which branch is being pushed to. See the STATE_MAP
+    setting in that file.
+
+    If you are using a system other than git, you can likely write a
+    similar hook using pwclient to update patch state. If you do write
+    one, please contribute it.

 
 
 Some errors:
 
 
 Some errors:


@@ -209,7 +297,7 @@ Some errors:
    to the tables.
 
 * pwclient fails for actions that require authentication, but a username
    to the tables.
 
 * pwclient fails for actions that require authentication, but a username

-  and password is given int ~/.pwclient rc. Server reports "No authentication
+  and password is given in ~/.pwclientrc. Server reports "No authentication

   credentials given".
 
  - if you're using the FastCGI interface to apache, you'll need the
   credentials given".
 
  - if you're using the FastCGI interface to apache, you'll need the