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 wish to enable the XML-RPC interface, add the following to
 117         your local_settings.py file:
 118
 119           ENABLE_XMLRPC = True
 120
 121         Then, get patchwork to create its tables in your configured database:
 122
 123          cd apps/
 124          PYTHONPATH=../lib/python ./manage.py syncdb
 125
 126         And add privileges for your mail and web users. This is only needed if
 127         you use the ident-based approach. If you use password-based database
 128         authentication, you can skip this step.
 129
 130         Postgresql:
 131           psql -f lib/sql/grant-all.postgres.sql patchwork
 132
 133         MySQL:
 134           mysql patchwork < lib/sql/grant-all.mysql.sql
 135
 136
 137 3. Apache setup
 138
 139 Example apache configuration files are in lib/apache2/.
 140
 141 wsgi:
 142         django has built-in support for WSGI, which supersedes the fastcgi
 143         handler. It is thus the preferred method to run patchwork.
 144
 145         The necessary configuration for Apache2 may be found in
 146
 147          lib/apache2/patchwork.wsgi.conf.
 148
 149         You will need to install/enable mod_wsgi for this to work:
 150
 151          a2enmod wsgi
 152          apache2ctl restart
 153
 154 mod_python:
 155
 156         An example apache configuration file for mod_python is in:
 157
 158           lib/apache2/patchwork.mod_python.conf
 159
 160         However, mod_python and mod_php may not work well together. So, if your
 161         web server is used for serving php files, the fastcgi method may suit
 162         instead.
 163
 164 fastcgi:
 165
 166         django has built-in support for fastcgi, which requires the
 167         'flup' python module. An example configuration is in:
 168
 169           lib/apache2/patchwork.fastcgi.conf
 170
 171         - this also requires the mod_rewrite apache module to be loaded.
 172
 173         Once you have apache set up, you can start the fastcgi server with:
 174
 175           cd /srv/patchwork/apps
 176           ./manage.py runfcgi method=prefork \
 177                               socket=/srv/patchwork/var/fcgi.sock \
 178                               pidfile=/srv/patchwork/var/fcgi.pid
 179
 180 4. Configure patchwork
 181     Now, you should be able to administer patchwork, by visiting the
 182     URL:
 183
 184       http://your-host/admin/
 185
 186     You'll probably want to do the following:
 187
 188       * Set up your projects
 189       * Configure your website address (in the Sites) section of the admin
 190
 191 5. Subscribe a local address to the mailing list
 192
 193      You will need an email address for patchwork to receive email on - for
 194      example - patchwork@, and this address will need to be subscribed to the
 195      list. Depending on the mailing list, you will probably need to confirm the
 196      subscription - temporarily direct the alias to yourself to do this.
 197
 198 6. Setup your MTA to deliver mail to the parsemail script
 199
 200     Your MTA will need to deliver mail to the parsemail script in the email/
 201     directory. (Note, do not use the parsemail.py script directly). Something
 202     like this in /etc/aliases is suitable for postfix:
 203
 204       patchwork: "|/srv/patchwork/apps/patchwork/bin/parsemail.sh"
 205
 206     You may need to customise the parsemail.sh script if you haven't installed
 207     patchwork in /srv/patchwork.
 208
 209     Test that you can deliver a patch to this script:
 210
 211      sudo -u nobody /srv/patchwork/apps/patchwork/bin/parsemail.sh < mail
 212
 213 7. Set up the patchwork cron script
 214
 215     Patchwork uses a cron script to clean up expired registrations, and
 216     send notifications of patch changes (for projects with this enabled).
 217
 218     Something like this in your crontab should work:
 219
 220       # m h  dom mon dow   command
 221       PYTHONPATH=apps:.
 222       DJANGO_SETTINGS_MODULE=settings
 223       */10 * * * * cd patchwork; python apps/patchwork/bin/patchwork-cron.py
 224
 225
 226     - the frequency should be the same as the NOTIFICATION_DELAY_MINUTES
 227     setting, which defaults to 10 minutes.
 228
 229 8. Optional: Configure your VCS to automatically update patches
 230
 231     The tools directory of the patchwork distribution contains a file
 232     named post-receive.hook which is an example git hook that can be
 233     used to automatically update patches to the Accepted state when
 234     corresponding comits are pushed via git.
 235
 236     To install this hook, simply copy it to the .git/hooks directory on
 237     your server, name it post-receive, and make it executable.
 238
 239     This sample hook has support to update patches to different states
 240     depending on which branch is being pushed to. See the STATE_MAP
 241     setting in that file.
 242
 243     If you are using a system other than git, you can likely write a
 244     similar hook using pwclient to update patch state. If you do write
 245     one, please contribute it.
 246
 247 Some errors:
 248
 249 * __init__() got an unexpected keyword argument 'max_length'
 250
 251  - you're running an old version of django. If your distribution doesn't
 252    provide a newer version, just download and extract django into
 253    lib/python/django
 254
 255 * ERROR: permission denied for relation patchwork_...
 256
 257  - the user that patchwork is running as (ie, the user of the web-server)
 258    doesn't have access to the patchwork tables in the database. Check that
 259    your web-server user exists in the database, and that it has permissions
 260    to the tables.
 261
 262 * pwclient fails for actions that require authentication, but a username
 263   and password is given int ~/.pwclient rc. Server reports "No authentication
 264   credentials given".
 265
 266  - if you're using the FastCGI interface to apache, you'll need the
 267    '-pass-header Authorization' option to the FastCGIExternalServer
 268    configuration directive.