diff options
| -rw-r--r-- | _layouts/page.html | 2 | ||||
| -rw-r--r-- | alaveteli-doc-master.txt | 13 | ||||
| -rw-r--r-- | developers/index.md | 12 | ||||
| -rw-r--r-- | getting_started.md | 12 | ||||
| -rw-r--r-- | glossary.md | 26 | ||||
| -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 | 14 | ||||
| -rw-r--r-- | running/server.md | 7 |
9 files changed, 163 insertions, 38 deletions
diff --git a/_layouts/page.html b/_layouts/page.html index c82d159fb..6f060d252 100644 --- a/_layouts/page.html +++ b/_layouts/page.html @@ -22,7 +22,7 @@ layout: default <li><a href="{{ site.baseurl }}installing/ami">Alaveteli AMI for EC2</a></li> <li><a href="{{ site.baseurl }}installing/manual_install">Installing by hand</a></li> <li><a href="{{ site.baseurl }}installing/macos">MacOS X</a></li> - <li><a href="{{ site.baseurl }}installing/exim4">MTA (email)</a></li> + <li><a href="{{ site.baseurl }}installing/email">MTA (email)</a></li> </ul> </li> <li><a href="{{ site.baseurl }}customising/">Customising</a> diff --git a/alaveteli-doc-master.txt b/alaveteli-doc-master.txt index f7fc316ef..f22983e45 100644 --- a/alaveteli-doc-master.txt +++ b/alaveteli-doc-master.txt @@ -29,6 +29,19 @@ These pages (in the wiki) have work/attention still pending: [>>] [no] Setting up a demo site <-- TODO should be in the docs, a useful page with some overlap +These pages are form the repo's doc/ directory +---------------------------------------------- + +[ ] [ ] CHANGES.md +[ ] [ ] DEPLOY.md +[ ] [ ] INSTALL-exim4.md +[ ] [ ] INSTALL-postfix.md +[ ] [ ] INSTALL.md +[ ] [ ] THEME-ASSETS-UPGRADE.md +[ ] [ ] THEMES-UPGRADE.md +[ ] [ ] THEMES.md +[ ] [ ] TRANSLATE.md + These pages are all effetively done (i.e., definitively settled in the docs) diff --git a/developers/index.md b/developers/index.md index a358b2d3f..85ed3f80f 100644 --- a/developers/index.md +++ b/developers/index.md @@ -39,11 +39,13 @@ title: For developers * Installing the software is a little involved, though it's getting easier. If you stick to Debian or Ubuntu, it should be possible to get a running version - within a few hours. The documentation is in - [INSTALL.md](https://github.com/mysociety/alaveteli/blob/develop/doc/INSTALL.m - d). There is an [Alaveteli EC2 AMI]({{ site.baseurl }}installing/ami/) that - might help you get up and running quickly. [Get in - touch](http://www.alaveteli.org/contact/) on the project mailing list or IRC + within a few hours. If you've got your own server, run the + [installation script]({{ site.baseurl }}installing/script/), or follow the + instructions for a + [manual installation]({{ site.baseurl }}installing/manual_install/). + Alternatively, there's an [Alaveteli EC2 AMI]({{ site.baseurl }}installing/ami/) + that might help you get up and running quickly. + [Get in touch](http://www.alaveteli.org/contact/) on the project mailing list or IRC for help. * A standard initial step for customising your deployment is [writing a diff --git a/getting_started.md b/getting_started.md index 3df3b286c..c8dd9d0cf 100644 --- a/getting_started.md +++ b/getting_started.md @@ -188,8 +188,7 @@ custom homepage, different fonts, etc; however, the more you customise the site, the harder it is to upgrade in the future; and you'll need a developer and/or designer to help do these customisations. We call the custom set of colours, fonts, logos etc a "theme"; there are some notes for developers about -[writing a -theme](https://github.com/mysociety/alaveteli/blob/master/doc/THEMES.md). You +[writing a theme]({{ site.baseurl }}customising/themes/). You might spend anywhere between 1 and 15 days on this. ### Legislative differences @@ -237,10 +236,11 @@ Now is also a good time to start thinking about some of your standard emails that you'll be sending out in response to common user queries and administrative tasks -- for example, an email that you send to IT departments asking them to whitelist emails from your Alaveteli website (if your emails are -being marked as spam). Review the [Administrator's -Manual](/running/admin_manual.md) for details on some of the common administrative tasks. There is a list of the -standard emails used by WhatDoTheyKnow on the [FOI Wiki]( -http://foiwiki.com/foiwiki/index.php/Common_WhatDoTheyKnow_support_responses). +being marked as spam). See the +[Administrator's Manual]({{ site.baseurl }}running/admin_manual/) for details +on some of the common administrative tasks. There is a list of the +standard emails used by WhatDoTheyKnow on the +[FOI Wiki](http://foiwiki.com/foiwiki/index.php/Common_WhatDoTheyKnow_support_responses). ### Other software customisations diff --git a/glossary.md b/glossary.md index 32952be1e..cfd559445 100644 --- a/glossary.md +++ b/glossary.md @@ -25,6 +25,7 @@ Definitions <li><a href="#publish">publish</a></li> <li><a href="#request">request</a></li> <li><a href="#response">response</a></li> + <li><a href="#rails">Ruby on Rails</a></li> <li><a href="#state">state</a></li> <li><a href="#theme">theme</a></li> </ul> @@ -192,8 +193,8 @@ Definitions <p>More information:</p> <ul> <li> - see these instructions for <a href="{{ site.baseurl }}installing/exim4">configuring exim4</a>, - a common MTA + see these instructions for <a href="{{ site.baseurl }}installing/email">configuring your MTA</a> + (examples are for exim4 and postfix, two of the most common) </li> </ul> </div> @@ -237,6 +238,27 @@ Definitions </dd> <dt> + <a name="rails">Ruby on Rails</a> (also Rails) + </dt> + <dd> + Alaveteli is written in the Ruby programming language, using + the web application framework "Ruby on Rails". + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + <a href="http://rubyonrails.org/">Ruby on Rails</a> website + </li> + <li> + Alavateli's <a href="{{ site.baseurl }}developers/directory_structure/">directory structure</a> + is influenced by its use of Ruby on Rails + </li> + </ul> + </div> + + </dd> + + <dt> <a name="state">state</a> </dt> <dd> 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..6d17bd8e9 100644 --- a/installing/manual_install.md +++ b/installing/manual_install.md @@ -206,7 +206,7 @@ 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 @@ -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. @@ -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 diff --git a/running/server.md b/running/server.md index 95f69b63d..703372cd4 100644 --- a/running/server.md +++ b/running/server.md @@ -65,11 +65,10 @@ achieved with rewrite rules that redirect URLs beginning with `/admin`. ## Email configuration -See the application-specific -[email configuration for exim]({{ site.baseurl }}installing/exim4) for +See the [configuration for exim or postfix]({{ site.baseurl }}installing/email/) for setting up your Mail Transfer Agent (MTA). It is possible to use other MTAs — -if you use a different one, the documentation for exim should provide you with -enough information to get started. If you do use a different one, please add to the +if you use a different one, the documentation there should provide you with +enough information to get started. If this applies to you, please add to the documentation! On a live server, you should also consider the following, to increase the |