docs: Add collectstatic step to installation instructions

[patchwork] / docs / INSTALL

diff --git a/docs/INSTALL b/docs/INSTALL
index 5716ed231b59ac36dc6e4e3f68ad17e3011cb67e..cb0eccfc85a64dabe7cf82a1479156f72328d4aa 100644 (file)
--- a/docs/INSTALL
+++ b/docs/INSTALL
@@ -15,6 +15,7 @@ in brackets):
   * A database server (postgresql, mysql)
   * relevant python modules for the database server (e.g: python-mysqldb)
 
   * A database server (postgresql, mysql)
   * relevant python modules for the database server (e.g: python-mysqldb)
 

+

 1. Database setup
 
     At present, I've tested with PostgreSQL and (to a lesser extent) MySQL
 1. Database setup
 
     At present, I've tested with PostgreSQL and (to a lesser extent) MySQL


@@ -22,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


@@ -52,16 +53,20 @@ in brackets):
         settings, using local_settings.py (see below) to override the defaults
         in settings.py:
 
         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 = ''
+        DATABASES = {
+            'default': {
+                'ENGINE': 'django.db.backends.postgresql_psycopg2',
+                'HOST': 'localhost',
+                'PORT': '',
+                'USER': 'patchwork',
+                'PASSWORD': 'my_secret_password',
+                'NAME': 'patchwork',
+            },
+        }

 
     For MySQL:
         $ mysql
 
     For 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>';
 


@@ -69,76 +74,97 @@ in brackets):
        settings, using local_settings.py (see below) to override the defaults
        in settings.py:
 
        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 = ''
+        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.5 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
+      git clone https://github.com/django/django.git -b stable/1.5.x
+      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
+    The patchwork/settings/*.py files contain 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.
+    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:

 
 

-        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:
+       cp patchwork/settings/production.example.py \
+          patchwork/settings/production.py

 
 

-          SECRET_KEY
-          ADMINS
-          TIME_ZONE
-          LANGUAGE_CODE
-          DEFAULT_FROM_EMAIL
-          NOTIFICATION_FROM_EMAIL
+    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
+      DATABASES
+      TIME_ZONE
+      LANGUAGE_CODE
+      DEFAULT_FROM_EMAIL
+      NOTIFICATION_FROM_EMAIL

 
 

-          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 wish to enable the XML-RPC interface, add the following to
+    your local_settings.py file:

 
 

-        Then, get patchwork to create its tables in your configured database:
+      ENABLE_XMLRPC = True

 
 

-         cd apps/
-         PYTHONPATH=../lib/python ./manage.py syncdb
+    Then, get patchwork to create its tables in your configured database:

 
 

-        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.
+     PYTHONPATH=lib/python ./manage.py syncdb

 
 

-        Postgresql:
-          psql -f lib/sql/grant-all.postgres.sql patchwork
+    and initialise the static content:

 
 

-        MySQL:
-          mysql patchwork < lib/sql/grant-all.mysql.sql
+     PYTHONPATH=lib/python ./manage.py collectstatic
+
+    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
+
+    MySQL:
+      mysql patchwork < lib/sql/grant-all.mysql.sql

 
 
 3. Apache setup
 
 
 
 3. Apache setup
 

-Example apache configuration files are in lib/apache2/.
+    Example apache configuration files are in lib/apache2/.
+
+    wsgi:

 
 

-wsgi:

         django has built-in support for WSGI, which supersedes the fastcgi
         handler. It is thus the preferred method to run patchwork.
 
         django has built-in support for WSGI, which supersedes the fastcgi
         handler. It is thus the preferred method to run patchwork.
 


@@ -151,7 +177,8 @@ wsgi:
          a2enmod wsgi
          apache2ctl restart
 
          a2enmod wsgi
          apache2ctl restart
 

-mod_python:
+
+     mod_python:

 
         An example apache configuration file for mod_python is in:
 
 
         An example apache configuration file for mod_python is in:
 


@@ -161,7 +188,8 @@ mod_python:
         web server is used for serving php files, the fastcgi method may suit
         instead.
 
         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:


@@ -172,11 +200,12 @@ fastcgi:
 
         Once you have apache set up, you can start the fastcgi server with:
 
 
         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:


@@ -186,14 +215,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
 


@@ -201,14 +232,15 @@ 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
 
 
 7. Set up the patchwork cron script
 


@@ -218,14 +250,15 @@ fastcgi:
     Something like this in your crontab should work:
 
       # m h  dom mon dow   command
     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
+      PYTHONPATH=.
+      DJANGO_SETTINGS_MODULE=patchwork.settings.production
+      */10 * * * * cd patchwork; python patchwork/bin/patchwork-cron.py

 
 
     - the frequency should be the same as the NOTIFICATION_DELAY_MINUTES
     setting, which defaults to 10 minutes.
 
 
 
     - 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
 8. Optional: Configure your VCS to automatically update patches
 
     The tools directory of the patchwork distribution contains a file


@@ -244,6 +277,7 @@ fastcgi:
     similar hook using pwclient to update patch state. If you do write
     one, please contribute it.
 
     similar hook using pwclient to update patch state. If you do write
     one, please contribute it.
 

+

 Some errors:
 
 * __init__() got an unexpected keyword argument 'max_length'
 Some errors:
 
 * __init__() got an unexpected keyword argument 'max_length'


@@ -260,7 +294,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