X-Git-Url: https://git.ozlabs.org/?a=blobdiff_plain;f=docs%2FINSTALL;h=cb0eccfc85a64dabe7cf82a1479156f72328d4aa;hb=daa3ae42eee5e569881070bcc2958b361743f70a;hp=ea164046596e9d92be83514dee762f4ef91a85cd;hpb=8b6225cb5e969d0dd84eccb80af860e5f4023a6d;p=patchwork diff --git a/docs/INSTALL b/docs/INSTALL index ea16404..cb0eccf 100644 --- a/docs/INSTALL +++ b/docs/INSTALL @@ -3,16 +3,18 @@ Deploying Patchwork Patchwork uses the django framework - there is some background on deploying django applications here: - http://www.djangobook.com/en/1.0/chapter20/ + 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 + * django >= 1.5 * A webserver (apache) * mod_python or flup - * A database server (postgresql) + * A database server (postgresql, mysql) + * relevant python modules for the database server (e.g: python-mysqldb) + 1. Database setup @@ -21,7 +23,7 @@ in brackets): 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 commant-line + 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 @@ -29,132 +31,180 @@ in brackets): user that your mail server runs as). On Ubuntu these are www-data and nobody, respectively. - For PostgreSQL + 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. + - 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: - For MySQL: + 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'; + > CREATE DATABASE patchwork CHARACTER SET utf8; > CREATE USER 'www-data'@'localhost' IDENTIFIED BY ''; > CREATE USER 'nobody'@'localhost' IDENTIFIED BY ''; -2. Django setup + 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: - Set up some initial directories in the patchwork base directory: + DATABASES = { + 'default': { + 'ENGINE': 'django.db.backends.mysql', + 'HOST': 'localhost', + 'PORT': '', + 'USER': 'patchwork', + 'PASSWORD': 'my_secret_password', + 'NAME': 'patchwork', + 'TEST_CHARSET': 'utf8', + }, + } - mkdir -p lib/packages lib/python + TEST_CHARSET is used when creating tables for the test suite. Without + it, tests checking for the correct handling of non-ASCII characters + fail. - At the time of release, patchwork depends on django version 1.0. - However, most distros don't provide 1.0 yet. If yours does, then you - can skip this step. Otherwise, do a: - cd lib/packages - svn checkout http://code.djangoproject.com/svn/django/tags/releases/1.0 - cd ../python - ln -s ../packages/django/django ./django +2. Django setup + + Set up some initial directories in the patchwork base directory: - We also use the django-registration infrastructure from - http://code.google.com/p/django-registration/ + mkdir -p lib/packages lib/python - cd lib/packages/ - svn checkout \ - http://django-registration.googlecode.com/svn/trunk/registration/ \ - django-registration - cd ../../apps - ln -s ../lib/packages/django-registration ./registration + 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. - We also use some Javascript libraries: + 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 - mkdir jquery - cd jquery - wget http://jqueryjs.googlecode.com/files/jquery-1.3.min.js - wget http://www.isocra.com/articles/jquery.tablednd_0_5.js.zip - unzip jquery.tablednd_0_5.js.zip jquery.tablednd_0_5.js - cd ../../../htdocs/js/ - ln -s ../../lib/packages/jquery/jquery-1.3.min.js ./ - ln -s ../../lib/packages/jquery/jquery.tablednd_0_5.js ./ + 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 settings.py file contains default settings for patchwork, you'll - need to configure settings for your own setup. + The patchwork/settings/*.py files contain default settings for patchwork, + you'll need to configure settings for your own setup. - Rather than edit settings.py, create a file 'local_settings.py', and - override or add settings as necessary. You'll need to define the - following: + 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: - SECRET_KEY - ADMINS - TIME_ZONE - LANGUAGE_CODE + cp patchwork/settings/production.example.py \ + patchwork/settings/production.py - You can generate the SECRET_KEY with the following python code: + and override or add settings as necessary. You'll need to define the + following: - import string, random - chars = string.letters + string.digits + string.punctuation - print repr("".join([random.choice(chars) for i in range(0,50)])) + SECRET_KEY + ADMINS + DATABASES + TIME_ZONE + LANGUAGE_CODE + DEFAULT_FROM_EMAIL + NOTIFICATION_FROM_EMAIL - If you have patchwork installed in somewhere other than /srv/patchwork, - you'll also need to define: + You can generate the SECRET_KEY with the following python code: - MEDIA_ROOT - TEMPLATE_DIRS + 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: + If you wish to enable the XML-RPC interface, add the following to + your local_settings.py file: - ENABLE_XMLRPC = True + ENABLE_XMLRPC = True - Then, get patchwork to create its tables in your configured database: + Then, get patchwork to create its tables in your configured database: - cd apps/ - PYTHONPATH=../lib/python ./manage.py syncdb + PYTHONPATH=lib/python ./manage.py syncdb - And add privileges for your mail and web users: + and initialise the static content: - Postgresql: - psql -f lib/sql/grant-all.postgres.sql patchwork + PYTHONPATH=lib/python ./manage.py collectstatic - MySQL: - mysql patchwork < lib/sql/grant-all.mysql.sql + and 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/apache/. + 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: - This should be the simpler of the two to set up. An example apache - configuration file is in: + mod_python: - lib/apache/patchwork.mod_python.conf + An example apache configuration file for mod_python is in: - 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. + lib/apache2/patchwork.mod_python.conf -fastcgi: + 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. - django has built-in support for fastcgi, which requires the - 'flup' python module. An example configuration is in: - lib/apache/patchwork.fastcgi.conf + fastcgi: - - this also requires the mod_rewrite apache module to be loaded. + django has built-in support for fastcgi, which requires the + 'flup' python module. An example configuration is in: - Once you have apache set up, you can start the fastcgi server with: + 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 - cd /srv/patchwork/apps - ./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 @@ -165,14 +215,16 @@ fastcgi: You'll probably want to do the following: * Set up your projects - * Configure your website address (in the Sites) section of the admin + * 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. + 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 @@ -180,14 +232,50 @@ fastcgi: directory. (Note, do not use the parsemail.py script directly). Something like this in /etc/aliases is suitable for postfix: - patchwork: "|/srv/patchwork/apps/patchwork/bin/parsemail.sh" + 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/apps/patchwork/bin/parsemail.sh < mail + 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 + PYTHONPATH=. + DJANGO_SETTINGS_MODULE=patchwork.settings.production + */10 * * * * cd patchwork; python patchwork/bin/patchwork-cron.py + + + - 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: @@ -206,7 +294,7 @@ Some errors: to the tables. * pwclient fails for actions that require authentication, but a username - and password is given int ~/.pwclient rc. Server reports "No authentication + 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