diff options
Diffstat (limited to 'installing')
| -rw-r--r-- | installing/email.md (renamed from installing/exim4.md) | 113 | ||||
| -rw-r--r-- | installing/index.md | 2 | ||||
| -rw-r--r-- | installing/manual_install.md | 32 |
3 files changed, 118 insertions, 29 deletions
diff --git a/installing/exim4.md b/installing/email.md index 4cb056a26..bad893c8e 100644 --- a/installing/exim4.md +++ b/installing/email.md @@ -6,21 +6,111 @@ title: Installing MTA # Installing the MTA <p class="lead"> - Alaveteli sends and recieves email. You'll need to set up your Mail - Transfer Agent (MTA) to handle this properly. + Alaveteli sends and receives email. You'll need to set up your Mail + Transfer Agent (MTA) to handle this properly. We've got examples + here for both postfix and exim4, two of the most popular MTAs. </p> +Make sure you follow the correct instructions for the specific MTA you're using: + +* [postfix](#example-setup-on-postfix) +* [exim4](#example-setup-on-exim4) + +## Example setup on postfix + +This section shows an example of how to set up your MTA if you're using +**postfix** (running on Ubuntu). See the example for +[exim4](#example-setup-on-exim4) if you're using that instead of postfix. + +### Instructions + +For example, with: + + ALAVETELI_HOME=/path/to/alaveteli/software + ALAVETELI_USER=www-data + +In `/etc/postfix/master.cf`: + + alaveteli unix - n n - 50 pipe + flags=R user=ALAVETELI_USER argv=ALAVETELI_HOME/script/mailin + +The user ALAVETELI_USER should have write permissions on ALAVETELI_HOME. + +In `/etc/postfix/main.cf`: + + virtual_alias_maps = regexp:/etc/postfix/regexp + +And, assuming you set +[`INCOMING_EMAIL_PREFIX`]({{ site.baseurl }}customising/config/#incoming_email_prefix) +in `config/general` to "foi+", create `/etc/postfix/regexp` with the following +content: + + /^foi.*/ alaveteli + +You should also configure postfix to discard any messages sent to the +[`BLACKHOLE_PREFIX`]({{ site.baseurl }}customising/config/#blackhole_prefix) +address, whose default value is `do-not-reply-to-this-address`. For example, add the +following to `/etc/aliases`: + + # We use this for envelope from for some messages where + # we don't care about delivery + do-not-reply-to-this-address: :blackhole: + +### Logging + +For the postfix logs to be succesfully read by the script `load-mail-server-logs`, they need +to be log rotated with a date in the filename. Since that will create a lot of rotated log +files (one for each day), it's good to have them in their own directory. For example (on Ubuntu), +in `/etc/rsyslog.d/50-default.conf` set: + + mail.* -/var/log/mail/mail.log + +And also edit `/etc/logrotate.d/rsyslog`: + + /var/log/mail/mail.log + { + rotate 30 + daily + dateext + missingok + notifempty + compress + delaycompress + sharedscripts + postrotate + reload rsyslog >/dev/null 2>&1 || true + endscript + } + +You'll also need to tell Alaveteli where the log files are stored and that they're in postfix +format. Update +[`MTA_LOG_PATH`]({{ site.baseurl }}customising/config/#mta_log_path) and +[`MTA_LOG_TYPE`]({{ site.baseurl }}customising/config/#mta_log_type) in `config/general.yml` with: + + MTA_LOG_PATH: '/var/log/mail/mail.log-*' + MTA_LOG_TYPE: "postfix" + +### Troubleshooting (postfix) + +To test mail delivery, run: + + $ /usr/sbin/sendmail -bv foi+requrest-1234@localhost + +This tells you if sending the emails to `foi\+.*localhost` is working. + + ## Example setup on exim4 -This page shows an example of how to set up your mail transfer agent (MTA). -These instructions are for **exim4** (running on Ubuntu) -- exim is one of the most -popular MTAs. +This section shows an example of how to set up your MTA if you're using +**exim4** (running on Ubuntu). See the example for +[postfix](#example-setup-on-postfix) if you're using that instead of exim4. + -## Instructions +### Instructions We suggest you add the following to your exim configuration. -In `/etc/exim4/conf.d/main/04_alaveteli_options`: +In `/etc/exim4/conf.d/main/04_alaveteli_options`, set: ALAVETELI_HOME=/path/to/alaveteli/software ALAVETELI_USER=www-data @@ -74,8 +164,7 @@ address, whose default value is # We use this for envelope from for some messages where we don't care about delivery do-not-reply-to-this-address: :blackhole: -If you want to make use of the automatic bounce-message handling, then -set the +If you want to make use of the automatic bounce-message handling, then set the [`TRACK_SENDER_EMAIL`]({{ site.baseurl }}customising/config/#track_sender_email) address to be filtered through `script/handle-mail-replies`. Messages that are not bounces or @@ -87,7 +176,7 @@ configuration looks like this: raw_team: [a list of people on the team] team: |/path/to/alaveteli/software/script/handle-mail-replies -with `FORWARD_NONBOUNCE_RESPONSES_TO: 'raw_team@whatdotheyknow.com'` +with `FORWARD_NONBOUNCE_RESPONSES_TO`: 'raw_team@whatdotheyknow.com'` Finally, make sure you have `dc_use_split_config='true'` in `/etc/exim4/update-exim4.conf.conf`, and execute the command @@ -99,9 +188,9 @@ yours does, you will need to rename it before running `update-exim4.conf`. (You may also want to set `dc_eximconfig_configtype='internet'`, `dc_local_interfaces='0.0.0.0 ; ::1'`, and -`dc_other_hostnames='<your-host-name>'`) +`dc_other_hostnames='<your-host-name>'`). -## Troubleshooting +### Troubleshooting (exim) To test mail delivery, run: diff --git a/installing/index.md b/installing/index.md index c77e30ded..32ed821ea 100644 --- a/installing/index.md +++ b/installing/index.md @@ -23,6 +23,6 @@ If you're setting up a development server on MacOS X, we've also got [MacOS inst Alaveteli needs to be able to send and receive email, so you need to setup your MTA (Mail Transfer Agent) appropriately. -* [Installing the MTA]({{ site.baseurl }}installing/exim4) +* [Installing the MTA]({{ site.baseurl }}installing/email) diff --git a/installing/manual_install.md b/installing/manual_install.md index a9580e402..01e868551 100644 --- a/installing/manual_install.md +++ b/installing/manual_install.md @@ -7,12 +7,12 @@ title: Manual installation # Manual Installation <p class="lead"> - The following instructions describe the step-by-step process for - installing Alavetli. <em>You don't necessarily need to do it this - way:</em> it's usually easier to use the - <a href="{{ site.baseurl }}installing/script">installation script</a> - or the - <a href="{{ site.baseurl }}installing/ami">Amazon EC2 AMI</a>. + The following instructions describe the step-by-step process for + installing Alaveteli. <em>You don't necessarily need to do it this + way:</em> it's usually easier to use the + <a href="{{ site.baseurl }}installing/script">installation script</a> + or the + <a href="{{ site.baseurl }}installing/ami">Amazon EC2 AMI</a>. </p> Note that there are [other ways to install Alaveteli]({{ site.baseurl }}installing). @@ -36,7 +36,7 @@ Next, get hold of the Alaveteli source code from github: git clone https://github.com/mysociety/alaveteli.git cd alaveteli -This will get the development branch, which has the latest (possibly buggy) +This will get the rails-3-develop branch, which has the latest (possibly buggy) code. If you don't want to add or try new features, swap to the master branch (which always contains the latest stable release): @@ -206,10 +206,10 @@ to the test config in `database.yml` (as seen in `database.yml-example`) You will need to set up an email server (MTA) to send and receive emails. Full configuration for an MTA is beyond the scope of this document -- see this -[example config for Exim4]({{ site.baseurl }}installing/exim4). +[example config for Exim4]({{ site.baseurl }}installing/email). Note that in development mode mail is handled by mailcatcher by default so -that you can see the mails in a browser - see http://mailcatcher.me/ for more +that you can see the mails in a browser - see [http://mailcatcher.me/](http://mailcatcher.me/) for more details. Start mailcatcher by running `bundle exec mailcatcher` in your application directory. @@ -243,7 +243,7 @@ When you set up your MTA, if there is some error inside Rails, the email is returned with an exit code 75, which for Exim at least means the MTA will try again later. Additionally, a stacktrace is emailed to `CONTACT_EMAIL`. -See [this example]({{ site.baseurl }}exim4) for a possible configuration for Exim (>=1.9). +See [this example]({{ site.baseurl }}installing/email/) for a possible configuration for Exim (>=1.9). A well-configured installation of this code will have had Exim make a backup copy of the email in a separate mailbox, just in case. @@ -322,7 +322,7 @@ Run the following to get the server running: bundle exec rails server --environment=development By default the server listens on all interfaces. You can restrict it to the -localhost interface by adding ` --binding=127.0.0.1` +localhost interface by adding `--binding=127.0.0.1` The server should have told you the URL to access in your browser to see the site in action. @@ -421,7 +421,7 @@ include the following in an Apache configuration file: Under all but light loads, it is strongly recommended to run the server behind an http accelerator like Varnish. A sample varnish VCL is supplied in -`../conf/varnish-alaveteli.vcl`. +`conf/varnish-alaveteli.vcl`. It's strongly recommended that you run the site over SSL. (Set FORCE_SSL to true in config/general.yml). For this you will need an SSL certificate for your @@ -492,10 +492,10 @@ things that can be automated for deployment. First, you need to check that your MTA is delivering relevant incoming emails to the `script/mailin` command. There are various - ways of setting your MTA up to do this; we have documented one way - of doing it in Exim at `doc/INSTALL-exim4.conf`, including a - command you can use to check that the email routing is set up - correctly. + ways of setting your MTA up to do this; we have documented + [one way of doing it]({{ site.baseurl }}installing/email/#troubleshooting-exim) + in Exim, including a command you can use to check that the email + routing is set up correctly. Second, you need to test that the mailin script itself is working correctly, by running it from the command line, First, find a |