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