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.2
  13   * A webserver (apache)
  14   * mod_python or flup
  15   * A database server (postgresql)
  16
  17 1. Database setup
  18
  19     At present, I've tested with PostgreSQL and (to a lesser extent) MySQL
  20     database servers. If you have any (positive or negative) experiences with
  21     either, email me.
  22
  23     For the following commands, a $ prefix signifies that the command should be
  24     entered at your shell prompt, and a > prefix signifies the commant-line
  25     client for your sql server (psql or mysql)
  26
  27     Create a database for the system, add accounts for two system users: the
  28     web user (the user that your web server runs as) and the mail user (the
  29     user that your mail server runs as). On Ubuntu these are
  30     www-data and nobody, respectively.
  31
  32     As an alternative, you can use password-based login and a single database
  33     account. This is described further down.
  34
  35     For PostgreSQL (ident-based)
  36
  37         $ createdb patchwork
  38         $ createuser www-data
  39         $ createuser nobody
  40
  41         - postgres uses the standard UNIX authentication, so these users
  42           will only be accessible for processes running as the same username.
  43           This means that no passwords need to be set.
  44
  45     For PostgreSQL (password-based)
  46
  47         $ createuser -PE patchwork
  48         $ createdb -O patchwork patchwork
  49
  50         Once that is done, you need to tell Django about the new Database
  51         settings, using local_settings.py (see below) to override the defaults
  52         in settings.py:
  53
  54         DATABASE_ENGINE = 'postgresql_psycopg2'
  55         DATABASE_NAME = 'patchwork'
  56         DATABASE_USER = 'patchwork'
  57         DATABASE_PASSWORD = 'my_secret_password
  58         DATABASE_HOST = 'localhost'
  59         DATABASE_PORT = ''
  60
  61     For MySQL:
  62         $ mysql
  63         > CREATE DATABASE 'patchwork';
  64         > CREATE USER 'www-data'@'localhost' IDENTIFIED BY '<password>';
  65         > CREATE USER 'nobody'@'localhost' IDENTIFIED BY '<password>';
  66
  67 2. Django setup
  68
  69         Set up some initial directories in the patchwork base directory:
  70
  71          mkdir -p lib/packages lib/python
  72
  73         lib/packages is for stuff we'll download, lib/python is to add
  74         to our python path. We'll symlink python modules into lib/python.
  75
  76         At the time of release, patchwork depends on django version 1.2 or
  77         later. Your distro probably provides this. If not, do a:
  78
  79          cd lib/packages
  80          svn checkout http://code.djangoproject.com/svn/django/tags/releases/1.2
  81          cd ../python
  82          ln -s ../packages/django/django ./django
  83
  84         We also use some Javascript libraries:
  85
  86          cd lib/packages
  87          mkdir jquery
  88          cd jquery
  89          wget http://jqueryjs.googlecode.com/files/jquery-1.3.min.js
  90          wget http://www.isocra.com/articles/jquery.tablednd_0_5.js.zip
  91          unzip jquery.tablednd_0_5.js.zip jquery.tablednd_0_5.js
  92          cd ../../../htdocs/js/
  93          ln -s ../../lib/packages/jquery/jquery-1.3.min.js ./
  94          ln -s ../../lib/packages/jquery/jquery.tablednd_0_5.js ./
  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           MEDIA_ROOT
 120           TEMPLATE_DIRS
 121
 122         If you wish to enable the XML-RPC interface, add the following to
 123         your local_settings.py file:
 124
 125           ENABLE_XMLRPC = True
 126
 127         Then, get patchwork to create its tables in your configured database:
 128
 129          cd apps/
 130          PYTHONPATH=../lib/python ./manage.py syncdb
 131
 132         And add privileges for your mail and web users. This is only needed if
 133         you use the ident-based approach. If you use password-based database
 134         authentication, you can skip this step.
 135
 136         Postgresql:
 137           psql -f lib/sql/grant-all.postgres.sql patchwork
 138
 139         MySQL:
 140           mysql patchwork < lib/sql/grant-all.mysql.sql
 141
 142
 143 3. Apache setup
 144
 145 Example apache configuration files are in lib/apache2/.
 146
 147 wsgi:
 148         django has built-in support for WSGI, which supersedes the fastcgi
 149         handler. It is thus the preferred method to run patchwork.
 150
 151         The necessary configuration for Apache2 may be found in
 152
 153          lib/apache2/patchwork.wsgi.conf.
 154
 155         You will need to install/enable mod_wsgi for this to work:
 156
 157          a2enmod wsgi
 158          apache2ctl restart
 159
 160 mod_python:
 161
 162         An example apache configuration file for mod_python is in:
 163
 164           lib/apache2/patchwork.mod_python.conf
 165
 166         However, mod_python and mod_php may not work well together. So, if your
 167         web server is used for serving php files, the fastcgi method may suit
 168         instead.
 169
 170 fastcgi:
 171
 172         django has built-in support for fastcgi, which requires the
 173         'flup' python module. An example configuration is in:
 174
 175           lib/apache2/patchwork.fastcgi.conf
 176
 177         - this also requires the mod_rewrite apache module to be loaded.
 178
 179         Once you have apache set up, you can start the fastcgi server with:
 180
 181           cd /srv/patchwork/apps
 182           ./manage.py runfcgi method=prefork \
 183                               socket=/srv/patchwork/var/fcgi.sock \
 184                               pidfile=/srv/patchwork/var/fcgi.pid
 185
 186 4. Configure patchwork
 187     Now, you should be able to administer patchwork, by visiting the
 188     URL:
 189
 190       http://your-host/admin/
 191
 192     You'll probably want to do the following:
 193
 194       * Set up your projects
 195       * Configure your website address (in the Sites) section of the admin
 196
 197 5. Subscribe a local address to the mailing list
 198
 199      You will need an email address for patchwork to receive email on - for
 200      example - patchwork@, and this address will need to be subscribed to the
 201      list. Depending on the mailing list, you will probably need to confirm the
 202      subscription - temporarily direct the alias to yourself to do this.
 203
 204 6. Setup your MTA to deliver mail to the parsemail script
 205
 206     Your MTA will need to deliver mail to the parsemail script in the email/
 207     directory. (Note, do not use the parsemail.py script directly). Something
 208     like this in /etc/aliases is suitable for postfix:
 209
 210       patchwork: "|/srv/patchwork/apps/patchwork/bin/parsemail.sh"
 211
 212     You may need to customise the parsemail.sh script if you haven't installed
 213     patchwork in /srv/patchwork.
 214
 215     Test that you can deliver a patch to this script:
 216
 217      sudo -u nobody /srv/patchwork/apps/patchwork/bin/parsemail.sh < mail
 218
 219
 220 Some errors:
 221
 222 * __init__() got an unexpected keyword argument 'max_length'
 223
 224  - you're running an old version of django. If your distribution doesn't
 225    provide a newer version, just download and extract django into
 226    lib/python/django
 227
 228 * ERROR: permission denied for relation patchwork_...
 229
 230  - the user that patchwork is running as (ie, the user of the web-server)
 231    doesn't have access to the patchwork tables in the database. Check that
 232    your web-server user exists in the database, and that it has permissions
 233    to the tables.
 234
 235 * pwclient fails for actions that require authentication, but a username
 236   and password is given int ~/.pwclient rc. Server reports "No authentication
 237   credentials given".
 238
 239  - if you're using the FastCGI interface to apache, you'll need the
 240    '-pass-header Authorization' option to the FastCGIExternalServer
 241    configuration directive.