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         DATABASES = {
  56             'default': {
  57                 'ENGINE': 'django.db.backends.postgresql_psycopg2',
  58                 'HOST': 'localhost',
  59                 'PORT': '',
  60                 'USER': 'patchwork',
  61                 'PASSWORD': 'my_secret_password',
  62                 'NAME': 'patchwork',
  63             },
  64         }
  65
  66     For MySQL:
  67         $ mysql
  68         > CREATE DATABASE 'patchwork' CHARACTER SET utf8;
  69         > CREATE USER 'www-data'@'localhost' IDENTIFIED BY '<password>';
  70         > CREATE USER 'nobody'@'localhost' IDENTIFIED BY '<password>';
  71
  72         Once that is done, you need to tell Django about the new Database
  73         settings, using local_settings.py (see below) to override the defaults
  74         in settings.py:
  75
  76         DATABASES = {
  77             'default': {
  78                 'ENGINE': 'django.db.backends.mysql',
  79                 'HOST': 'localhost',
  80                 'PORT': '',
  81                 'USER': 'patchwork',
  82                 'PASSWORD': 'my_secret_password',
  83                 'NAME': 'patchwork',
  84                 'TEST_CHARSET': 'utf8',
  85             },
  86         }
  87
  88         TEST_CHARSET is used when creating tables for the test suite. Without
  89         it, tests checking for the correct handling of non-ASCII characters
  90         fail.
  91
  92 2. Django setup
  93
  94         Set up some initial directories in the patchwork base directory:
  95
  96          mkdir -p lib/packages lib/python
  97
  98         lib/packages is for stuff we'll download, lib/python is to add
  99         to our python path. We'll symlink python modules into lib/python.
 100
 101         At the time of release, patchwork depends on django version 1.5 or
 102         later. Your distro probably provides this. If not, do a:
 103
 104          cd lib/packages
 105           git clone https://github.com/django/django.git -b stable/1.5.x
 106          cd ../python
 107          ln -s ../packages/django/django ./django
 108
 109         The settings.py file contains default settings for patchwork, you'll
 110         need to configure settings for your own setup.
 111
 112         Rather than edit settings.py, create a file 'local_settings.py', and
 113         override or add settings as necessary. You'll need to define the
 114         following:
 115
 116           SECRET_KEY
 117           ADMINS
 118           TIME_ZONE
 119           LANGUAGE_CODE
 120           DEFAULT_FROM_EMAIL
 121           NOTIFICATION_FROM_EMAIL
 122
 123         You can generate the SECRET_KEY with the following python code:
 124
 125           import string, random
 126           chars = string.letters + string.digits + string.punctuation
 127           print repr("".join([random.choice(chars) for i in range(0,50)]))
 128
 129         If you wish to enable the XML-RPC interface, add the following to
 130         your local_settings.py file:
 131
 132           ENABLE_XMLRPC = True
 133
 134         Then, get patchwork to create its tables in your configured database:
 135
 136          cd apps/
 137          PYTHONPATH=../lib/python ./manage.py syncdb
 138
 139         And add privileges for your mail and web users. This is only needed if
 140         you use the ident-based approach. If you use password-based database
 141         authentication, you can skip this step.
 142
 143         Postgresql:
 144           psql -f lib/sql/grant-all.postgres.sql patchwork
 145
 146         MySQL:
 147           mysql patchwork < lib/sql/grant-all.mysql.sql
 148
 149
 150 3. Apache setup
 151
 152 Example apache configuration files are in lib/apache2/.
 153
 154 wsgi:
 155         django has built-in support for WSGI, which supersedes the fastcgi
 156         handler. It is thus the preferred method to run patchwork.
 157
 158         The necessary configuration for Apache2 may be found in
 159
 160          lib/apache2/patchwork.wsgi.conf.
 161
 162         You will need to install/enable mod_wsgi for this to work:
 163
 164          a2enmod wsgi
 165          apache2ctl restart
 166
 167 mod_python:
 168
 169         An example apache configuration file for mod_python is in:
 170
 171           lib/apache2/patchwork.mod_python.conf
 172
 173         However, mod_python and mod_php may not work well together. So, if your
 174         web server is used for serving php files, the fastcgi method may suit
 175         instead.
 176
 177 fastcgi:
 178
 179         django has built-in support for fastcgi, which requires the
 180         'flup' python module. An example configuration is in:
 181
 182           lib/apache2/patchwork.fastcgi.conf
 183
 184         - this also requires the mod_rewrite apache module to be loaded.
 185
 186         Once you have apache set up, you can start the fastcgi server with:
 187
 188           cd /srv/patchwork/apps
 189           ./manage.py runfcgi method=prefork \
 190                               socket=/srv/patchwork/var/fcgi.sock \
 191                               pidfile=/srv/patchwork/var/fcgi.pid
 192
 193 4. Configure patchwork
 194     Now, you should be able to administer patchwork, by visiting the
 195     URL:
 196
 197       http://your-host/admin/
 198
 199     You'll probably want to do the following:
 200
 201       * Set up your projects
 202       * Configure your website address (in the Sites) section of the admin
 203
 204 5. Subscribe a local address to the mailing list
 205
 206      You will need an email address for patchwork to receive email on - for
 207      example - patchwork@, and this address will need to be subscribed to the
 208      list. Depending on the mailing list, you will probably need to confirm the
 209      subscription - temporarily direct the alias to yourself to do this.
 210
 211 6. Setup your MTA to deliver mail to the parsemail script
 212
 213     Your MTA will need to deliver mail to the parsemail script in the email/
 214     directory. (Note, do not use the parsemail.py script directly). Something
 215     like this in /etc/aliases is suitable for postfix:
 216
 217       patchwork: "|/srv/patchwork/apps/patchwork/bin/parsemail.sh"
 218
 219     You may need to customise the parsemail.sh script if you haven't installed
 220     patchwork in /srv/patchwork.
 221
 222     Test that you can deliver a patch to this script:
 223
 224      sudo -u nobody /srv/patchwork/apps/patchwork/bin/parsemail.sh < mail
 225
 226 7. Set up the patchwork cron script
 227
 228     Patchwork uses a cron script to clean up expired registrations, and
 229     send notifications of patch changes (for projects with this enabled).
 230
 231     Something like this in your crontab should work:
 232
 233       # m h  dom mon dow   command
 234       PYTHONPATH=apps:.
 235       DJANGO_SETTINGS_MODULE=settings
 236       */10 * * * * cd patchwork; python apps/patchwork/bin/patchwork-cron.py
 237
 238
 239     - the frequency should be the same as the NOTIFICATION_DELAY_MINUTES
 240     setting, which defaults to 10 minutes.
 241
 242 8. Optional: Configure your VCS to automatically update patches
 243
 244     The tools directory of the patchwork distribution contains a file
 245     named post-receive.hook which is an example git hook that can be
 246     used to automatically update patches to the Accepted state when
 247     corresponding comits are pushed via git.
 248
 249     To install this hook, simply copy it to the .git/hooks directory on
 250     your server, name it post-receive, and make it executable.
 251
 252     This sample hook has support to update patches to different states
 253     depending on which branch is being pushed to. See the STATE_MAP
 254     setting in that file.
 255
 256     If you are using a system other than git, you can likely write a
 257     similar hook using pwclient to update patch state. If you do write
 258     one, please contribute it.
 259
 260 Some errors:
 261
 262 * __init__() got an unexpected keyword argument 'max_length'
 263
 264  - you're running an old version of django. If your distribution doesn't
 265    provide a newer version, just download and extract django into
 266    lib/python/django
 267
 268 * ERROR: permission denied for relation patchwork_...
 269
 270  - the user that patchwork is running as (ie, the user of the web-server)
 271    doesn't have access to the patchwork tables in the database. Check that
 272    your web-server user exists in the database, and that it has permissions
 273    to the tables.
 274
 275 * pwclient fails for actions that require authentication, but a username
 276   and password is given int ~/.pwclient rc. Server reports "No authentication
 277   credentials given".
 278
 279  - if you're using the FastCGI interface to apache, you'll need the
 280    '-pass-header Authorization' option to the FastCGIExternalServer
 281    configuration directive.