diff options
| -rw-r--r-- | _layouts/page.html | 2 | ||||
| -rw-r--r-- | alaveteli-doc-master.txt | 13 | ||||
| -rw-r--r-- | customising/themes.md | 47 | ||||
| -rw-r--r-- | customising/translation.md | 2 | ||||
| -rw-r--r-- | developers/index.md | 12 | ||||
| -rw-r--r-- | getting_started.md | 36 | ||||
| -rw-r--r-- | glossary.md | 53 | ||||
| -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 | ||||
| -rw-r--r-- | running/server.md | 7 |
11 files changed, 237 insertions, 82 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/customising/themes.md b/customising/themes.md index f6e504eff..63417123f 100644 --- a/customising/themes.md +++ b/customising/themes.md @@ -6,9 +6,9 @@ title: Themes # Alaveteli's themes <p class="lead"> - Alaveteli uses <strong>themes</strong> to make the site look and run - differently from the default. - Simple changes like colour and logo are relatively easy, but themes can also + Alaveteli uses <strong>themes</strong> to make the site look and run + differently from the default. + Simple changes like colour and logo are relatively easy, but themes can also control more complex things like <em>how</em> the site behaves. </p> @@ -24,7 +24,7 @@ about this, [ask for help](/community)! ## What you might want to change The most common requirement is to brand the site: at a minimum, -inserting your own logo and colour scheme. You may also want to tweak +[inserting your own logo](#changing-the-logo) and [colour scheme](#changing-the-colour-scheme). You may also want to tweak the different states that a request can go through. You'll also want to edit the categories that public bodies can appear in (i.e. the groupings on the left hand side of the @@ -49,7 +49,7 @@ code. We try to encapsulate all site-specific functionality in one of these places: -* Site [configuration]({{ site.baseurl }}customisation/config ) +* Site [configuration]({{ site.baseurl }}customising/config) (e.g., the name of your site, the available languages, and so on — all in `config/general.yml`) * Data (e.g. the public bodies to whom requests should be addressed) @@ -58,13 +58,13 @@ places: This document is about what you can do in a theme. By default, the sample theme ("alavetelitheme") has already been -installed. See the setting -[`THEME_URLS`]({{ site.baseurl }}customising/config/#theme_urls) +installed. See the setting +[`THEME_URLS`]({{ site.baseurl }}customising/config/#theme_urls) in `general.yml` for an explanation. You can also install the sample theme by hand, by running: - bundle exec rails plugin install git://github.com/mysociety/alavetelitheme.git + bundle exec rake themes:install The sample theme contains examples for nearly everything you might want to customise. You should probably make a copy, rename it, and @@ -101,24 +101,27 @@ then issue a pull request. Normally, however, you should override these pages **in your own theme**, by placing them at a corresponding location within your theme's `lib/` directory. These means that a file at -`lib/themes/alavetelitheme/lib/help/about.rhml` will appear +`lib/themes/alavetelitheme/lib/views/help/about.rhml` will appear instead of the core "about us" file. -Rails expects all its stylesheets to live at `<railshome>/public`, -which presents a problem for plugins. Here's how we solve it: the -stylesheet and associated resources for your theme live (by -convention) in `alavetelitheme/public/`. This is symlinked from -the main Rails app -- see `alavetelitheme/install.rb` to see how this -happens. +### Changing the logo -The partial at -`alavetelitheme/lib/views/general/_before_head_end.html.erb` includes the -custom CSS in your theme's stylesheet folder (by convention, in -`alavetelitheme/public/stylesheets/`), with: +Alaveteli uses Rails' [asset pipeline](http://guides.rubyonrails.org/asset_pipeline.html) to convert and compress stylesheets written in +<a href="{{ site.baseurl }}glossary/#sass" class="glossary">Sass</a>, +the css extension language, to minified concatenated css. Assets are stored in core Alaveteli under `app/assets` - in `fonts`, `images`, `javascripts` and `stylesheets`. +The default theme has corresponding asset directories in `alavetelitheme/assets` Asset files placed in these directories will override those in the core directories. As with templates, a file at `lib/themes/alavetelitheme/assets/images/logo.png` will appear on the site instead of the logo from `app/assets/images/logo.png`. - <%= stylesheet_link_tag "/alavetelitheme/stylesheets/custom" %> +### Changing the colour scheme -...which will, usually, need changing for your theme. +Alaveteli uses a set of basic +<a href="{{ site.baseurl }}glossary/#sass" class="glossary">Sass</a> +modules to define the layout for the site on different device sizes, and some basic styling. These modules are in `app/assets/stylesheets/responsive`. The colours and fonts are added in the theme - alavetelitheme defines them in `lib/themes/alavetelitheme/assets/stylesheets/responsive/custom.scss`. Colours used in the theme are defined as variables at the top of this file and you can edit them here. + +### Changing other styling + +To change other styling, you can add to or edit the styles in `lib/themes/alavetelitheme/assets/stylesheets/responsive/custom.scss`. Styles defined here will override those in the sass modules in `app/assets/stylesheets/responsive` as they will be imported last by `app/assets/stylesheets/responsive/all.scss`. However, if you want to substantially change the way a particular part of the site is laid out, you may want to override one of the core sass modules. You could override the layout of the front page, for example, by copying `app/assets/stylesheets/responsive/_frontpage_layout.scss` to `lib/themes/alavetelitheme/assets/stylesheets/responsive/_frontpage_layout.scss` and editing it. + +You can load extra stylesheets and javascript files by adding them to `lib/themes/alavetelitheme/lib/views/general/_before_head_end.html.erb` ## Adding your own categories for public bodies @@ -185,4 +188,4 @@ necessary. ## Adding or overriding models and controllers -If you need to extend the behaviour of Alaveteli at the controller or model level, see `alavetelitheme/lib/controller_patches.rb` and `alavetelitheme/lib/model_patches.rb` for examples.
\ No newline at end of file +If you need to extend the behaviour of Alaveteli at the controller or model level, see `alavetelitheme/lib/controller_patches.rb` and `alavetelitheme/lib/model_patches.rb` for examples. diff --git a/customising/translation.md b/customising/translation.md index 927067f89..a403f6396 100644 --- a/customising/translation.md +++ b/customising/translation.md @@ -28,7 +28,7 @@ need to know about the one that applies to you. ## Translation process: translator's view -**If you're just working on translating Alavetli into a language you know, then +**If you're just working on translating Alaveteli into a language you know, then this section is for you.** When a developer adds a new feature to the user interface in Alaveteli, they 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 d3711d276..2911aecf3 100644 --- a/getting_started.md +++ b/getting_started.md @@ -180,15 +180,14 @@ http://blogger.com and announce your project with a new blog post. Next, think about the visual identity. At a minimum, you should probably replace the default Alaveteli logo that you can see at the top left of -http://demo.alaveteli.org. It's also easy to change the colour scheme. +<http://demo.alaveteli.org>. It's also easy to change the colour scheme. If you have a bit more budget and time, you can rework the design more, with a 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 @@ -218,14 +217,14 @@ therefore relevant only to the UK. You should take these pages as inspiration, but review their content with a view to your jurisdiction. The important pages to translate are: -* [About](https://github.com/mysociety/alaveteli/blob/develop/app/views/help/about.rhtml): why the website exists, why it works, etc -* [contact](https://github.com/mysociety/alaveteli/blob/develop/app/views/help/contact.rhtml): how to get in touch -* [credits](https://github.com/mysociety/alaveteli/blob/develop/app/views/help/credits.rhtml): who is involved in the site. Importantly, includes a section on how users can help the project. -* [officers](https://github.com/mysociety/alaveteli/blob/develop/app/views/help/officers.rhtml): information for the officers who deal with FOI at authorities. They get a link to this page in emails that the site sends them. -* [privacy](https://github.com/mysociety/alaveteli/blob/develop/app/views/help/privacy.rhtml): privacy policy, plus information making it clear that requests are going to appear on the internet. Let users know if they are allowed to use pseudonyms in your jurisdiction. -* [requesting](https://github.com/mysociety/alaveteli/blob/develop/app/views/help/requesting.rhtml): the main help page about making requests. How it works, how to decide who to write to, what they can expect in terms of responses, how to make appeals, etc. -* [unhappy](https://github.com/mysociety/alaveteli/blob/develop/app/views/help/unhappy.rhtml): users are taken to this page after a request that has been somehow unsuccessful (e.g. the request has been refused, or the authority is insisting on a postal request). The page should encourage them to keep going, e.g. by starting a new request or addressing it to a different body. -* [why email](https://github.com/mysociety/alaveteli/blob/develop/app/views/help/_why_they_should_reply_by_email.rhtml): a snippet of information that explains why users should insist on replies by email. This is displayed next to requests that have "gone postal". +* [About](https://github.com/mysociety/alaveteli/blob/master/app/views/help/about.rhtml): why the website exists, why it works, etc +* [contact](https://github.com/mysociety/alaveteli/blob/master/app/views/help/contact.rhtml): how to get in touch +* [credits](https://github.com/mysociety/alaveteli/blob/master/app/views/help/credits.rhtml): who is involved in the site. Importantly, includes a section on how users can help the project. +* [officers](https://github.com/mysociety/alaveteli/blob/master/app/views/help/officers.rhtml): information for the officers who deal with FOI at authorities. They get a link to this page in emails that the site sends them. +* [privacy](https://github.com/mysociety/alaveteli/blob/master/app/views/help/privacy.rhtml): privacy policy, plus information making it clear that requests are going to appear on the internet. Let users know if they are allowed to use pseudonyms in your jurisdiction. +* [requesting](https://github.com/mysociety/alaveteli/blob/master/app/views/help/requesting.rhtml): the main help page about making requests. How it works, how to decide who to write to, what they can expect in terms of responses, how to make appeals, etc. +* [unhappy](https://github.com/mysociety/alaveteli/blob/master/app/views/help/unhappy.rhtml): users are taken to this page after a request that has been somehow unsuccessful (e.g. the request has been refused, or the authority is insisting on a postal request). The page should encourage them to keep going, e.g. by starting a new request or addressing it to a different body. +* [why email](https://github.com/mysociety/alaveteli/blob/master/app/views/help/_why_they_should_reply_by_email.rhtml): a snippet of information that explains why users should insist on replies by email. This is displayed next to requests that have "gone postal". The help pages contain some HTML. Your tech person should be able to advise on this. @@ -236,10 +235,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 @@ -287,9 +287,9 @@ called Transifex. This website allows teams of translators to collaborate in one place, using a fairly easy interface. The Alaveteli page on Transifex is at -https://www.transifex.net/projects/p/alaveteli/; the translations all live in a +<https://www.transifex.com/projects/p/alaveteli/>; the translations all live in a single translation file called -[`app.pot`](https://www.transifex.net/projects/p/alaveteli/resource/apppot/). +[`app.pot`](https://www.transifex.com/projects/p/alaveteli/resource/apppot/). You can set up your language and provide translations there; you can also use specialise software on your own computer (see the help pages on Transifex) @@ -310,7 +310,7 @@ review the untranslated strings. ## Step five: Test drive the site For launch, the tech person should review the [Production Server Best -Practices](FIXME). +Practices]({{ site.baseurl }}running/server). A low-key launch, where you tell just a few trusted people about the site, is a very good idea. You can then track how things work, and gauge the responses of diff --git a/glossary.md b/glossary.md index 32952be1e..d641f7451 100644 --- a/glossary.md +++ b/glossary.md @@ -25,6 +25,8 @@ 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="#sass">Sass</a></li> <li><a href="#state">state</a></li> <li><a href="#theme">theme</a></li> </ul> @@ -192,8 +194,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 +239,53 @@ 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="sass">Sass</a> (for generating CSS) + </dt> + <dd> + Alaveteli's cascading stylesheets (CSS) control how the pages appear, and + are defined using <strong>Sass</strong>. It's technically a CSS extension + language, and we use it because it's easier to manage than writing CSS + directly (for example, Sass lets you easily make a single change that will + be applied to many elements across the whole site). + <a href="#rails" class="glossary">Rails</a> notices if you change any of + the Sass files, and automatically re-generates the CSS files that the + website uses. + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + <a href="http://sass-lang.com">Sass website</a> + </li> + <li> + more about <a href="{{ site.baseurl }}customising/themes/#changing-the-colour-scheme">changing + your colour scheme</a>, which uses Sass + </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..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 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 |