diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/customising/config.md | 6 | ||||
| -rw-r--r-- | docs/customising/themes.md | 4 | ||||
| -rw-r--r-- | docs/developers/api.md | 6 | ||||
| -rw-r--r-- | docs/developers/directory_structure.md | 119 | ||||
| -rw-r--r-- | docs/developers/i18n.md | 24 | ||||
| -rw-r--r-- | docs/developers/index.md | 2 | ||||
| -rw-r--r-- | docs/getting_started.md | 15 | ||||
| -rw-r--r-- | docs/glossary.md | 62 | ||||
| -rw-r--r-- | docs/installing/ami.md | 17 | ||||
| -rw-r--r-- | docs/installing/deploy.md | 62 | ||||
| -rw-r--r-- | docs/installing/index.md | 24 | ||||
| -rw-r--r-- | docs/installing/manual_install.md | 206 | ||||
| -rw-r--r-- | docs/installing/next_steps.md | 34 | ||||
| -rw-r--r-- | docs/installing/script.md | 24 | ||||
| -rw-r--r-- | docs/installing/vagrant.md | 70 | ||||
| -rw-r--r-- | docs/running/admin_manual.md | 6 | ||||
| -rw-r--r-- | docs/running/index.md | 2 | ||||
| -rw-r--r-- | docs/running/states.md | 4 | ||||
| -rw-r--r-- | docs/running/states_informatazyrtare.md | 2 | ||||
| -rw-r--r-- | docs/running/upgrading.md | 2 |
20 files changed, 465 insertions, 226 deletions
diff --git a/docs/customising/config.md b/docs/customising/config.md index 191141749..906af3702 100644 --- a/docs/customising/config.md +++ b/docs/customising/config.md @@ -638,9 +638,9 @@ THEME_URLS: </dt> <dd> Is this a - <a href="{{site.baseurl}}docs/glossary/#staging" class="glossary">staging</a> or - <a href="{{site.baseurl}}docs/glossary/#development" class="glossary">development</a> site? - If not, it's a live <a href="{{site.baseurl}}docs/glossary/#production" class="glossary">production</a> + <a href="{{site.baseurl}}docs/glossary/#staging" class="glossary__link">staging</a> or + <a href="{{site.baseurl}}docs/glossary/#development" class="glossary__link">development</a> site? + If not, it's a live <a href="{{site.baseurl}}docs/glossary/#production" class="glossary__link">production</a> site. This setting controls whether or not the <code>rails-post-deploy</code> script will create the file <code>config/rails_env.rb</code> file to force Rails into production environment. diff --git a/docs/customising/themes.md b/docs/customising/themes.md index bad1639d7..7db02f7eb 100644 --- a/docs/customising/themes.md +++ b/docs/customising/themes.md @@ -107,14 +107,14 @@ instead of the core "about us" file. ### Changing the logo Alaveteli uses Rails' [asset pipeline](http://guides.rubyonrails.org/asset_pipeline.html) to convert and compress stylesheets written in -<a href="{{ site.baseurl }}docs/glossary/#sass" class="glossary">Sass</a>, +<a href="{{ site.baseurl }}docs/glossary/#sass" class="glossary__link">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`. ### Changing the colour scheme Alaveteli uses a set of basic -<a href="{{ site.baseurl }}docs/glossary/#sass" class="glossary">Sass</a> +<a href="{{ site.baseurl }}docs/glossary/#sass" class="glossary__link">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 diff --git a/docs/developers/api.md b/docs/developers/api.md index cbd4c7c85..1e6c15cfd 100644 --- a/docs/developers/api.md +++ b/docs/developers/api.md @@ -22,7 +22,7 @@ these ways: * Look for the RSS feed links. * Examine the `<link rel="alternate" type="application/atom+xml">` tag in the head of the HTML. -* Add `/feed` to the start of another URL. +* Add `/feed` to the start of another URL. Note that even complicated search queries have Atom feeds. You can do all sorts of things with them, such as query by authority, by file type, by date range, @@ -73,9 +73,13 @@ as follows: * as form variable `json`: * `direction` - either `request` (from the user - might be a followup, reminder, etc) or `response` (from the authority) * `body` - the message itself + * `state` - optional, allows the authority to include an updated request `state` value when sending an update. Allowable values: `waiting_response`, `rejected`, `successful` and `partially_successful`. Only used in the `response` direction * `sent_at` - ISO-8601 formatted time that the correspondence was sent * (optionally) the variable `attachments` as `multipart/form-data`: * attachments to the correspondence. Attachments can only be attached to messages in the `response` direction +* `/api/v2/request/<id>/update.json` - POST a new state for the request: + * as form variable `json`: + * `state` - the user's assessment of the `state` of a request that has received a response from the authority. Allowable values: `waiting_response`, `rejected`, `successful` and `partially_successful`. Should only be used for the user's feedback, an authority wishing to update the request `state` should use `/api/v2/request/<id>.json` instead diff --git a/docs/developers/directory_structure.md b/docs/developers/directory_structure.md index 9dbe06789..34a92b411 100644 --- a/docs/developers/directory_structure.md +++ b/docs/developers/directory_structure.md @@ -33,6 +33,30 @@ website](http://guides.rubyonrails.org/getting_started.html). <p><em>the core Alaveteli application code</em></p> <dl> <dt> + assets + </dt> + <dd> + <em>static assets that require precompilation before being served</em> + <dl> + <dt> + fonts + </dt> + <dt> + images + </dt> + <dt> + javascripts + </dt> + <dt class="last"> + stylesheets + </dt> + <dd class="last"> + <p><em>stylesheets in CSS or <a href="http://sass-lang.com/">SCSS</a> format.</em></p> + <p>SCSS stylesheets are compiled to CSS.</p> + </dd> + </dl> + </dd> + <dt> controllers </dt> <dt> @@ -44,54 +68,16 @@ website](http://guides.rubyonrails.org/getting_started.html). <dt> models </dt> - <dt> - sass - </dt> <dt class="last"> views </dt> </dl> </dd> - <dt> - assets + <dt>cache </dt> - <dd> - Static assets - <dl> - <dt> - css - </dt> - <dd> - Rendered stylesheets - </dd> - <dt> - img - </dt> - <dd> - static images - </dd> - <dt> - sass - </dt> - <dd> - Stylesheets in SCSS format, which are compiled to CSS - </dd> - <dt class="last"> - scripts - </dt> - <dd class="last"> - JavaScript - </dd> - </dl> + <dd><p><em>cached files for downloads, attachments and templates.</em></p> </dd> <dt> - bootstrap - </dt> - <dd> - <p> - Alaveteli's default style uses Bootstrap. - </p> - <dt> commonlib </dt> <dd> @@ -155,9 +141,13 @@ website](http://guides.rubyonrails.org/getting_started.html). <dt> tasks </dt> + <dd><a href="http://guides.rubyonrails.org/command_line.html#rake">Rake</a> tasks. + </dd> <dt class="last"> - whatdotheyknow + themes </dt> + <dd class="last">This is where your Alaveteli theme lives. + </dd> </dl> </dd> <dt> @@ -171,33 +161,15 @@ website](http://guides.rubyonrails.org/getting_started.html). </p> </dd> <dt> - public + log </dt> <dd> - <p><em>static assets</em></p> - <dl> - <dt> - admin - </dt> - <dd> - images, JavaScript and stylesheets used by the admin back-end - </dd> - <dt> - fcgi - </dt> - <dd> - Fast CGI files for serving static assets - </dd> - <dt> - images - </dt> - <dt> - javascripts - </dt> - <dt class="last"> - stylesheets - </dt> - </dl> + <p><em>application log files.</em></p> + </dd> + <dt> + public + </dt> + <dd> <p><em>static files that can be served directly.</em></p> </dd> <dt> script @@ -219,17 +191,6 @@ website](http://guides.rubyonrails.org/getting_started.html). </p> </dd> <dt> - stylesheets - </dt> - <dd> - <p> - <em>global stylesheet</em> - </p> - <p> - Actually just <code>global.css</code> - </p> - </dd> - <dt> tmp </dt> <dd> @@ -243,10 +204,10 @@ website](http://guides.rubyonrails.org/getting_started.html). <dd class="last"> <p><em>third-party software</em></p> <dl> - <dt class="last">plugins</dt> + <dt class="last">bundle</dt> <dd class="last"> <p> - Plugins + <em>the bundle of gems needed to run Alaveteli</em> </p> </dd> </dl> diff --git a/docs/developers/i18n.md b/docs/developers/i18n.md index deabc99a1..24c0c31e0 100644 --- a/docs/developers/i18n.md +++ b/docs/developers/i18n.md @@ -7,7 +7,7 @@ title: Internationalisation (for devs) <p class="lead"> This page describes some technical aspects of internationalising the - Alaveteli code. It's mostly aimed at devs who are working on the + Alaveteli code. It's mostly aimed at devs who are working on the codebase — if you just want to translate Alaveteli into your own language, see <a href="{{ site.baseurl }}docs/customising/translation">translating Alaveteli</a> @@ -29,11 +29,27 @@ work and turns it into the files that Alaveteli needs (using gettext). For example, to deploy English and Spanish translations at once: - * Ensure their `.po` files are at ```locale/en/app.po``` and ```locale/es/app.po``` + * Ensure their `.po` files are at ```locale/en/app.po``` and ```locale/es/app.po``` (for example, by downloading them from Transifex) * Set <code><a href="{{ site.baseurl }}docs/customising/config/#available_locales">AVAILABLE_LOCALES</a></code> to <code>en es</code> +### What to do if you don't have complete translations for an older release of Alaveteli + +Before a new release of Alaveteli is made, the translation files are +pulled from Transifex and added to Alaveteli's ``locale/`` directory in +github. These represent the most complete translations for the previous +release. Then the files in Transifex are updated with any new strings +that need to be translated for the upcoming release. At this point old +strings that are no longer used in the new release are also removed. The +latest [release tag](https://github.com/mysociety/alaveteli/releases) +for a release in github should contain the most complete translations +for that release from Transifex. + +If you're using an older release of Alaveteli and you want to add to or +change the translations, you can edit the .po files directly using a +local program such as [PoEdit](http://poedit.net/). + ### How to add new strings to the translations You need to do this if you've added any new strings to the code that need @@ -63,7 +79,7 @@ For more details about the translations, see the page about This is complicated by the fact that there are two competing ways to define a locale+territory combination. The POSIX (and gettext and Transifex) way is like `en_GB`; the Rails way is like `en-US`. Because we are using gettext and -Transifex for translations, we must deal with both. +Transifex for translations, we must deal with both. * for the Rails version of the currently selected locale, use `I18n.locale` * for the POSIX version of the locale, use `FastGettext.locale` @@ -85,7 +101,7 @@ Some hints for adding the strings into the Alaveteli code: * We allow some inline HTML where it helps with meaningful context, for example: ``` -_('<a href="{{browse_url}}">Browse all</a> or <a href="{{add_url}}">ask us to add it</a>.', +_('<a href="{{browse_url}}">Browse all</a> or <a href="{{add_url}}">ask us to add it</a>.', :browse_url => @browse_url, :add_url => @add_url) ``` diff --git a/docs/developers/index.md b/docs/developers/index.md index 22390f236..f1167a22b 100644 --- a/docs/developers/index.md +++ b/docs/developers/index.md @@ -45,7 +45,7 @@ title: For developers [manual installation]({{ site.baseurl }}docs/installing/manual_install/). Alternatively, there's an [Alaveteli EC2 AMI]({{ site.baseurl }}docs/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 + [Get in touch]({{ site.baseurl }}community/) on the project mailing list or IRC for help. * A standard initial step for customising your deployment is [writing a diff --git a/docs/getting_started.md b/docs/getting_started.md index 5c5a7437d..eddcf78a6 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -108,12 +108,13 @@ You'll need to find a tech person who knows about hosting websites using Apache and Linux. They don't need to know Ruby on Rails, but it would be a huge advantage if they do. -You'll also need to source a server. You should ask your tech person to help -with this. The minimum spec for running a low traffic website is 512MB RAM and -a 20GB disk. 2GB RAM would be ideal. We recommend Debian Squeeze 64-bit as the -operating system, though any sort of Linux should do. Rackspace offer suitable -cloud servers, which start out at around $25 / month. Then your tech person -should follow the [installation documentation]({{ site.baseurl }}docs/installing/). +You'll also need to source a server. You should ask your tech person to +help with this. The minimum spec for running a low traffic website is +512MB RAM and a 20GB disk. 2GB RAM would be ideal. We recommend the +latest Debian Wheezy (7) or Squeeze (6) 64-bit or Ubuntu precise (12.04) +as the operating system. Rackspace offer suitable cloud servers, which +start out at around $25 / month. Then your tech person should follow the +[installation documentation]({{ site.baseurl }}docs/installing/). Alternatively, you could use Amazon Web Services. This has the added advantage that you can use our preconfigured [Alaveteli EC2 @@ -140,7 +141,7 @@ can see what requests look like to them. When trying things out, you need to wear several hats -- as a site administrator, an ordinary site user, and as a public authority. This can get confusing with several email addresses, so one quick and easy way to manage -this is to use a throwaway email service like http://mailinator.com. +this is to use a throwaway email service like [Mailinator](http://mailinator.com). <a name="step-2"> </a> diff --git a/docs/glossary.md b/docs/glossary.md index 493c0a5eb..989bf4ce6 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -81,12 +81,12 @@ Definitions <a name="agnostic">asker agnostic</a> </dt> <dd> - <a href="#foi" class="glossary">Freedom of Information</a> (FoI) law typically considers - the <a href="#response" class="glossary">responses</a> given by the - <a href="#authority" class="glossary">authorities</a> to be <strong>asker agnostic</strong>. This means + <a href="#foi" class="glossary__link">Freedom of Information</a> (FoI) law typically considers + the <a href="#response" class="glossary__link">responses</a> given by the + <a href="#authority" class="glossary__link">authorities</a> to be <strong>asker agnostic</strong>. This means that the reply should not be any different depending on <em>who</em> asked for the information. One consequence of this is that the response - can be <a href="#publish" class="glossary">published</a>, because in theory <em>everyone</em> + can be <a href="#publish" class="glossary__link">published</a>, because in theory <em>everyone</em> could ask for it and expect, by law, to receive the same information. <p> Despite this, it's still very common all around the world for authorities to reply @@ -102,7 +102,7 @@ Definitions </dt> <dd> An <strong>authority</strong> is the term we use for any of the bodies, organisations, - departments, or companies to which users can send <a href="#request" class="glossary">requests</a>. + departments, or companies to which users can send <a href="#request" class="glossary__link">requests</a>. <div class="more-info"> <p>More information:</p> <ul> @@ -111,7 +111,7 @@ Definitions </li> <li> Authorities are usually, but not always, public bodies that are obliged by the local - <a href="#foi" class="glossary">Freedom of Information</a> (FoI) law to respond. Sometimes an + <a href="#foi" class="glossary__link">Freedom of Information</a> (FoI) law to respond. Sometimes an Alaveteli site is set up in a jurisdiction that does not yet have FoI law. In the UK, we add some authorites to our <a href="https://www.whatdotheyknow.com">WhaDoTheyKnow</a> site that are not subject to FoI law, but which have either voluntarily submitted themselves @@ -192,7 +192,7 @@ Definitions <dd> Alaveteli administrators can define <strong>censor rules</strong> to define which parts of replies or responses should be - <a href="#redact" class="glossary">redacted</a>. + <a href="#redact" class="glossary__link">redacted</a>. </p> <div class="more-info"> <p>More information:</p> @@ -219,9 +219,9 @@ Definitions so you can <a href="{{ site.baseurl }}docs/customising/">customise it</a>, experiment with different settings, and test that it does what you expect. This is different from a - <a href="#production" class="glossary">production server</a>, which is the one your + <a href="#production" class="glossary__link">production server</a>, which is the one your users actually visit running with live data, or a - <a href="#staging" class="glossary">staging server</a>, + <a href="#staging" class="glossary__link">staging server</a>, which is used for testing code before it goes live. <p> On your dev server, you should set @@ -312,7 +312,7 @@ Definitions <dd> A <strong>Mail Tranfer Agent</strong> is the the program which actually sends and receives email. Alaveteli sends email on behalf of its users, and processes - the <a href="#response" class="glossary">responses</a> and replies it receives. + the <a href="#response" class="glossary__link">responses</a> and replies it receives. All this email goes through the MTA, which is a seperate service on your system. <div class="more-info"> <p>More information:</p> @@ -330,7 +330,7 @@ Definitions </dt> <dd> Alaveteli can use <strong>New Relic</strong>'s application monitoring tool to track the - performance of your <a href="#production" class="glossary">production site</a>. If enabled, + performance of your <a href="#production" class="glossary__link">production site</a>. If enabled, data from your application is gathered on the New Relic website, which you can inspect with their visual tools. Basic use is free. <div class="more-info"> @@ -389,14 +389,14 @@ Definitions <dd> A <strong>production server</strong> is one that is running your Alaveteli site for real users, with live data. This is different from a - <a href="#development" class="glossary">development server</a>, which you use make your + <a href="#development" class="glossary__link">development server</a>, which you use make your customisation and environment changes and try to get them to all work OK, or a - <a href="#staging" class="glossary">staging server</a>, which is used for testing code + <a href="#staging" class="glossary__link">staging server</a>, which is used for testing code and configuration after it's been finished but before it goes live. <p> Your production site should be configured to run as efficiently as possible: for example, caching is enabled, and debugging switched off. - <a href="#rails" class="glossary">Rails</a> has a "production mode" which does + <a href="#rails" class="glossary__link">Rails</a> has a "production mode" which does this for you: set <code><a href="{{site.baseurl}}docs/customising/config/#staging_site">STAGING_SITE</a></code> to <code>0</code>. Note that if you <em>change</em> this setting after you've @@ -419,9 +419,9 @@ Definitions </dt> <dd> Alaveteli works by <strong>publishing</strong> the - <a href="#response" class="glossary">responses</a> it recieves to the - <a href="#foi" class="glossary">Freedom of Information</a> - <a href="#request" class="glossary">requests</a> that its users send. + <a href="#response" class="glossary__link">responses</a> it recieves to the + <a href="#foi" class="glossary__link">Freedom of Information</a> + <a href="#request" class="glossary__link">requests</a> that its users send. It does this by processing the emails it receives and presenting them as pages — one per request — on the website. This makes it easy for people to find, read, link to, and share the request and the @@ -478,7 +478,7 @@ Definitions </li> <li> you can do text-only redaction with Alaveteli's - <a href="#censor-rule" class="glossary">censor rules</a> + <a href="#censor-rule" class="glossary__link">censor rules</a> </li> <li> some things are easier to redact than others — especially in PDFs, @@ -496,8 +496,8 @@ Definitions A <strong>regular expression</strong> is a concise way to describe a pattern or sequence of characters, letters or words. As an administrator, you may find regular expressions useful if you need to define <a - href="#censor-rule" class="glossary">censor rules</a>. For example, instead - of <a href="#redact" class="glossary">redacting</a> just one specific + href="#censor-rule" class="glossary__link">censor rules</a>. For example, instead + of <a href="#redact" class="glossary__link">redacting</a> just one specific phrase, you can describe a whole range of <em>similar</em> phrases with one single regular expression. <p> @@ -564,11 +564,11 @@ Definitions </dt> <dd> In Alaveteli, a <strong>request</strong> is the - <a href="#foi" class="glossary">Freedom of Information</a> request + <a href="#foi" class="glossary__link">Freedom of Information</a> request that a user enters, and which the site then emails to the relevant - <a href="#authority" class="glossary">authority</a>. - Alaveteli automatically <a href="#publish" class="glossary">publishes</a> - the <a href="#response" class="glossary">responses</a> + <a href="#authority" class="glossary__link">authority</a>. + Alaveteli automatically <a href="#publish" class="glossary__link">publishes</a> + the <a href="#response" class="glossary__link">responses</a> to all the requests it sends. </dd> @@ -577,8 +577,8 @@ Definitions </dt> <dd> A <strong>response</strong> is the email sent by an - <a href="#authority" class="glossary">authority</a> in reply to - a user's <a href="#request" class="glossary">requests</a>. + <a href="#authority" class="glossary__link">authority</a> in reply to + a user's <a href="#request" class="glossary__link">requests</a>. </dd> <dt> @@ -610,7 +610,7 @@ Definitions 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 + <a href="#rails" class="glossary__link">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"> @@ -633,9 +633,9 @@ Definitions <dd> A <strong>staging server</strong> is one that you use for testing code or configuration before it goes live. This is different from a <a href="#development" - class="glossary">development server</a>, on which you change the code and settings to + class="glossary__link">development server</a>, on which you change the code and settings to make everything work, or the - <a href="#production" class="glossary">production server</a>, which is the + <a href="#production" class="glossary__link">production server</a>, which is the site your users visit running with live data. <p> On your staging server, you should set @@ -658,14 +658,14 @@ Definitions <a name="state">state</a> </dt> <dd> - Each <a href="#request" class="glossary">request</a> passes through different + Each <a href="#request" class="glossary__link">request</a> passes through different <strong>states</strong> as it progresses through the system. States help Alaveteli administrators, as well as the public, understand the current situation with any request and what action, if any, is required. <p> The states available can be customised within - your site's <a href="#theme" class="glossary">theme</a>. + your site's <a href="#theme" class="glossary__link">theme</a>. </p> <div class="more-info"> <p>More information:</p> diff --git a/docs/installing/ami.md b/docs/installing/ami.md index 1f7195761..cee4f88af 100644 --- a/docs/installing/ami.md +++ b/docs/installing/ami.md @@ -1,6 +1,6 @@ --- layout: page -title: Installing the easy way +title: Installation from AMI --- # Installation on Amazon EC2 @@ -13,11 +13,13 @@ Note that there are [other ways to install Alaveteli]({{ site.baseurl }}docs/ins ## Installing from our AMI -To help people try out Alaveteli, we have created an AMI (Amazon Machine Image) -with a basic installation of Alaveteli, which you can use to create a running -server on an Amazon EC2 instance. This creates an instance that runs in -development mode, so we wouldn't recommend you use it for a production system -without changing the configuration. +To help people try out Alaveteli, we have created an AMI (Amazon Machine +Image) with a basic installation of Alaveteli (installed using the +[installation script]({{ site.baseurl }}docs/installing/script/)), which +you can use to create a running server on an Amazon EC2 instance. This +creates an instance that runs in development mode, so we wouldn't +recommend you use it for a production system without changing the +configuration. Unfortunately, Alaveteli will not run properly on a free Micro instance due to the low amount of memory available on those @@ -57,3 +59,6 @@ If you have any problems or questions, please ask on the [Alaveteli Google Group](https://groups.google.com/forum/#!forum/alaveteli-dev) or [report an issue](https://github.com/mysociety/alaveteli/issues?state=open). +##What next? + +Check out the [next steps]({{ site.baseurl }}docs/installing/next_steps/). diff --git a/docs/installing/deploy.md b/docs/installing/deploy.md index 4bbc91a9d..64ecde088 100644 --- a/docs/installing/deploy.md +++ b/docs/installing/deploy.md @@ -8,7 +8,8 @@ title: Deploying <p class="lead"> Although you can install Alaveteli and just change it when you need it, we recommend you adopt a way of <strong>deploying</strong> it automatically, - especially on your <a href="{{ site.baseurl }}docs/glossary/#production">production server</a>. + especially on your + <a href="{{ site.baseurl }}docs/glossary/#production" class="glossary__link">production server</a>. Alaveteli provides a deployment mechanism using Capistrano. </p> @@ -27,13 +28,13 @@ changes or copying files by hand, so your site will be down for the shortest possible time. We **strongly recommend** you use the deployment mechanism for your -<a href="{{ site.baseurl }}docs/glossary/#production">production server</a> and, if -you're running one, your -<a href="{{ site.baseurl }}docs/glossary/#staging">staging server</a> too. +<a href="{{ site.baseurl }}docs/glossary/#production" class="glossary__link">production server</a> +and, if you're running one, your +<a href="{{ site.baseurl }}docs/glossary/#staging" class="glossary__link">staging server</a> too. ## Capistrano -<a href="{{site.baseurl}}docs/glossary/#capistrano" class="glossary">Capistrano</a> +<a href="{{site.baseurl}}docs/glossary/#capistrano" class="glossary__link">Capistrano</a> is included as part of Alaveteli as a standard deployment system. The basic principle of Capistrano is that you execute `cap [do-something]` @@ -68,7 +69,11 @@ and thereafter you'll be able to deploy very easily (see [usage, below](#usage)) First, on the server: * [install Alaveteli]({{ site.baseurl }}docs/installing/) -* then move the Alaveteli app to a temporary place on the server, like your home +* give the Unix user that runs Alaveteli the ability to ssh to your server. Either give them a password or, preferably, set up ssh keys for them so they can ssh from your local machine to the server: + * to give them a password (if they don't already have one) - `sudo passwd [UNIX-USER]`. Store this password securely on your local machine e.g in a password manager + * to set up ssh keys for them, follow the instructions in the [capistrano documentation](http://capistranorb.com/documentation/getting-started/authentication-and-authorisation/). There's no need to set up ssh keys to the git repository as it is public. +* make sure the Unix user that runs Alaveteli has write permissions on the parent directory of your Alaveteli app +* move the Alaveteli app to a temporary place on the server, like your home directory (temporarily, your site will be missing, until the deployment puts new files in place) @@ -82,20 +87,31 @@ Next, on your local machine: need some of the files available locally even though you might not be running Alaveteli on this machine) * copy the example file `config/deploy.yml.example` to `config/deploy.yml` -* now customise the deployment settings in that file: edit `config/deploy.yml` - appropriately -- for example, edit the name of the server. Also, change - `deploy_to` to be the path where Alaveteli is currently installed on the - server -- if you used the installation script, this will be - `/var/www/alaveteli/alaveteli`. +* now customise the deployment settings in that file: edit + `config/deploy.yml` appropriately -- for example, edit the name of the + server. Also, change `deploy_to` to be the path where Alaveteli is + currently installed on the server -- if you used the installation + script , this will be `/var/www/[HOST or alaveteli]/alaveteli`. If + you're running the thin application server rather than passenger, + you'll need to set `rails_app_server` to `thin` and `rails_app_port` + to whatever port it's running on. If you installed with the install + script, this will be port 3300. + + * `cd` into the Alaveteli repo you checked out (otherwise the `cap` commands you're about to execute won't work) * still on your local machine, run `cap -S stage=staging deploy:setup` to setup capistrano on the server -* again on your local machine, run `cap -S stage=staging deploy:update_code` to get a code checkout on the server + +If you get an error `SSH::AuthenticationFailed`, and are not prompted for the password of the deployment user, you may have run into [a bug](http://stackoverflow.com/questions/21560297/capistrano-sshauthenticationfailed-not-prompting-for-password) in the net-ssh gem version 2.8.0. Try installing version 2.7.0 instead: + + gem uninstall net-ssh + + gem install net-ssh -v 2.7.0 Back on the server: * copy the following config files from the temporary copy of Alaveteli you made at - the begining (perhaps in your home directory) to the `shared` directory that + the beginning (perhaps in your home directory) to the `shared` directory that Capistrano just created on the server: * `general.yml` * `database.yml` @@ -110,17 +126,23 @@ Back on the server: `shared` directory created by Capistrano on the server: * `cache/` * `files/` + * `lib/acts_as_xapian/xapiandbs` (copy this to straight into `shared` so it becomes `shared/xapiandbs`) + * `log/` Now, back on your local machine: * make sure you're still in the Alaveteli repo (if not, `cd` back into it) +* run `cap -S stage=staging deploy:update_code` to get a code checkout on the server. * create a deployment directory on the server by running *one* of these commands: - * `cap deploy` if you're deploying a <a href="{{site.baseurl}}docs/glossary/#staging" class="glossary">staging site</a>, or... - * `cap -S stage=production deploy` for <a href="{{site.baseurl}}docs/glossary/#production" class="glossary">production</a> + * `cap deploy` if you're deploying a <a href="{{site.baseurl}}docs/glossary/#staging" class="glossary__link">staging site</a>, or... + * `cap -S stage=production deploy` for <a href="{{site.baseurl}}docs/glossary/#production" class="glossary__link">production</a> + +Back on the server: + * update the webserver config (either apache or nginx) to add the `current` element to the path where it is serving Alaveteli from. If you installed using the installation script, this will be replacing `/var/www/alaveteli/alaveteli/` with - `/var/www/alaveteli/alaveteli/current` in `etc/nginx/sites-available/default`. + `/var/www/alaveteli/alaveteli/current` in `/etc/nginx/sites-available/default`. * edit the server crontab so that the paths in the cron jobs also include the `current` element. If you used the installation script the crontab will be in `etc/cron.d/alaveteli`. @@ -130,7 +152,13 @@ Now, back on your local machine: `argv=/var/www/alaveteli/alaveteli/script/mailin` with `argv=/var/www/alaveteli/alaveteli/current/script/mailin`. If you're using Exim as your MTA, edit `etc/exim4/conf.d/04_alaveteli_options` - to update the `ALAVETELI_HOME` variable to the new Alaveteli path. + to update the `ALAVETELI_HOME` variable to the new Alaveteli path. Restart the MTA after you've made these changes. + +* You will also need to update the path to Alaveteli in your [init scripts]({{site.baseurl}}docs/installing/manual_install/#cron-jobs-and-init-scripts). + You should have a script for running the alert tracks + (`/etc/init.d/foi-alert-tracks`), and possibly scripts for purging the + varnish cache (`/etc/init.d/foi-purge-varnish`), and restarting the + app server (`/etc/init.d/alaveteli`). Phew, you're done! diff --git a/docs/installing/index.md b/docs/installing/index.md index c276c3d08..c04aaa3ca 100644 --- a/docs/installing/index.md +++ b/docs/installing/index.md @@ -6,17 +6,19 @@ title: Installing # Installing Alaveteli <p class="lead"> - Although you can install Alaveteli and just change it when you need it, we - recommend you adopt a way of <strong>deploying</strong> it automatically. - This has several advantages, especially for your - <a href="{{ site.baseurl }}docs/glossary/#production">production server</a>. + There are a number of ways to install Alaveteli. + We've made an Amazon Machine Image (AMI) so you can quickly deploy on + Amazon EC2 (handy if you just want to evaluate it, for example). + If you prefer to use your own server, there's an installation script + which does most of the work for you, or you can follow the manual + installation instructions. </p> ## Before you start This is important: you need to decide if you are installing Alaveteli for -[development]({{ site.baseurl }}docs/glossary/#development) or -[production]({{ site.baseurl }}docs/glossary/#production). +<a href="{{ site.baseurl }}docs/glossary/#development" class="glossary__link">development</a> or +<a href="{{ site.baseurl }}docs/glossary/#production" class="glossary__link">production</a>. A **development** site is one where you're going to change, customise, and perhaps experiment while you get it up and running. You should always do this @@ -30,9 +32,10 @@ messages switched off. It's important to be able to deploy changes to a production site quickly and efficiently, so we recommend you consider using a [deployment mechanism]({{ site.baseurl }}docs/installing/deploy/) too. -Ideally, you should also have a [staging site]({{ site.baseurl }}docs/glossary/#staging), +Ideally, you should also have a +<a href="{{ site.baseurl }}docs/glossary/#staging" class="glossary__link">staging site</a>, which is used solely to test new code in an identical environment to your -production site but before it goes live. +production site before it goes live. If you're in doubt, you're probably running a development site. Get it up and running, play with it, customise it, and -- later -- you can install it as a @@ -47,6 +50,7 @@ those servers, because Capistrano takes care of that for you. ## Installing the core code +* [Install into a Vagrant virtual development environment]({{ site.baseurl }}docs/installing/vagrant/) -- a good choice for development, and playing around with the site. * [Install on Amazon EC2]({{ site.baseurl }}docs/installing/ami/) using our AMI * [Use the installation script]({{ site.baseurl }}docs/installing/script/) which does the full installation on your own server * [Manual installation]({{ site.baseurl }}docs/installing/manual_install/) -- step-by-step instructions @@ -56,7 +60,7 @@ If you're setting up a development server on MacOS X, we've also got ## Other installation information -Alaveteli needs to be able to send and receive email, so you need to setup your -MTA (Mail Transfer Agent) appropriately. +Alaveteli needs to be able to send and receive email. If you're installing manually, you need to [setup your +MTA (Mail Transfer Agent) appropriately]({{ site.baseurl }}docs/installing/email/). The other install methods will do this for you. * [Installing the MTA]({{ site.baseurl }}docs/installing/email/) diff --git a/docs/installing/manual_install.md b/docs/installing/manual_install.md index 841617477..7eac53ae3 100644 --- a/docs/installing/manual_install.md +++ b/docs/installing/manual_install.md @@ -19,15 +19,15 @@ Note that there are [other ways to install Alaveteli]({{ site.baseurl }}docs/ins ## Target operating system -These instructions assume Debian Squeeze (64-bit) or Ubuntu 12.04 LTS -(precise). Debian Squeeze is the best supported deployment platform. We also +These instructions assume a 64-bit version of Debian 6 (Wheezy), Debian 7 (Squeeze) +or Ubuntu 12.04 LTS (Precise). Debian is the best supported deployment platform. We also have instructions for [installing on MacOS]({{ site.baseurl }}docs/installing/macos/). Commands are intended to be run via the terminal or over ssh. ## Set the locale -**Debian Squeeze** +**Debian Wheezy or Squeeze** Follow the [Debian guide](https://wiki.debian.org/Locale#Standard) for configuring the locale of the operating system. @@ -60,59 +60,118 @@ submodules, run: git submodule update --init -## Install system dependencies +## Prepare to install system dependencies using OS packages These are packages that the software depends on: third-party software used to parse documents, host the site, and so on. There are also packages that contain headers necessary to compile some of the gem dependencies in the next step. +<div class="attention-box"> +Note the commands in this section will require root privileges +</div> + +### Using other repositories to get more recent packages + Add the following repositories to `/etc/apt/sources.list`: **Debian Squeeze** - cat > /etc/apt/sources.list.d/debian-backports.list <<EOF + cat > /etc/apt/sources.list.d/debian-extra.list <<EOF deb http://backports.debian.org/debian-backports squeeze-backports main contrib non-free + deb http://the.earth.li/debian/ wheezy main contrib non-free EOF -The repositories above let you install `wkhtmltopdf-static` and `bundler` using -`apt`. +The squeeze-backports repository is providing a more recent version of rubygems, and the wheezy repository is providing bundler. You should configure package-pinning to reduce the priority of the wheezy repository so other packages aren't pulled from it. + + cat >> /etc/apt/preferences <<EOF + + Package: bundler + Pin: release n=wheezy + Pin-Priority: 990 + + Package: * + Pin: release n=wheezy + Pin-Priority: 50 + EOF + +**Debian Wheezy** + + cat > /etc/apt/sources.list.d/debian-extra.list <<EOF + # Debian mirror to use, including contrib and non-free: + deb http://the.earth.li/debian/ wheezy main contrib non-free + deb-src http://the.earth.li/debian/ wheezy main contrib non-free + + # Security Updates: + deb http://security.debian.org/ wheezy/updates main non-free + deb-src http://security.debian.org/ wheezy/updates main non-free + EOF **Ubuntu Precise** cat > /etc/apt/sources.list.d/ubuntu-extra.list <<EOF - deb http://eu-west-1.ec2.archive.ubuntu.com/ubuntu/ precise multiverse - deb-src http://eu-west-1.ec2.archive.ubuntu.com/ubuntu/ precise multiverse - deb http://eu-west-1.ec2.archive.ubuntu.com/ubuntu/ precise-updates multiverse - deb-src http://eu-west-1.ec2.archive.ubuntu.com/ubuntu/ precise-updates multiverse + deb http://de.archive.ubuntu.com/ubuntu/ precise multiverse + deb-src http://de.archive.ubuntu.com/ubuntu/ precise multiverse + deb http://de.archive.ubuntu.com/ubuntu/ precise-updates multiverse + deb-src http://de.archive.ubuntu.com/ubuntu/ precise-updates multiverse + deb http://de.archive.ubuntu.com/ubuntu/ raring universe + deb-src http://de.archive.ubuntu.com/ubuntu/ raring universe + EOF + +The raring repo is used here to get a more recent version of bundler and pdftk. You should configure package-pinning to reduce the priority of the raring repository so other packages aren't pulled from it. + + cat >> /etc/apt/preferences <<EOF + + Package: ruby-bundler + Pin: release n=raring + Pin-Priority: 990 + + Package: pdftk + Pin: release n=raring + Pin-Priority: 990 + + Package: * + Pin: release n=raring + Pin-Priority: 50 EOF -The repositories above let you install `wkhtmltopdf-static` using `apt`. -`bundler` will have to be installed manually on Ubuntu Precise. ### Packages customised by mySociety -If you're using Debian, you should add the mySociety Debian archive to your +If you're using Debian or Ubuntu, you should add the mySociety Debian archive to your apt sources. Note that mySociety packages are currently only built for 64-bit Debian. +**Debian Squeeze, Wheezy or Ubuntu Precise** + cat > /etc/apt/sources.list.d/mysociety-debian.list <<EOF deb http://debian.mysociety.org squeeze main EOF +The repository above lets you install `wkhtmltopdf-static` and `pdftk` (for squeeze) using `apt`. + Add the GPG key from the [mySociety Debian Package Repository](http://debian.mysociety.org/). wget -O - https://debian.mysociety.org/debian.mysociety.org.gpg.key | sudo apt-key add - + +**Debian Wheezy or Ubuntu Precise** + You should also configure package-pinning to reduce the priority of this -repository. +repository - we only want to pull wkhtmltopdf-static from mysociety. + + cat >> /etc/apt/preferences <<EOF - cat > /etc/apt/preferences <<EOF Package: * Pin: origin debian.mysociety.org Pin-Priority: 50 EOF -If you're using some other platform, you can optionally install these +**Debian Squeeze** + +No special package pinning is required. + +### Other platforms +If you're using some other linux platform, you can optionally install these dependencies manually, as follows: 1. If you would like users to be able to get pretty PDFs as part of the @@ -126,13 +185,15 @@ everything will still work, but users will get ugly, plain text versions of their requests when they download them. 2. Version 1.44 of `pdftk` contains a bug which makes it loop forever in -certain edge conditions. Until it's incorporated into an official release, you +certain edge conditions. This is fixed in the standard 1.44.7 package which is available in wheezy (Debian) and raring (Ubuntu). + +If you can't get an official release for your OS with the fix, you can either hope you don't encounter the bug (it ties up a rails process until you kill it), patch it yourself, or use the Debian package compiled by mySociety (see link in [issue 305](https://github.com/mysociety/alaveteli/issues/305)) -### Install the dependencies +## Install the dependencies Refresh the sources after adding the extra repositories: @@ -140,6 +201,9 @@ Refresh the sources after adding the extra repositories: Now install the packages relevant to your system: + # Debian Wheezy + sudo apt-get install $(cat config/packages.debian-wheezy) + # Debian Squeeze sudo apt-get install $(cat config/packages.debian-squeeze) @@ -153,7 +217,7 @@ choice of packages. ## Install Ruby dependencies To install Alaveteli's Ruby dependencies, you need to install bundler. In -Debian, this is provided as a package (installed as part of the package install +Debian and Ubuntu, this is provided as a package (installed as part of the package install process above). You could also install it as a gem: sudo gem install bundler @@ -341,56 +405,90 @@ site in action. ## Cron jobs and init scripts -`config/crontab-example` contains the cronjobs run on WhatDoTheyKnow. It's in a -strange templating format they use in mySociety. mySociety render the example -file to reference absolute paths, and then drop it in `/etc/cron.d/` on the -server. +The crontab and init scripts use the `.ugly` file format, which is a strange +templating format used by mySociety. The `ugly` format uses simple variable substitution. A variable looks like -`!!(*= $this *)!!`. The variables are: - -* `vhost`: part of the path to the directory where the software is - served from. In the mySociety files, it usually comes as - `/data/vhost/!!(*= $vhost *)!!` -- you should replace that whole - port with a path to the directory where your Alaveteli software - installation lives, e.g. `/var/www/` -* `vhost_dir`: the entire path to the directory where the software is - served from. -- you should replace this with a path to the - directory where your Alaveteli software installation lives, - e.g. `/var/www/` -* `vcspath`: the name of the alaveteli checkout, e.g. `alaveteli`. - Thus, `/data/vhost/!!(*= $vhost *)!!/!!(*= $vcspath *)!!` might be - replaced with `/var/www/alaveteli` in your cron tab +`!!(*= $this *)!!`. + +### Generate crontab + +`config/crontab-example` contains the cron jobs that run on +WhatDoTheyKnow. mySociety render the example file to reference absolute paths, +and then drop it in `/etc/cron.d/` on the server. + +**Template Variables:** + +* `vhost_dir`: the full path to the directory where alaveteli is checked out. + e.g. If your checkout is at `/var/www/alaveteli` then set this to `/var/www` +* `vcspath`: the name of the directory that contains the alaveteli code. + e.g. `alaveteli` * `user`: the user that the software runs as * `site`: a string to identify your alaveteli instance +* `mailto`: The email address that cron output will be sent to There is a rake task that will help to rewrite this file into one that is -useful to you, which can be invoked with: +useful to you. Change the variables to suit your installation. bundle exec rake config_files:convert_crontab \ DEPLOY_USER=deploy \ - VHOST_DIR=/dir/above/alaveteli \ - VCSPATH=alaveteli \ - SITE=alaveteli \ - CRONTAB=config/crontab-example > crontab + VHOST_DIR=/var/www \ + VCSPATH=alaveteli \ + SITE=alaveteli \ + MAILTO=cron-alaveteli@example.org \ + CRONTAB=config/crontab-example > /etc/cron.d/alaveteli -You should change the `DEPLOY_USER`, `VHOST_DIR`, `VCSPATH` and `SITE` -environment variables to match your server and installation. You should also -edit the resulting `crontab` file to customize the `MAILTO` variable. +### Generate alert daemon One of the cron jobs refers to a script at `/etc/init.d/foi-alert-tracks`. This -is an init script, a copy of which lives in `config/alert-tracks-debian.ugly`. -As with the cron jobs above, replace the variables (and/or bits near the -variables) with paths to your software. You can use the rake task `rake -config_files:convert_init_script` to do this. +is an init script, which can be generated from the +`config/alert-tracks-debian.ugly` template. + +**Template Variables:** + +* `vhost_dir`: the full path to the directory where alaveteli is checked out. + e.g. If your checkout is at `/var/www/alaveteli` then set this to `/var/www` +* `user`: the user that the software runs as + +There is a rake task that will help to rewrite this file into one that is +useful to you. Change the variables to suit your installation. + + bundle exec rake config_files:convert_init_script \ + DEPLOY_USER=deploy \ + VHOST_DIR=/var/www \ + SCRIPT_FILE=config/alert-tracks-debian.ugly > /etc/init.d/foi-alert-tracks + +### Generate varnish purge daemon `config/purge-varnish-debian.ugly` is a similar init script, which is optional and not required if you choose not to run your site behind Varnish (see below). + +**Template Variables:** + +* `daemon_name`: The name of the daemon. Set this to `purge-varnish`. +* `vhost_dir`: the full path to the directory where alaveteli is checked out. + e.g. If your checkout is at `/var/www/alaveteli` then set this to `/var/www` +* `user`: the user that the software runs as + +This template does not yet have a rake task to generate it. + +### Init script permissions + Either tweak the file permissions to make the scripts executable by your deploy user, or add the following line to your sudoers file to allow these to be run -by your deploy user (named `deploy` in this case): +by your deploy user (named `deploy` in this case). - deploy ALL = NOPASSWD: /etc/init.d/foi-alert-tracks, /etc/init.d/foi-purge-varnish + deploy ALL = NOPASSWD: /etc/init.d/foi-alert-tracks, /etc/init.d/foi-purge-varnish + +There is also an example config for stopping and starting the +Alaveteli app server as a service in `config/sysvinit.example`. This +example assumes you're using Thin as an application server, so will +need tweaking for Passenger or any other app server. You can install +this by copying it to `/etc/init.d/alaveteli` and setting the +`SITE_HOME` variable to the path where Alaveteli is running, and the +`USER` variable to the Unix user that will be running Alaveteli. Once +that's done, you can restart Alaveteli with `/etc/init.d/alaveteli +restart`. ## Set up production web server @@ -443,6 +541,10 @@ and so it knows to include that in any absolute urls it serves. We have some [production server best practice notes]({{ site.baseurl}}docs/running/server/). +## What next? + +Check out the [next steps]({{ site.baseurl }}docs/installing/next_steps/). + ## Troubleshooting * **Incoming emails aren't appearing in my Alaveteli install** diff --git a/docs/installing/next_steps.md b/docs/installing/next_steps.md new file mode 100644 index 000000000..98a661416 --- /dev/null +++ b/docs/installing/next_steps.md @@ -0,0 +1,34 @@ +--- +layout: page +title: Next Steps +--- +# Next Steps + +<p class="lead"> + OK, you've installed a copy of Alaveteli, and can see the site in a browser. What next? +</p> + + +### Create a superuser account for yourself + +* Sign up for a new account on the site. You should receive a confirmation email. Click on the link in it to confirm the account. + +* Get access to the [admin interface]({{ site.baseurl}}docs/running/admin_manual/#administrator-privileges). You can find the +`general.yml` file you'll need to get the `ADMIN_USERNAME` and +`ADMIN_PASSWORD` credentials in the `config` subdirectory of the +directory Alaveteli was installed into. + +* In the admin interface, go to the 'Users' section and find the account you just created. Promote the account you just created to superuser status by clicking the 'Edit' button and setting the 'Admin level' value to 'super'. + +### Test out the request process + +* Create a new public authority in the admin interface - give it a name something like 'Test authority'. Set the request email to an address that you will receive. + +* From the main interface of the site, make a request to the new authority. + +* You should receive the request email - try replying to it. Your response email should appear in Alaveteli. Not working? Take a look at our [troubleshooting tips]({{ site.baseurl}}docs/installing/manual_install/#troubleshooting). If that doesn't sort it out, [get in touch]({{ site.baseurl}}community/) on the project mailing list or IRC +for help. + +### Start thinking about customising Alaveteli + +Check out [our guide]({{ site.baseurl}}docs/customising/). diff --git a/docs/installing/script.md b/docs/installing/script.md index b8b678a0a..72fbd6438 100644 --- a/docs/installing/script.md +++ b/docs/installing/script.md @@ -1,6 +1,6 @@ --- layout: page -title: Installing the easy way +title: Installation script --- # Installation script @@ -16,7 +16,7 @@ Note that there are [other ways to install Alaveteli]({{ site.baseurl }}docs/ins If you have a clean installation of Debian squeeze 64-bit or Ubuntu precise, you can use an install script in our commonlib repository to set up a working instance of Alaveteli. This is not suitable for production (it runs in development mode, -for example) but should set up a functional installation of the site. +for example) but should set up a functional installation of the site, which can send and receive email. **Warning: only use this script on a newly installed server – it will make significant changes to your server’s setup, including modifying your nginx @@ -25,7 +25,7 @@ etc.** To download the script, run the following command: - curl -O https://raw.github.com/mysociety/commonlib/master/bin/install-site.sh + curl -O https://raw.githubusercontent.com/mysociety/commonlib/master/bin/install-site.sh If you run this script with `sh install-site.sh`, you'll see its usage message: @@ -56,10 +56,20 @@ could download the script, make it executable and then invoke it with: sudo ./install-site.sh --default alaveteli alaveteli +If you have any problems or questions, please ask on the [Alaveteli Google + Group](https://groups.google.com/forum/#!forum/alaveteli-dev) or [report an + issue](https://github.com/mysociety/alaveteli/issues?state=open). + +## What the install script does + When the script has finished, you should have a working copy of the website, -accessible via the hostname you supplied to the script. +accessible via the hostname you supplied to the script. So, for this example, you could access the site in a browser at `http://alaveteli.10.10.10.30.xip.io`. The site runs using the thin application server, and the nginx webserver. By default, Alaveteli will be installed into `/var/www/[HOST]` on the server. + +The server will also be configured to accept replies to information request emails (as long as the MX record for the domain is pointing at the server). Incoming mail handling is set up using Postfix as the MTA. + +##What next? + +Check out the [next steps]({{ site.baseurl }}docs/installing/next_steps/). + -If you have any problems or questions, please ask on the [Alaveteli Google -Group](https://groups.google.com/forum/#!forum/alaveteli-dev) or [report an -issue](https://github.com/mysociety/alaveteli/issues?state=open). diff --git a/docs/installing/vagrant.md b/docs/installing/vagrant.md new file mode 100644 index 000000000..8938d496b --- /dev/null +++ b/docs/installing/vagrant.md @@ -0,0 +1,70 @@ +--- +layout: page +title: Vagrant +--- +# Alaveteli using Vagrant + +<p class="lead"> +Vagrant provides an easy method to set up virtual development environments; for +further information see <a href="http://www.vagrantup.com">the Vagrant website</a>. +We bundle an example Vagrantfile in the repository, which runs the +<a href="{{ site.baseurl }}docs/installing/script/">install script</a> for you. +</p> + +Note that this is just one of [several ways to install Alaveteli]({{ site.baseurl }}docs/installing/). + +The included steps will use vagrant to create a development environment +where you can run the test suite, the development server and make +changes to the codebase. + +The basic process is to create a base virtual machine, and then +provision it with the software packages and setup needed. The supplied +scripts will create you a Vagrant VM based on the server edition of +Ubuntu 12.04 LTS that contains everything you need to work on Alaveteli. + +1. Get a copy of Alaveteli from GitHub and create the Vagrant instance. + This will provision the system and can take some time - usually at + least 20 minutes. + + # on your machine + $ git clone git@github.com:mysociety/alaveteli.git + $ cd alaveteli + $ git submodule update --init + $ vagrant --no-color up + +2. You should now be able to ssh in to the Vagrant guest OS and run the + test suite: + + $ vagrant ssh + + # You are now in a terminal on the virtual machine + $ cd /home/vagrant/alaveteli + $ bundle exec rake spec + + +3. Run the rails server and visit the application in your host browser + at http://10.10.10.30:3000 + + # in the virtual machine terminal + bundle exec rails server + +## What next? + +Check out the [next steps]({{ site.baseurl }}docs/installing/next_steps/). + +## Customizing the Vagrant instance + +The Vagrantfile allows customisation of some aspects of the virtual machine. See the customization options in the file [`Vagrantfile`](https://github.com/mysociety/alaveteli/blob/master/Vagrantfile#L30) at the top level of the Alaveteli repository. + +The options can be set either by prefixing the vagrant command, or by +exporting to the environment. + + # Prefixing the command + $ ALAVETELI_VAGRANT_MEMORY=2048 vagrant up + + # Exporting to the environment + $ export ALAVETELI_VAGRANT_MEMORY=2048 + $ vagrant up + +Both have the same effect, but exporting will retain the variable for the duration of your shell session. + diff --git a/docs/running/admin_manual.md b/docs/running/admin_manual.md index cde828c9a..567e6cf5e 100644 --- a/docs/running/admin_manual.md +++ b/docs/running/admin_manual.md @@ -6,7 +6,11 @@ title: Administrator's guide # Alaveteli administrator's guide <p class="lead"> - What is it like running an Alaveteli site? This guide explains what you can expect, and the types of problem that you might encounter. It includes examples of how mySociety manages their own <a href="/docs/glossary/#foi" class="glossary">Freedom of Information</a> site, <a href="https://www.whatdotheyknow.com">whatdotheyknow.com</a>. + What is it like running an Alaveteli site? This guide explains what you can + expect, and the types of problem that you might encounter. It includes + examples of how mySociety manages their own <a href="/docs/glossary/#foi" + class="glossary__link">Freedom of Information</a> site, <a + href="https://www.whatdotheyknow.com">whatdotheyknow.com</a>. </p> ## What's involved? diff --git a/docs/running/index.md b/docs/running/index.md index 90461fb3e..d6225ac61 100644 --- a/docs/running/index.md +++ b/docs/running/index.md @@ -11,7 +11,7 @@ title: Running </p> Alaveteli is not just software. To run a successful -<a href="{{ site.baseurl }}docs/glossary/#foi" class="glossary">Freedom of Information</a> +<a href="{{ site.baseurl }}docs/glossary/#foi" class="glossary__link">Freedom of Information</a> site, you need to make sure day-to-day tasks get done too. Most Alaveteli sites are run by a team who allocate some time every day to user support and generally keeping the project up to date. diff --git a/docs/running/states.md b/docs/running/states.md index 1c3fb217e..40e8a1a5b 100644 --- a/docs/running/states.md +++ b/docs/running/states.md @@ -6,14 +6,14 @@ title: States of requests # Request states <p class="lead"> - A <a href="{{site.baseurl}}docs/glossary/#request" class="glossary">request</a> + A <a href="{{site.baseurl}}docs/glossary/#request" class="glossary__link">request</a> passes through different <strong>states</strong> as it is processed. These may vary from one jurisdiction to another. </p> The request states are defined in the Alaveteli code, and we recommend you use them (provided they match the <a href="{{ site.baseurl }}docs/glossary/#foi" -class="glossary">FOI law</a> in your own jurisdiction). But if you do need to +class="glossary__link">FOI law</a> in your own jurisdiction). But if you do need to customise them, you can — see <a href="{{ site.baseurl }}docs/customising/themes/">Customising the request states</a> for details. diff --git a/docs/running/states_informatazyrtare.md b/docs/running/states_informatazyrtare.md index bd5ff1a1c..28711643b 100644 --- a/docs/running/states_informatazyrtare.md +++ b/docs/running/states_informatazyrtare.md @@ -14,7 +14,7 @@ title: States of requests (InformataZyrtare) The request states are defined in the Alaveteli code, and we recommend you use them (provided they match the <a href="{{ site.baseurl }}docs/glossary/#foi" -class="glossary">FOI law</a> in your own jurisdiction). +class="glossary__link">FOI law</a> in your own jurisdiction). ## InformataZyrtare.org (Kosovo) example diff --git a/docs/running/upgrading.md b/docs/running/upgrading.md index 2142bfd47..ab8db2385 100644 --- a/docs/running/upgrading.md +++ b/docs/running/upgrading.md @@ -17,7 +17,7 @@ Upgrading Alaveteli The developer team policy is that the `master` branch in git should always contain the latest stable release -- so you'll be up to date if you pull from the `master` branch. However, on your -<a href="{{site.baseurl}}docs/glossary/#production" class="glossary">production +<a href="{{site.baseurl}}docs/glossary/#production" class="glossary__link">production site</a>, you should know precisely what version you're running, and deploy Alaveteli from a [*specific* release tag](https://github.com/mysociety/alaveteli/releases). |