X-Git-Url: http://git.ozlabs.org/?p=patchwork;a=blobdiff_plain;f=docs%2FINSTALL;fp=docs%2FINSTALL;h=0000000000000000000000000000000000000000;hp=bd9577023deed4e75d72be67575e0599f40f7e62;hb=808904d8a80c2b41234f2de9827ebcf67edcf227;hpb=c1c3f73c0a98996e1347353864e9367ac69edf33 diff --git a/docs/INSTALL b/docs/INSTALL deleted file mode 100644 index bd95770..0000000 --- a/docs/INSTALL +++ /dev/null @@ -1,305 +0,0 @@ -Deploying Patchwork - -Patchwork uses the django framework - there is some background on deploying -django applications here: - - http://www.djangobook.com/en/2.0/chapter12/ - -You'll need the following (applications used for patchwork development are -in brackets): - - * A python interpreter - * django >= 1.5 - * A webserver (apache) - * mod_python or flup - * A database server (postgresql, mysql) - * relevant python modules for the database server (e.g: python-mysqldb) - - -1. Database setup - - At present, I've tested with PostgreSQL and (to a lesser extent) MySQL - database servers. If you have any (positive or negative) experiences with - either, email me. - - For the following commands, a $ prefix signifies that the command should be - entered at your shell prompt, and a > prefix signifies the command-line - client for your sql server (psql or mysql) - - Create a database for the system, add accounts for two system users: the - web user (the user that your web server runs as) and the mail user (the - user that your mail server runs as). On Ubuntu these are - www-data and nobody, respectively. - - As an alternative, you can use password-based login and a single database - account. This is described further down. - - For PostgreSQL (ident-based) - - $ createdb patchwork - $ createuser www-data - $ createuser nobody - - - postgres uses the standard UNIX authentication, so these users - will only be accessible for processes running as the same username. - This means that no passwords need to be set. - - For PostgreSQL (password-based) - - $ createuser -PE patchwork - $ createdb -O patchwork patchwork - - Once that is done, you need to tell Django about the new Database - settings, using local_settings.py (see below) to override the defaults - in settings.py: - - DATABASES = { - 'default': { - 'ENGINE': 'django.db.backends.postgresql_psycopg2', - 'HOST': 'localhost', - 'PORT': '', - 'USER': 'patchwork', - 'PASSWORD': 'my_secret_password', - 'NAME': 'patchwork', - }, - } - - For MySQL: - $ mysql - > CREATE DATABASE patchwork CHARACTER SET utf8; - > CREATE USER 'www-data'@'localhost' IDENTIFIED BY ''; - > CREATE USER 'nobody'@'localhost' IDENTIFIED BY ''; - - Once that is done, you need to tell Django about the new Database - settings, using local_settings.py (see below) to override the defaults - in settings.py: - - DATABASES = { - 'default': { - 'ENGINE': 'django.db.backends.mysql', - 'HOST': 'localhost', - 'PORT': '', - 'USER': 'patchwork', - 'PASSWORD': 'my_secret_password', - 'NAME': 'patchwork', - 'TEST_CHARSET': 'utf8', - }, - } - - TEST_CHARSET is used when creating tables for the test suite. Without - it, tests checking for the correct handling of non-ASCII characters - fail. - - -2. Django setup - - Set up some initial directories in the patchwork base directory: - - mkdir -p lib/packages lib/python - - lib/packages is for stuff we'll download; lib/python is to add - to our python path. We'll symlink python modules into lib/python. - - At the time of release, patchwork depends on django version 1.5 or - later. Your distro probably provides this. If not, do a: - - cd lib/packages - git clone https://github.com/django/django.git -b stable/1.5.x - cd ../python - ln -s ../packages/django/django ./django - - The patchwork/settings/*.py files contain default settings for patchwork, - you'll need to configure settings for your own setup. - - Rather than editing these files (which will cause conflicts when you - update the base patchwork code), create a file 'production.py', based on - the example: - - cp patchwork/settings/production.example.py \ - patchwork/settings/production.py - - and override or add settings as necessary. You'll need to define the - following: - - SECRET_KEY - ADMINS - DATABASES - TIME_ZONE - LANGUAGE_CODE - DEFAULT_FROM_EMAIL - NOTIFICATION_FROM_EMAIL - - You can generate the SECRET_KEY with the following python code: - - import string, random - chars = string.letters + string.digits + string.punctuation - print repr("".join([random.choice(chars) for i in range(0,50)])) - - If you wish to enable the XML-RPC interface, add the following to - your local_settings.py file: - - ENABLE_XMLRPC = True - - Then, get patchwork to create its tables in your configured database: - - PYTHONPATH=lib/python ./manage.py syncdb - - and initialise the static content: - - PYTHONPATH=lib/python ./manage.py collectstatic - - You'll also need to load the initial tags and states into the - patchwork database: - - PYTHONPATH=lib/python ./manage.py loaddata default_tags default_states - - Finally, add privileges for your mail and web users. This is only needed if - you use the ident-based approach. If you use password-based database - authentication, you can skip this step. - - Postgresql: - psql -f lib/sql/grant-all.postgres.sql patchwork - - MySQL: - mysql patchwork < lib/sql/grant-all.mysql.sql - - -3. Apache setup - - Example apache configuration files are in lib/apache2/. - - wsgi: - - django has built-in support for WSGI, which supersedes the fastcgi - handler. It is thus the preferred method to run patchwork. - - The necessary configuration for Apache2 may be found in - - lib/apache2/patchwork.wsgi.conf. - - You will need to install/enable mod_wsgi for this to work: - - a2enmod wsgi - apache2ctl restart - - - mod_python: - - An example apache configuration file for mod_python is in: - - lib/apache2/patchwork.mod_python.conf - - However, mod_python and mod_php may not work well together. So, if your - web server is used for serving php files, the fastcgi method may suit - instead. - - - fastcgi: - - django has built-in support for fastcgi, which requires the - 'flup' python module. An example configuration is in: - - lib/apache2/patchwork.fastcgi.conf - - - this also requires the mod_rewrite apache module to be loaded. - - Once you have apache set up, you can start the fastcgi server with: - - cd /srv/patchwork/ - ./manage.py runfcgi method=prefork \ - socket=/srv/patchwork/var/fcgi.sock \ - pidfile=/srv/patchwork/var/fcgi.pid - - -4. Configure patchwork - Now, you should be able to administer patchwork, by visiting the - URL: - - http://your-host/admin/ - - You'll probably want to do the following: - - * Set up your projects - * Configure your website address (in the Sites) section - - -5. Subscribe a local address to the mailing list - - You will need an email address for patchwork to receive email on - for - example - patchwork@, and this address will need to be subscribed to the - list. Depending on the mailing list, you will probably need to confirm the - subscription - temporarily direct the alias to yourself to do this. - - -6. Setup your MTA to deliver mail to the parsemail script - - Your MTA will need to deliver mail to the parsemail script in the email/ - directory. (Note, do not use the parsemail.py script directly). Something - like this in /etc/aliases is suitable for postfix: - - patchwork: "|/srv/patchwork/patchwork/bin/parsemail.sh" - - You may need to customise the parsemail.sh script if you haven't installed - patchwork in /srv/patchwork. - - Test that you can deliver a patch to this script: - - sudo -u nobody /srv/patchwork/patchwork/bin/parsemail.sh < mail - - -7. Set up the patchwork cron script - - Patchwork uses a cron script to clean up expired registrations, and - send notifications of patch changes (for projects with this enabled). - - Something like this in your crontab should work: - - # m h dom mon dow command - */10 * * * * cd patchwork; ./manage.py cron - - - - the frequency should be the same as the NOTIFICATION_DELAY_MINUTES - setting, which defaults to 10 minutes. - - -8. Optional: Configure your VCS to automatically update patches - - The tools directory of the patchwork distribution contains a file - named post-receive.hook which is an example git hook that can be - used to automatically update patches to the Accepted state when - corresponding comits are pushed via git. - - To install this hook, simply copy it to the .git/hooks directory on - your server, name it post-receive, and make it executable. - - This sample hook has support to update patches to different states - depending on which branch is being pushed to. See the STATE_MAP - setting in that file. - - If you are using a system other than git, you can likely write a - similar hook using pwclient to update patch state. If you do write - one, please contribute it. - - -Some errors: - -* __init__() got an unexpected keyword argument 'max_length' - - - you're running an old version of django. If your distribution doesn't - provide a newer version, just download and extract django into - lib/python/django - -* ERROR: permission denied for relation patchwork_... - - - the user that patchwork is running as (ie, the user of the web-server) - doesn't have access to the patchwork tables in the database. Check that - your web-server user exists in the database, and that it has permissions - to the tables. - -* pwclient fails for actions that require authentication, but a username - and password is given in ~/.pwclientrc. Server reports "No authentication - credentials given". - - - if you're using the FastCGI interface to apache, you'll need the - '-pass-header Authorization' option to the FastCGIExternalServer - configuration directive.