docs/INSTALL: Add setup details for patchwork cron script

[patchwork] / docs / INSTALL

diff --git a/docs/INSTALL b/docs/INSTALL
index 0ed2cea78e3afa18fddca6d370c1c3a1edc00515..face0dc832ce22b33eba9f041ca9626a8c022807 100644 (file)
--- a/docs/INSTALL
+++ b/docs/INSTALL
@@ -3,16 +3,17 @@ 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
 


@@ -29,7 +30,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,12 +43,39 @@ 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:
+
+        DATABASE_ENGINE = 'postgresql_psycopg2'
+        DATABASE_NAME = 'patchwork'
+        DATABASE_USER = 'patchwork'
+        DATABASE_PASSWORD = 'my_secret_password
+        DATABASE_HOST = 'localhost'
+        DATABASE_PORT = ''
+
+    For MySQL:

         $ mysql
         > CREATE DATABASE 'patchwork';
         > CREATE USER 'www-data'@'localhost' IDENTIFIED BY '<password>';
         > CREATE USER 'nobody'@'localhost' IDENTIFIED BY '<password>';
 
         $ mysql
         > CREATE DATABASE 'patchwork';
         > 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:
+
+       DATABASE_ENGINE = 'mysql'
+       DATABASE_NAME = 'patchwork'
+       DATABASE_USER = 'root'
+       DATABASE_PASSWORD = 'my_secret_root_password'
+       DATABSE_HOST = 'localhost'
+       DATABASE_PORT = ''
+

 2. Django setup
 
         Set up some initial directories in the patchwork base directory:
 2. Django setup
 
         Set up some initial directories in the patchwork base directory:


@@ -54,37 +85,14 @@ in brackets):
         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
+        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
         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
+         git clone https://github.com/django/django.git -b stable/1.5.x

          cd ../python
          ln -s ../packages/django/django ./django
 
          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/ :
-
-         cd lib/packages/
-         hg clone http://bitbucket.org/ubernostrum/django-registration/
-         cd ../python
-         ln -s ../lib/packages/django-registration/registration ./registration
-
-        We also use some Javascript libraries:
-
-         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 ./
-

         The settings.py file contains default settings for patchwork, you'll
         need to configure settings for your own setup.
 
         The settings.py file contains default settings for patchwork, you'll
         need to configure settings for your own setup.
 


@@ -96,6 +104,8 @@ in brackets):
           ADMINS
           TIME_ZONE
           LANGUAGE_CODE
           ADMINS
           TIME_ZONE
           LANGUAGE_CODE

+          DEFAULT_FROM_EMAIL
+          NOTIFICATION_FROM_EMAIL

 
         You can generate the SECRET_KEY with the following python code:
 
 
         You can generate the SECRET_KEY with the following python code:
 


@@ -106,6 +116,7 @@ in brackets):
         If you have patchwork installed in somewhere other than /srv/patchwork,
         you'll also need to define:
 
         If you have patchwork installed in somewhere other than /srv/patchwork,
         you'll also need to define:
 

+          ROOT_DIR

           MEDIA_ROOT
           TEMPLATE_DIRS
 
           MEDIA_ROOT
           TEMPLATE_DIRS
 


@@ -117,9 +128,11 @@ in brackets):
         Then, get patchwork to create its tables in your configured database:
 
          cd apps/
         Then, get patchwork to create its tables in your configured database:
 
          cd apps/

-         PYTHONPATH=../lib/python ./manage.py syncdb
+         PYTHONPATH=../lib/python/django ./manage.py syncdb

 
 

-        And add privileges for your mail and web users:
+        And 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


@@ -130,14 +143,26 @@ in brackets):
 
 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
 
         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


@@ -148,7 +173,7 @@ 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.
 
 
         - this also requires the mod_rewrite apache module to be loaded.
 


@@ -192,6 +217,39 @@ fastcgi:
 
      sudo -u nobody /srv/patchwork/apps/patchwork/bin/parsemail.sh < mail
 
 
      sudo -u nobody /srv/patchwork/apps/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
+      PYTHONPATH=apps:.
+      DJANGO_SETTINGS_MODULE=settings
+      */10 * * * * cd patchwork; python apps/patchwork/bin/patchwork-cron.py
+
+
+    - 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: