git.ozlabs.org Git - patchwork/blob - docs/INSTALL

   1 Deploying Patchwork
   2
   3 Patchwork uses the django framework - there is some background on deploying
   4 django applications here:
   5
   6  http://www.djangobook.com/en/2.0/chapter12/
   7
   8 You'll need the following (applications used for patchwork development are
   9 in brackets):
  10
  11   * A python interpreter
  12   * django >= 1.5
  13   * A webserver (apache)
  14   * mod_python or flup
  15   * A database server (postgresql, mysql)
  16   * relevant python modules for the database server (e.g: python-mysqldb)
  17
  18 1. Database setup
  19
  20     At present, I've tested with PostgreSQL and (to a lesser extent) MySQL
  21     database servers. If you have any (positive or negative) experiences with
  22     either, email me.
  23
  24     For the following commands, a $ prefix signifies that the command should be
  25     entered at your shell prompt, and a > prefix signifies the commant-line
  26     client for your sql server (psql or mysql)
  27
  28     Create a database for the system, add accounts for two system users: the
  29     web user (the user that your web server runs as) and the mail user (the
  30     user that your mail server runs as). On Ubuntu these are
  31     www-data and nobody, respectively.
  32
  33     As an alternative, you can use password-based login and a single database
  34     account. This is described further down.
  35
  36     For PostgreSQL (ident-based)
  37
  38         $ createdb patchwork
  39         $ createuser www-data
  40         $ createuser nobody
  41
  42         - postgres uses the standard UNIX authentication, so these users
  43           will only be accessible for processes running as the same username.
  44           This means that no passwords need to be set.
  45
  46     For PostgreSQL (password-based)
  47
  48         $ createuser -PE patchwork
  49         $ createdb -O patchwork patchwork
  50
  51         Once that is done, you need to tell Django about the new Database
  52         settings, using local_settings.py (see below) to override the defaults
  53         in settings.py:
  54
  55         DATABASE_ENGINE = 'postgresql_psycopg2'
  56         DATABASE_NAME = 'patchwork'
  57         DATABASE_USER = 'patchwork'
  58         DATABASE_PASSWORD = 'my_secret_password
  59         DATABASE_HOST = 'localhost'
  60         DATABASE_PORT = ''
  61
  62     For MySQL:
  63         $ mysql
  64         > CREATE DATABASE 'patchwork';
  65         > CREATE USER 'www-data'@'localhost' IDENTIFIED BY '<password>';
  66         > CREATE USER 'nobody'@'localhost' IDENTIFIED BY '<password>';
  67
  68         Once that is done, you need to tell Django about the new Database
  69         settings, using local_settings.py (see below) to override the defaults
  70         in settings.py:
  71
  72         DATABASE_ENGINE = 'mysql'
  73         DATABASE_NAME = 'patchwork'
  74         DATABASE_USER = 'root'
  75         DATABASE_PASSWORD = 'my_secret_root_password'
  76         DATABSE_HOST = 'localhost'
  77         DATABASE_PORT = ''
  78
  79 2. Django setup
  80
  81         Set up some initial directories in the patchwork base directory:
  82
  83          mkdir -p lib/packages lib/python
  84
  85         lib/packages is for stuff we'll download, lib/python is to add
  86         to our python path. We'll symlink python modules into lib/python.
  87
  88         At the time of release, patchwork depends on django version 1.5 or
  89         later. Your distro probably provides this. If not, do a:
  90
  91          cd lib/packages
  92           git clone https://github.com/django/django.git -b stable/1.5.x
  93          cd ../python
  94          ln -s ../packages/django/django ./django
  95
  96         The settings.py file contains default settings for patchwork, you'll
  97         need to configure settings for your own setup.
  98
  99         Rather than edit settings.py, create a file 'local_settings.py', and
 100         override or add settings as necessary. You'll need to define the
 101         following:
 102
 103           SECRET_KEY
 104           ADMINS
 105           TIME_ZONE
 106           LANGUAGE_CODE
 107           DEFAULT_FROM_EMAIL
 108           NOTIFICATION_FROM_EMAIL
 109
 110         You can generate the SECRET_KEY with the following python code:
 111
 112           import string, random
 113           chars = string.letters + string.digits + string.punctuation
 114           print repr("".join([random.choice(chars) for i in range(0,50)]))
 115
 116         If you have patchwork installed in somewhere other than /srv/patchwork,
 117         you'll also need to define:
 118
 119           ROOT_DIR
 120           MEDIA_ROOT
 121           TEMPLATE_DIRS
 122
 123         If you wish to enable the XML-RPC interface, add the following to
 124         your local_settings.py file:
 125
 126           ENABLE_XMLRPC = True
 127
 128         Then, get patchwork to create its tables in your configured database:
 129
 130          cd apps/
 131          PYTHONPATH=../lib/python/django ./manage.py syncdb
 132
 133         And add privileges for your mail and web users. This is only needed if
 134         you use the ident-based approach. If you use password-based database
 135         authentication, you can skip this step.
 136
 137         Postgresql:
 138           psql -f lib/sql/grant-all.postgres.sql patchwork
 139
 140         MySQL:
 141           mysql patchwork < lib/sql/grant-all.mysql.sql
 142
 143
 144 3. Apache setup
 145
 146 Example apache configuration files are in lib/apache2/.
 147
 148 wsgi:
 149         django has built-in support for WSGI, which supersedes the fastcgi
 150         handler. It is thus the preferred method to run patchwork.
 151
 152         The necessary configuration for Apache2 may be found in
 153
 154          lib/apache2/patchwork.wsgi.conf.
 155
 156         You will need to install/enable mod_wsgi for this to work:
 157
 158          a2enmod wsgi
 159          apache2ctl restart
 160
 161 mod_python:
 162
 163         An example apache configuration file for mod_python is in:
 164
 165           lib/apache2/patchwork.mod_python.conf
 166
 167         However, mod_python and mod_php may not work well together. So, if your
 168         web server is used for serving php files, the fastcgi method may suit
 169         instead.
 170
 171 fastcgi:
 172
 173         django has built-in support for fastcgi, which requires the
 174         'flup' python module. An example configuration is in:
 175
 176           lib/apache2/patchwork.fastcgi.conf
 177
 178         - this also requires the mod_rewrite apache module to be loaded.
 179
 180         Once you have apache set up, you can start the fastcgi server with:
 181
 182           cd /srv/patchwork/apps
 183           ./manage.py runfcgi method=prefork \
 184                               socket=/srv/patchwork/var/fcgi.sock \
 185                               pidfile=/srv/patchwork/var/fcgi.pid
 186
 187 4. Configure patchwork
 188     Now, you should be able to administer patchwork, by visiting the
 189     URL:
 190
 191       http://your-host/admin/
 192
 193     You'll probably want to do the following:
 194
 195       * Set up your projects
 196       * Configure your website address (in the Sites) section of the admin
 197
 198 5. Subscribe a local address to the mailing list
 199
 200      You will need an email address for patchwork to receive email on - for
 201      example - patchwork@, and this address will need to be subscribed to the
 202      list. Depending on the mailing list, you will probably need to confirm the
 203      subscription - temporarily direct the alias to yourself to do this.
 204
 205 6. Setup your MTA to deliver mail to the parsemail script
 206
 207     Your MTA will need to deliver mail to the parsemail script in the email/
 208     directory. (Note, do not use the parsemail.py script directly). Something
 209     like this in /etc/aliases is suitable for postfix:
 210
 211       patchwork: "|/srv/patchwork/apps/patchwork/bin/parsemail.sh"
 212
 213     You may need to customise the parsemail.sh script if you haven't installed
 214     patchwork in /srv/patchwork.
 215
 216     Test that you can deliver a patch to this script:
 217
 218      sudo -u nobody /srv/patchwork/apps/patchwork/bin/parsemail.sh < mail
 219
 220 7. Optional: Configure your VCS to automatically update patches
 221
 222     The tools directory of the patchwork distribution contains a file
 223     named post-receive.hook which is an example git hook that can be
 224     used to automatically update patches to the Accepted state when
 225     corresponding comits are pushed via git.
 226
 227     To install this hook, simply copy it to the .git/hooks directory on
 228     your server, name it post-receive, and make it executable.
 229
 230     This sample hook has support to update patches to different states
 231     depending on which branch is being pushed to. See the STATE_MAP
 232     setting in that file.
 233
 234     If you are using a system other than git, you can likely write a
 235     similar hook using pwclient to update patch state. If you do write
 236     one, please contribute it.
 237
 238 Some errors:
 239
 240 * __init__() got an unexpected keyword argument 'max_length'
 241
 242  - you're running an old version of django. If your distribution doesn't
 243    provide a newer version, just download and extract django into
 244    lib/python/django
 245
 246 * ERROR: permission denied for relation patchwork_...
 247
 248  - the user that patchwork is running as (ie, the user of the web-server)
 249    doesn't have access to the patchwork tables in the database. Check that
 250    your web-server user exists in the database, and that it has permissions
 251    to the tables.
 252
 253 * pwclient fails for actions that require authentication, but a username
 254   and password is given int ~/.pwclient rc. Server reports "No authentication
 255   credentials given".
 256
 257  - if you're using the FastCGI interface to apache, you'll need the
 258    '-pass-header Authorization' option to the FastCGIExternalServer
 259    configuration directive.