diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/customising/config.md | 1172 | ||||
| -rw-r--r-- | docs/customising/index.md | 44 | ||||
| -rw-r--r-- | docs/customising/themes.md | 191 | ||||
| -rw-r--r-- | docs/customising/translation.md | 123 | ||||
| -rw-r--r-- | docs/developers/api.md | 82 | ||||
| -rw-r--r-- | docs/developers/directory_structure.md | 257 | ||||
| -rw-r--r-- | docs/developers/index.md | 84 | ||||
| -rw-r--r-- | docs/developers/overview.md | 51 | ||||
| -rw-r--r-- | docs/getting_started.md | 380 | ||||
| -rw-r--r-- | docs/glossary.md | 590 | ||||
| -rw-r--r-- | docs/installing/ami.md | 59 | ||||
| -rw-r--r-- | docs/installing/deploy.md | 167 | ||||
| -rw-r--r-- | docs/installing/email.md | 213 | ||||
| -rw-r--r-- | docs/installing/index.md | 62 | ||||
| -rw-r--r-- | docs/installing/macos.md | 155 | ||||
| -rw-r--r-- | docs/installing/manual_install.md | 570 | ||||
| -rw-r--r-- | docs/installing/script.md | 65 | ||||
| -rw-r--r-- | docs/running/admin_manual.md | 301 | ||||
| -rw-r--r-- | docs/running/index.md | 28 | ||||
| -rw-r--r-- | docs/running/server.md | 122 | ||||
| -rw-r--r-- | docs/running/states.md | 217 | ||||
| -rw-r--r-- | docs/running/states_informatazyrtare.md | 88 |
22 files changed, 5021 insertions, 0 deletions
diff --git a/docs/customising/config.md b/docs/customising/config.md new file mode 100644 index 000000000..2528adefc --- /dev/null +++ b/docs/customising/config.md @@ -0,0 +1,1172 @@ +--- +layout: page +title: Configuration +--- + +# Configuring Alaveteli + +<p class="lead"> + You can control much of how Alaveteli looks and behaves just by + changing the config settings. +</p> + +## The general configuration file + +The alaveteli code ships with an example configuration file: `config/general.yml-example`. + +As part of the [installation process]({{ site.baseurl }}docs/installing ), the +example file gets copied to `config/general.yml`. You **must** edit this file to +suit your needs. + +Note that the default settings for frontpage examples are designed to work with +the dummy data shipped with Alaveteli. Once you have real data, you should +certainly edit these. + +Note that there are [other configuration files](#other-config) too, for specific aspects of Alaveteli. + + +## Config settings by topic + +The following are all the configuration settings that you can change in `config/general.yml`. +When you edit this file, remember it must be in the <a href="http://yaml.org">YAML syntax</a>. +It's not complicated but — especially if you're editing a list — be careful to get the +indentation correct. If in doubt, look at the examples already in the file, and don't use tabs. + + +### Appearance and overall behaviour of the site: + +<code><a href="#site_name">SITE_NAME</a></code> +<br> <code><a href="#domain">DOMAIN</a></code> +<br> <code><a href="#force_ssl">FORCE_SSL</a></code> +<br> <code><a href="#force_registration_on_new_request">FORCE_REGISTRATION_ON_NEW_REQUEST</a></code> +<br> <code><a href="#theme_urls">THEME_URLS</a></code> +<br> <code><a href="#theme_branch">THEME_BRANCH</a></code> +<br> <code><a href="#frontpage_publicbody_examples">FRONTPAGE_PUBLICBODY_EXAMPLES</a></code> +<br> <code><a href="#public_body_statistics_page">PUBLIC_BODY_STATISTICS_PAGE</a></code> +<br> <code><a href="#minimum_requests_for_statistics">MINIMUM_REQUESTS_FOR_STATISTICS</a></code> +<br> <code><a href="#responsive_styling">RESPONSIVE_STYLING</a></code> + +### Site status: + +<code><a href="#read_only">READ_ONLY</a></code> +<br> <code><a href="#staging_site">STAGING_SITE</a></code> + +### Locale and internationalisation: + +<code><a href="#iso_country_code">ISO_COUNTRY_CODE</a></code> +<br> <code><a href="#time_zone">TIME_ZONE</a></code> +<br> <code><a href="#available_locales">AVAILABLE_LOCALES</a></code> +<br> <code><a href="#default_locale">DEFAULT_LOCALE</a></code> +<br> <code><a href="#use_default_browser_language">USE_DEFAULT_BROWSER_LANGUAGE</a></code> +<br> <code><a href="#include_default_locale_in_urls">INCLUDE_DEFAULT_LOCALE_IN_URLS</a></code> + +### Definition of "late": + +<code><a href="#reply_late_after_days">REPLY_LATE_AFTER_DAYS</a></code> +<br> <code><a href="#reply_very_late_after_days">REPLY_VERY_LATE_AFTER_DAYS</a></code> +<br> <code><a href="#special_reply_very_late_after_days">SPECIAL_REPLY_VERY_LATE_AFTER_DAYS</a></code> +<br> <code><a href="#working_or_calendar_days">WORKING_OR_CALENDAR_DAYS</a></code> + +### Admin access: + +<code><a href="#admin_username">ADMIN_USERNAME</a></code> +<br> <code><a href="#admin_password">ADMIN_PASSWORD</a></code> +<br> <code><a href="#admin_username">DISABLE_EMERGENCY_USER</a></code> +<br> <code><a href="#skip_admin_auth">SKIP_ADMIN_AUTH</a></code> + +### Email management: + +<code><a href="#incoming_email_domain">INCOMING_EMAIL_DOMAIN</a></code> +<br> <code><a href="#incoming_email_prefix">INCOMING_EMAIL_PREFIX</a></code> +<br> <code><a href="#incoming_email_secret">INCOMING_EMAIL_SECRET</a></code> +<br> <code><a href="#blackhole_prefix">BLACKHOLE_PREFIX</a></code> +<br> <code><a href="#contact_email">CONTACT_EMAIL</a></code> +<br> <code><a href="#contact_name">CONTACT_NAME</a></code> +<br> <code><a href="#track_sender_email">TRACK_SENDER_EMAIL</a></code> +<br> <code><a href="#track_sender_name">TRACK_SENDER_NAME</a></code> +<br> <code><a href="#raw_emails_location">RAW_EMAILS_LOCATION</a></code> +<br> <code><a href="#exception_notifications_from">EXCEPTION_NOTIFICATIONS_FROM</a></code> +<br> <code><a href="#exception_notifications_to">EXCEPTION_NOTIFICATIONS_TO</a></code> +<br> <code><a href="#forward_nonbounce_responses_to">FORWARD_NONBOUNCE_RESPONSES_TO</a></code> +<br> <code><a href="#mta_log_path">MTA_LOG_PATH</a></code> +<br> <code><a href="#mta_log_type">MTA_LOG_TYPE</a></code> + +### General admin (keys, paths, back-end services): + +<code><a href="#cookie_store_session_secret">COOKIE_STORE_SESSION_SECRET</a></code> +<br> <code><a href="#recaptcha_public_key">RECAPTCHA_PUBLIC_KEY</a></code> +<br> <code><a href="#recaptcha_private_key">RECAPTCHA_PRIVATE_KEY</a></code> +<br> <code><a href="#gaze_url">GAZE_URL</a></code> +<br> <code><a href="#ga_code">GA_CODE</a></code> (GA=Google Analytics) +<br> <code><a href="#utility_search_path">UTILITY_SEARCH_PATH</a></code> +<br> <code><a href="#shared_files_path">SHARED_FILES_PATH</a></code> +<br> <code><a href="#shared_files">SHARED_FILES</a></code> +<br> <code><a href="#shared_directories">SHARED_DIRECTORIES</a></code> + +### Behaviour settings and switches: + +<code><a href="#new_response_reminder_after_days">NEW_RESPONSE_REMINDER_AFTER_DAYS</a></code> +<br> <code><a href="#max_requests_per_user_per_day">MAX_REQUESTS_PER_USER_PER_DAY</a></code> +<br> <code><a href="#override_all_public_body_request_emails">OVERRIDE_ALL_PUBLIC_BODY_REQUEST_EMAILS</a></code> +<br> <code><a href="#allow_batch_requests">ALLOW_BATCH_REQUESTS</a></code> +<br> <code><a href="#public_body_list_fallback_to_default_locale">PUBLIC_BODY_LIST_FALLBACK_TO_DEFAULT_LOCALE</a></code> +<br> <code><a href="#cache_fragments">CACHE_FRAGMENTS</a></code> + +### External public services: + +<code><a href="#blog_feed">BLOG_FEED</a></code> +<br> <code><a href="#twitter_username">TWITTER_USERNAME</a></code> +<br> <code><a href="#twitter_widget_id">TWITTER_WIDGET_ID</a></code> +<br> <code><a href="#donation_url">DONATION_URL</a></code> + +### Development work or special cases: + +<code><a href="#debug_record_memory">DEBUG_RECORD_MEMORY</a></code> +<br> <code><a href="#varnish_host">VARNISH_HOST</a></code> +<br> <code><a href="#use_mailcatcher_in_development">USE_MAILCATCHER_IN_DEVELOPMENT</a></code> +<br> <code><a href="#use_ghostscript_compression">USE_GHOSTSCRIPT_COMPRESSION</a></code> +<br> <code><a href="#html_to_pdf_command">HTML_TO_PDF_COMMAND</a></code> + + +--- + +## All the general settings + + +<dl class="glossary"> + + <dt> + <a name="site_name"><code>SITE_NAME</code></a> + </dt> + <dd> + <strong>SITE_NAME</strong> appears in various places throughout the site. + <div class="more-info"> + <p>Examples:</p> + <ul class="examples"> + <li> + <code>SITE_NAME: 'Alaveteli'</code> + </li> + <li> + <code>SITE_NAME: 'WhatDoTheyKnow'</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="domain"><code>DOMAIN</code></a> + </dt> + <dd> + Domain used in URLs generated by scripts (e.g. for going in some emails) + <div class="more-info"> + <p>Examples:</p> + <ul class="examples"> + <li> + <code>DOMAIN: '127.0.0.1:3000'</code> + </li> + <li> + <code>DOMAIN: 'www.example.com'</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="force_ssl"><code>FORCE_SSL</code></a> + </dt> + <dd> + If true forces everyone (in the production environment) to use encrypted connections + (via https) by redirecting unencrypted connections. This is <strong>highly + recommended</strong> so that logins can't be intercepted by naughty people. + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>FORCE_SSL: true</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="iso_country_code"><code>ISO_COUNTRY_CODE</code></a> + </dt> + <dd> + The <a href="http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2">ISO country code</a> + of the country in which your Alaveteli site is deployed. + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>ISO_COUNTRY_CODE: GB</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="time_zone"><code>TIME_ZONE</code></a> + </dt> + <dd> + This is the <a href="http://en.wikipedia.org/wiki/List_of_tz_database_time_zones">timezone</a> + that Alaveteli usese to display times and dates. + If not set, defaults to UTC. + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>TIME_ZONE: Australia/Sydney</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="blog_feed"><code>BLOG_FEED</code></a> + </dt> + <dd> + These feeds are displayed accordingly on the Alaveteli "blog" page: <!-- TODO --> + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>BLOG_FEED: 'http://www.mysociety.org/category/projects/whatdotheyknow/feed/'</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="twitter_username"><code>TWITTER_USERNAME</code></a> + <a name="twitter_widget_id"><code>TWITTER_WIDGET_ID</code></a> + </dt> + <dd> + If you want a twitter feed displayed on the "blog" page, provide the widget ID and username. + <div class="more-info"> + <p>Examples:</p> + <ul class="examples"> + <li> + <code>TWITTER_USERNAME: WhatDoTheyKnow</code> + </li> + <li> + <code>TWITTER_WIDGET_ID: '833549204689320031'</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="available_locales"><code>AVAILABLE_LOCALES</code></a> & + <a name="default_locale"><code>DEFAULT_LOCALE</code></a> + </dt> + <dd> + <strong>AVAILABLE_LOCALES</strong> lists all the locales you want your site to support. + If there is more than one, use spaces betwween the entries. + Nominate one of these locales as the default with <strong>DEFAULT_LOCALE</strong>. + <div class="more-info"> + <p>Examples:</p> + <ul class="examples"> + <li> + <code>AVAILABLE_LOCALES: 'en es'</code> + </li> + <li> + <code>DEFAULT_LOCALE: 'en'</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="use_default_browser_language"><code>USE_DEFAULT_BROWSER_LANGUAGE</code></a> + </dt> + <dd> + Should Alaveteli try to use the default language of the user's browser? + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>USE_DEFAULT_BROWSER_LANGUAGE: true</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="include_default_locale_in_urls"><code>INCLUDE_DEFAULT_LOCALE_IN_URLS</code></a> + </dt> + <dd> + Normally, Alaveteli will put the locale into its URLs, like this + <code>www.example.com/en/body/list/all</code>. If you don't want this + behaviour whenever the locale is the default one, set + <strong>INCLUDE_DEFAULT_LOCALE_IN_URLS</strong> to false. + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>INCLUDE_DEFAULT_LOCALE_IN_URLS: true</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="reply_late_after_days"><code>REPLY_LATE_AFTER_DAYS</code></a><br> + <a name="reply_very_late_after_days"><code>REPLY_VERY_LATE_AFTER_DAYS</code></a><br> + <a name="special_reply_very_late_after_days"><code>SPECIAL_REPLY_VERY_LATE_AFTER_DAYS</code></a> + <a name="working_or_calendar_days"><code>WORKING_OR_CALENDAR_DAYS</code></a> + </dt> + <dd> + The <strong>REPLY...AFTER_DAYS</strong> settings define how many days must have + passed before an answer to a request is officially <em>late</em>. + The SPECIAL case is for some types of authority (for example: in the UK, schools) which are + granted a bit longer than everyone else to respond to questions. + The <strong>WORKING_OR_CALENDAR_DAYS</strong> setting can be either "working" (the default) + or "calendar", and determines which days are counted. + <div class="more-info"> + <p>Examples:</p> + <ul class="examples"> + <li> + <code>REPLY_LATE_AFTER_DAYS: 20</code> + </li> + <li> + <code>REPLY_VERY_LATE_AFTER_DAYS: 40</code> + </li> + <li> + <code>SPECIAL_REPLY_VERY_LATE_AFTER_DAYS: 60</code> + </li> + <li> + <code>WORKING_OR_CALENDAR_DAYS: working</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="frontpage_publicbody_examples"><code>FRONTPAGE_PUBLICBODY_EXAMPLES</code></a> + </dt> + <dd> + Specify which public bodies you want to be listed as examples on the home page, + using their <code>short_names</code>. + If you want more than one, separate them with semicolons. + Comment this out if you want this to be auto-generated. + <p> + <strong>Warning</strong>: this is slow — don't use in production! + </p> + <div class="more-info"> + <p>Examples:</p> + <ul class="examples"> + <li> + <code>FRONTPAGE_PUBLICBODY_EXAMPLES: 'tgq'</code> + </li> + <li> + <code>FRONTPAGE_PUBLICBODY_EXAMPLES: 'tgq;foo;bar'</code> + </li> + <li> + <code># FRONTPAGE_PUBLICBODY_EXAMPLES: </code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="theme_urls"><code>THEME_URLS</code></a> + </dt> + <dd> + URLs of <a href="{{ site.baseurl }}docs/customising/themes">themes</a> to download and use + (when running the <code>rails-post-deploy</code> script). The earlier in the list means + the templates have a higher priority. + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <pre> +THEME_URLS: + - 'git://github.com/mysociety/alavetelitheme.git' +</pre> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="theme_branch"><code>THEME_BRANCH</code></a> + </dt> + <dd> + When <code>rails-post-deploy</code> installs the <a href="{{ site.baseurl }}docs/customising/themes">themes</a>, + it will try the theme branch first, but only if you've set <code>THEME_BRANCH</code> + to be true. If the branch doesn't exist it will fall back to using a tagged version + specific to your installed alaveteli version, and if that doesn't exist it will + back to <code>master</code>. + <p> + The default theme is the "Alaveteli" theme. This gets installed automatically when + <code>rails-post-deploy</code> runs. + </p> + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>THEME_BRANCH: false</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="force_registration_on_new_request"><code>FORCE_REGISTRATION_ON_NEW_REQUEST</code></a> + </dt> + <dd> + Does a user needs to sign in to start the New Request process? + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>FORCE_REGISTRATION_ON_NEW_REQUEST: false</code> + </li> + </ul> + </div> + </dd> + + + <dt> + <a name="incoming_email_domain"><code>INCOMING_EMAIL_DOMAIN</code></a> + </dt> + <dd> + Your email domain for incoming mail. + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>INCOMING_EMAIL_DOMAIN: 'localhost'</code> + </li> + <li> + <code>INCOMING_EMAIL_DOMAIN: 'foifa.com'</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="incoming_email_prefix"><code>INCOMING_EMAIL_PREFIX</code></a> + </dt> + <dd> + An optional prefix to help you distinguish FOI requests. + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>INCOMING_EMAIL_PREFIX: ''</code> + </li> + <li> + <code>INCOMING_EMAIL_PREFIX: 'foi+'</code> + </li> + </ul> + </div> + </dd> + + + <dt> + <a name="incoming_email_secret"><code>INCOMING_EMAIL_SECRET</code></a> + </dt> + <dd> + Used for hash in request email address. + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>INCOMING_EMAIL_SECRET: '11ae 4e3b 70ff c001 3682 4a51 e86d ef5f'</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="blackhole_prefix"><code>BLACKHOLE_PREFIX</code></a> + </dt> + <dd> + Used as envelope from at the incoming email domain for cases where you don't care about failure. + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>BLACKHOLE_PREFIX: 'do-not-reply-to-this-address'</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="admin_username"><code>ADMIN_USERNAME</code></a> + & + <a name="admin_password"><code>ADMIN_PASSWORD</code></a> + <br> + <a name="admin_username"><code>DISABLE_EMERGENCY_USER</code></a> + </dt> + <dd> + The emergency user. + <div class="more-info"> + <p>Examples:</p> + <ul class="examples"> + <li> + <code>ADMIN_USERNAME: 'adminxxxx'</code> + </li> + <li> + <code>ADMIN_PASSWORD: 'passwordx'</code> + </li> + <li> + <code>DISABLE_EMERGENCY_USER: false</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="skip_admin_auth"><code>SKIP_ADMIN_AUTH</code></a> + </dt> + <dd> + Set this to true, and the admin interface will be available to anonymous users. + Obviously, you should not set this to be true in production environments. + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>SKIP_ADMIN_AUTH: false</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="contact_email"><code>CONTACT_EMAIL</code></a> + & + <a name="contact_name"><code>CONTACT_NAME</code></a> + </dt> + <dd> + Email "from" details. + <div class="more-info"> + <p>Examples:</p> + <ul class="examples"> + <li> + <code>CONTACT_EMAIL: 'team@example.com'</code> + </li> + <li> + <code>CONTACT_NAME: 'Alaveteli Webmaster'</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="track_sender_email"><code>TRACK_SENDER_EMAIL</code></a> & + <a name="track_sender_name"><code>TRACK_SENDER_NAME</code></a> + </dt> + <dd> + Email "from" details for track messages. + <div class="more-info"> + <p>Examples:</p> + <ul class="examples"> + <li> + <code>TRACK_SENDER_EMAIL: 'alaveteli@example.com'</code> + </li> + <li> + <code>TRACK_SENDER_NAME: 'Alaveteli Webmaster'</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="raw_emails_location"><code>RAW_EMAILS_LOCATION</code></a> + </dt> + <dd> + Where the raw incoming email data gets stored. + <strong>Make sure you back this up!</strong> + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>RAW_EMAILS_LOCATION: 'files/raw_emails'</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="cookie_store_session_secret"><code>COOKIE_STORE_SESSION_SECRET</code></a> + </dt> + <dd> + Secret key for signing cookie_store sessions. Make it long and random. + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>COOKIE_STORE_SESSION_SECRET: 'uIngVC238Jn9NsaQizMNf89pliYmDBFugPjHS2JJmzOp8'</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="read_only"><code>READ_ONLY</code></a> + </dt> + <dd> + If present, <strong>READ_ONLY</strong> puts the site in read-only mode, + and uses the text as reason (whole paragraph). Please use a read-only database + user as well, as it only checks in a few obvious places. + <div class="more-info"> + <p>Examples:</p> + <ul class="examples"> + <li> + Typically, you do <strong>not</strong> want to run your site in + read-only mode — so set <strong>READ_ONLY</strong> to be + an empty string. + <br> + <code> + READ_ONLY: '' + </code> + </li> + <li> + <code> + READ_ONLY: 'The site is not currently accepting requests while we move the server.' + </code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="staging_site"><code>STAGING_SITE</code></a> + </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> + 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. + <div class="more-info"> + <p>Examples:</p> + <ul class="examples"> + <li> + For staging or development: + <p> + <code>STAGING_SITE: 1</code> + </p> + </li> + <li> + For production: + <p> + <code>STAGING_SITE: 0</code> + </p> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="recaptcha_public_key"><code>RECAPTCHA_PUBLIC_KEY</code></a> & + <a name="recaptcha_private_key"><code>RECAPTCHA_PRIVATE_KEY</code></a> + </dt> + <dd> + Recaptcha, for detecting humans. Get keys here: + <a href="http://recaptcha.net/whyrecaptcha.html">http://recaptcha.net/whyrecaptcha.html</a> + + <div class="more-info"> + <p>Examples:</p> + <ul class="examples"> + <li> + <code>RECAPTCHA_PUBLIC_KEY: '7HoPjGBBBBBBBBBkmj78HF9PjjaisQ893'</code> + </li> + <li> + <code>RECAPTCHA_PRIVATE_KEY: '7HjPjGBBBBBCBBBpuTy8a33sgnGG7A'</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="new_response_reminder_after_days"><code>NEW_RESPONSE_REMINDER_AFTER_DAYS</code></a> + </dt> + <dd> + Number of days after which to send a 'new response reminder'. + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>NEW_RESPONSE_REMINDER_AFTER_DAYS: [3, 10, 24]</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="debug_record_memory"><code>DEBUG_RECORD_MEMORY</code></a> + </dt> + <dd> + For debugging memory problems. If true, Alaveteli logs + the memory use increase of the Ruby process due to the + request (Linux only). Since Ruby never returns memory to the OS, if the + existing process previously served a larger request, this won't + show any consumption for the later request. + + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>DEBUG_RECORD_MEMORY: false</code> + </li> + </ul> + </div> + </dd> + + + <dt> + <a name="use_ghostscript_compression"><code>USE_GHOSTSCRIPT_COMPRESSION</code></a> + </dt> + <dd> + Currently we default to using pdftk to compress PDFs. You can + optionally try Ghostscript, which should do a better job of + compression. Some versions of pdftk are buggy with respect to + compression, in which case Alaveteli doesn't recompress the PDFs at + all and logs a warning message "Unable to compress PDF" — which would + be another reason to try this setting. + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>USE_GHOSTSCRIPT_COMPRESSION: true</code> + </li> + </ul> + </div> + </dd> + + + <dt> + <a name="gaze_url"><code>GAZE_URL</code></a> + </dt> + <dd> + Alateveli uses mySociety's gazeteer service to determine country from incoming + IP address (this lets us suggest an Alaveteli in their country, if one exists). + You shouldn't normally need to change this. + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>GAZE_URL: http://gaze.mysociety.org</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="forward_nonbounce_responses_to"><code>FORWARD_NONBOUNCE_RESPONSES_TO</code></a> + </dt> + <dd> + The email address to which non-bounce responses should be forwarded + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>FORWARD_NONBOUNCE_RESPONSES_TO: user-support@example.com</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="html_to_pdf_command"><code>HTML_TO_PDF_COMMAND</code></a> + </dt> + <dd> + Path to a program that converts an HTML page in a file to PDF. It + should take two arguments: the URL, and a path to an output file. + A static binary of <a href="http://wkhtmltopdf.org">wkhtmltopdf</a> is recommended. + If the command is not present, a text-only version will be rendered + instead. + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>HTML_TO_PDF_COMMAND: /usr/local/bin/wkhtmltopdf-amd64</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="exception_notifications_from"><code>EXCEPTION_NOTIFICATIONS_FROM</code></a> & + <a name="exception_notifications_to"><code>EXCEPTION_NOTIFICATIONS_TO</code></a> + </dt> + <dd> + Email address(es) used for sending exception notifications. + <div class="more-info"> + <p>Examples:</p> + <ul class="examples"> + <li> + <pre> +EXCEPTION_NOTIFICATIONS_FROM: do-not-reply-to-this-address@example.com + +EXCEPTION_NOTIFICATIONS_TO: + - robin@example.com + - seb@example.com +</pre> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="max_requests_per_user_per_day"><code>MAX_REQUESTS_PER_USER_PER_DAY</code></a> + </dt> + <dd> + This rate limiting can be turned off per-user via the admin interface. + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>MAX_REQUESTS_PER_USER_PER_DAY: 6</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="varnish_host"><code>VARNISH_HOST</code></a> + </dt> + <dd> + If you're running behind Varnish, it might help to set this to + work out where to send purge requests. + Otherwise, don't set it. + <div class="more-info"> + <p>Examples:</p> + <ul class="examples"> + <li> + <code>VARNISH_HOST: null</code> + </li> + <li> + <code>VARNISH_HOST: localhost</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="ga_code"><code>GA_CODE</code> (GA=Google Analytics)</a> + </dt> + <dd> + Adding a value here will enable Google Analytics on all non-admin pages for non-admin users. + <div class="more-info"> + <p>Examples:</p> + <ul class="examples"> + <li> + <code>GA_CODE: ''</code> + </li> + <li> + <code>GA_CODE: 'AB-8222142-14'</code> + </li> + </ul> + </div> + </dd> + + + <dt> + <a name="override_all_public_body_request_emails"><code>OVERRIDE_ALL_PUBLIC_BODY_REQUEST_EMAILS</code></a> + </dt> + <dd> + If you want to override <strong>all</strong> the public body request emails with + your own email address so that request emails that would normally go to the public body + go to you, use this setting. + This is useful for a staging server, so you can play with the whole process of sending requests + without inadvertently sending an email to a real authority. + <div class="more-info"> + <p>Examples:</p> + <ul class="examples"> + <li> + <code>OVERRIDE_ALL_PUBLIC_BODY_REQUEST_EMAILS: test-email@foo.com</code> + </li> + <li> + If you don't want this behaviour, comment the setting out + <br> + <code># OVERRIDE_ALL_PUBLIC_BODY_REQUEST_EMAILS:</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="utility_search_path"><code>UTILITY_SEARCH_PATH</code></a> + </dt> + <dd> + Search path for external command-line utilities (such as pdftohtml, pdftk, unrtf). + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>UTILITY_SEARCH_PATH: ["/usr/bin", "/usr/local/bin"]</code> + </li> + </ul> + </div> + </dd> + + + <dt> + <a name="mta_log_path"><code>MTA_LOG_PATH</code></a> + </dt> + <dd> + Path to your exim or postfix log files that will get sucked up + by <code>script/load-mail-server-logs</code>. + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>MTA_LOG_PATH: '/var/log/exim4/exim-mainlog-*'</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="mta_log_type"><code>MTA_LOG_TYPE</code></a> + </dt> + <dd> + Are you using "exim" or "postfix" for your Mail Transfer Agnt (MTA)? + + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>MTA_LOG_TYPE: "exim"</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="donation_url"><code>DONATION_URL</code></a> + </dt> + <dd> + URL where people can donate to the organisation running the site. If set, + this will be included in the message people see when their request is + successful. + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>DONATION_URL: "http://www.mysociety.org/donate/"</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="public_body_statistics_page"><code>PUBLIC_BODY_STATISTICS_PAGE</code></a> & + <a name="minimum_requests_for_statistics"><code>MINIMUM_REQUESTS_FOR_STATISTICS</code></a> + </dt> + <dd> + If <strong>PUBLIC_BODY_STATISTICS_PAGE</strong> is set to true, Alaveteli will make a + page of statistics on the performance of public bodies (which you can see at + <code>/body_statistics</code>). + The page will only consider public bodies that have had at least the number of requests + set by <strong>MINIMUM_REQUESTS_FOR_STATISTICS</strong>. + + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>PUBLIC_BODY_STATISTICS_PAGE: false</code> + </li> + <li> + <code>MINIMUM_REQUESTS_FOR_STATISTICS: 50</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="public_body_list_fallback_to_default_locale"><code>PUBLIC_BODY_LIST_FALLBACK_TO_DEFAULT_LOCALE</code></a> + </dt> + <dd> + If you would like the public body list page to include bodies that have no translation + in the current locale (but which do have a translation in the default locale), set this to true. + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>PUBLIC_BODY_LIST_FALLBACK_TO_DEFAULT_LOCALE: false</code> + </li> + </ul> + </div> + </dd> + + + <dt> + <a name="use_mailcatcher_in_development"><code>USE_MAILCATCHER_IN_DEVELOPMENT</code></a> + </dt> + <dd> + <!-- TODO check mailcatcher URL --> + If true, while in development mode, try to send mail by SMTP to port + 1025 (the port the <a href="http://mailcatcher.me">mailcatcher</a> listens on by default): + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>USE_MAILCATCHER_IN_DEVELOPMENT: true</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="cache_fragments"><code>CACHE_FRAGMENTS</code></a> + </dt> + <dd> + Use memcached to cache HTML fragments for better performance. + This will only have an effect in environments where + <code>config.action_controller.perform_caching</code> is set to true + + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>CACHE_FRAGMENTS: true</code> + </li> + </ul> + </div> + </dd> + + + + <dt> + <a name="shared_files_path"><code>SHARED_FILES_PATH</code></a> + </dt> + <dd> + In some deployments of Alaveteli you may wish to install each newly + deployed version alongside the previous ones, in which case certain + files and resources should be shared between these installations. + For example, the <code>files</code> directory, the <code>cache</code> directory and the + generated graphs such as <code>public/foi-live-creation.png</code>. If you're + installing Alaveteli in such a setup then set <strong>SHARED_FILES_PATH</strong> to + the directory you're keeping these files under. Otherwise, leave it blank. + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>SHARED_FILES_PATH: ''</code> <!-- TODO specific example --> + </li> + </ul> + </div> + </dd> + + + <dt> + <a name="shared_files"><code>SHARED_FILES</code></a> & + <a name="shared_directories"><code>SHARED_DIRECTORIES</code></a> + </dt> + <dd> + If you have <strong>SHARED_FILES_PATH</strong> set, then these options list the files + and directories that are shared; i.e. those to which the deploy scripts + should create symlinks from the repository. + <div class="more-info"> + <p>Examples:</p> + <ul class="examples"> + <li> + <pre> +SHARED_FILES: + - config/database.yml + - config/general.yml + - config/rails_env.rb + - config/newrelic.yml + - config/httpd.conf + - public/foi-live-creation.png + - public/foi-user-use.png + - config/aliases + </pre> + </li> + <li> + <pre> +SHARED_DIRECTORIES: + - files/ + - cache/ + - lib/acts_as_xapian/xapiandbs/ + - vendor/bundle + - public/assets + </pre> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="allow_batch_requests"><code>ALLOW_BATCH_REQUESTS</code></a> + </dt> + <dd> + Allow some users to make batch requests to multiple authorities. Once + this is set to true, you can enable batch requests for an individual + user via the user admin page. + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>ALLOW_BATCH_REQUESTS: false</code> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="responsive_styling"><code>RESPONSIVE_STYLING</code></a> + </dt> + <dd> + + Use the responsive base stylesheets and templates, rather than + those that only render the site at a fixed width. These + stylesheets are currently experimental but will become the default + in the future. They allow the site to render nicely on mobile + devices as well as larger screens. Currently the fixed width + stylesheets are used by default. + + <div class="more-info"> + <p>Example:</p> + <ul class="examples"> + <li> + <code>RESPONSIVE_STYLING: true</code> + </li> + </ul> + </div> + </dd> + +</dl> + +<a name="other-config"> </a> + +## Other configuration files + +Note that there are other configuration files for Alaveteli — you'll find them all +in the `config` directory. These are presented in the git repository as `*-example` files +which you can copy into place. + +<dl> + <dt> + <strong>database.yml</strong> + </dt> + <dd> + database settings (as per Rails) + </dd> + <dt> + <strong>deploy.yml</strong> + </dt> + <dd> + deployment specifications used by Capistrano + </dd> + <dt> + <strong>httpd.conf, nginx.conf</strong> + </dt> + <dd> + Apache and Nginx configuration suggestions + </dd> + <dt> + <strong>newrelic.yml</strong> + </dt> + <dd> + Analytics configuration + </dd> +</dl> diff --git a/docs/customising/index.md b/docs/customising/index.md new file mode 100644 index 000000000..4b8cf9fda --- /dev/null +++ b/docs/customising/index.md @@ -0,0 +1,44 @@ +--- +layout: page +title: Customising +--- + +# Customising Alaveteli + +<p class="lead"> + There are two ways to make your installation look and act the way you want. + Some behaviour can be controlled with <strong>configuration settings</strong>. + For more complex changes, you'll need to create a new <strong>theme</strong>. +</p> + + +## Configuration settings + +You can customise much of Alaveteli's behaviour just by editing the configuration +file. This [complete list of Alaveteli's config settings]({{ site.baseurl }}docs/customising/config) +shows the sort of things you can control in this way. + +<!-- TODO key settings --> + +## Simple branding: colour and logo + +It's common to want to change the basic appearance of the site. Although you +can simply edit the default templates and CSS to do this, we **strongly +recommend** that you [create a theme]({{ site.baseurl }}docs/customising/themes). + +Themes do not need to be especially complex, but they allow your changes to +work alongside the core code, which you can then update (when new releases or +updates become available). + +## Need Alaveteli in a different language? + +No problem! See the [information about translating Alaveteli]({{ site.baseurl }}docs/customising/translation). + +## Complex changes + +If you are a developer (or you have a team of programmers available) you can +add any customisation that you want. But it's important to do this without +breaking the core code, so that you can accept new releases with updates. +There's more detail in the [page about themes]({{ site.baseurl }}docs/customising/themes). + +See also the [documentation for developers]({{ site.baseurl }}docs/developers). diff --git a/docs/customising/themes.md b/docs/customising/themes.md new file mode 100644 index 000000000..65410ece2 --- /dev/null +++ b/docs/customising/themes.md @@ -0,0 +1,191 @@ +--- +layout: page +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 + control more complex things like <em>how</em> the site behaves. +</p> + +When you customise your Alaveteli site, there is a lot you can change just +by editing the [config settings]({{ site.baseurl }}docs/customising/config). +But if you want to change the way the site looks, or add more specific +behaviour, you'll need to make a **theme**. + +You don't need to be a programmer in order to make simple changes, but you will +need to be confident enough to copy and change some files. If you're not sure +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](#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 +"[View authorities](http://www.whatdotheyknow.com/body/list/all)" page +on WhatDoTheyKnow. + +There may also be other things you want to customise -- drop a line on +the developer's mailing list to discuss what you need. We're still working +out the best way of doing these kinds of customisations! + +In any case, the important principle to bear in mind is that the less +you override and customise the code, the easier your site will be to +maintain in the long term. Any customisation is possible, but for +each customisation beyond the simple cases documented here, ask +yourself (or your client), "can we possibly live without this?" If the +answer is "no", then consider starting a discussion about a pluggable +way of achieving your goals, rather than overriding any of the core +code. + +## General principles + +We try to encapsulate all site-specific functionality in one of these +places: + +* Site [configuration]({{ site.baseurl }}docs/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) +* A theme, installed in `lib/themes`. + +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 }}docs/customising/config/#theme_urls) +in `general.yml` for an explanation. + +You can also install the sample theme by hand, by running: + + 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 +use that as the basis for your own theme. + +## Make sure your theme is as lightweight as possible + +The more you put in your theme, the harder it will be to upgrade to +future versions of Alaveteli. Everything you place in your theme +overrides things in the core theme, so if you make a new "main +template", then new widgets that appear in the core theme won't appear +on your website. + +Therefore, you should consider how you can brand your website without +changing much in the core theme. The ideal would be if you are able +to rebrand the site by only changing the CSS. You will also need to +add custom help pages, as described below. + +## Branding the site + +The core templates that comprise the layout and user interface of an +Alaveteli site live in `app/views/`. They use Rails' ERB syntax. +For example, the template for the home page lives at +`app/views/general/frontpage.html.erb`, and the template for the "about +us" page is at `app/views/help/about.html.erb`. + +Obviously, you *could* edit those core files directly, but this would +be a Bad Idea, because you would find it increasingly hard to do +upgrades. Having said that, sometimes you may want to change the core +templates in a way that would benefit everyone, in which case, discuss +the changes on the mailing list, make them in a fork of Alaveteli, and +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/views/help/about.rhml` will appear +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>, +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> +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 + +Categories are implemented in Alaveteli using tags. Specific tags can +be designated to group authorities together as a category. + +There's a file in the sample theme, +`alavetelitheme/lib/public_body_categories_en.rb`, which contains a +nested structure that defines categories. It contains a comment +describing its structure. You should make a copy of this file for each +locale you support. + +## Customising the request states + +As mentioned above, if you can possibly live with the +[default Alaveteli request statuses]({{ site.baseurl }}docs/running/states), +it would be good to do so. Note that you can set how many days counts +as "overdue" in the main site config file — +see [`REPLY_LATE_AFTER_DAYS`]({{ site.baseurl }}docs/customising/config/#reply_late_after_days). + +If you can't live with the states as they are, there's a very basic +way to add to them (which will get improved over time). There's not +currently a way to remove any easily. There is an example of how to +do this in the `alavetelitheme`. + +To do add states, create two modules in your theme, +`InfoRequestCustomStates` and `RequestControllerCustomStates`. The +former must have these methods: + +* `theme_calculate_status`: return a tag to identify the current state of the request +* `theme_extra_states`: return a list of tags which identify the extra states you'd like to support +* `theme_display_status`: return human-readable strings corresponding with these tags + +The latter must have one method: + +* `theme_describe_state`: Return a notice for the user suitable for + displaying after they've categorised a request; and redirect them to + a suitable next page + +When you've added your extra states, you also need to create the following files in your theme: + +* `lib/views/general/_custom_state_descriptions.html.erb`: Descriptions + of your new states, suitable for displaying to end users +* `lib/views/general/_custom_state_transitions_complete.html.erb`: + Descriptions for any new states that you might characterise as + 'completion' states, for displaying on the categorisation form that + we ask requestors to fill out +* `lib/views/general/_custom_state_transitions_pending.html.erb`: As + above, but for new states you might characterise as 'pending' + states. + +You can see examples of these customisations in +[this commit](https://github.com/sebbacon/informatazyrtare-theme/commit/2b240491237bd72415990399904361ce9bfa431d) +for the Kosovan version of Alaveteli, Informata Zyrtare (ignore the +file `lib/views/general/_custom_state_transitions.html.erb`, which is +unused). + +## Adding new pages in the navigation + +`alavetelitheme/lib/config/custom-routes.rb` allows you to extend the base routes in +Alaveteli. The example in `alavetelitheme` adds an extra help page. +You can also use this to override the behaviour of specific pages if +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. diff --git a/docs/customising/translation.md b/docs/customising/translation.md new file mode 100644 index 000000000..4f3c39270 --- /dev/null +++ b/docs/customising/translation.md @@ -0,0 +1,123 @@ +--- +layout: page +title: Translation +--- + +# Translating Alaveteli + +<p class="lead"> + We've designed Alaveteli to be used in many different + jurisdictions all around the world. If it doesn't already + support the language you need, you can help by translating + it. This page explains how. +</p> + +## Alaveteli's translations + +The software translations are implemented using GNU gettext, and the resource +files are managed in Transifex. + +The Transifex project is at +[https://www.transifex.net/projects/p/alaveteli](https://www.transifex.net/proje +cts/p/alaveteli) -- you'll probably want an account there (ask on the mailing +list). It has a fairly easy-to-use interface for contributing translations. + +There are three roles in the translation process, and each one is described +below: **translator**, **developer**, and **release manager**. You probably only +need to know about the one that applies to you. + +## Translation process: translator's view + +**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 +use some code to mark sentences or words ("strings") that they think will need +to be translated. + +When the Alaveteli release manager is planning a release, they will upload a +template containing all the strings to be translated (called a POT) to +Transifex. This causes your own translations in Transifex to be updated with +the latest strings. + +When you visit Transifex, it will prompt you to fill out values for all new +strings, and all strings that have been modified. In the case where a string +has only been slightly modified, such as with punctuation ("Hello" has become +"Hello!"), Transifex will suggest a suitable translation for you (look for the +"suggestions" tab under the source string). + +In order for this feature to work properly, the release manager has to download +your translations, run a program that inserts the suggestions, and then upload +them again. Therefore, when a release candidate is announced, make sure you +have uploaded any outstanding translations, or you will lose them. + +When a release candidate has been annouced, there is a **translation freeze**: +during this period, developers must not add any new strings to the software, so +you can be confident that you're translating everything that will be in the +final release. + +The release manager will also give you a **translation deadline**. After this +date, you can continue to contribute new translations, but they won't make it +into the release. + +### General notes on translation in Transifex + +Some strings will have comments attached to them from the Alaveteli +application developers about the context in which the text appears in the +application — these comments will appear under the 'Details' tab for the text +in Transifex. + +Some strings will have **placeholders** in them to indicate that Alaveteli +will insert some text of its own into them when they're displayed. They +will be surrounded by double curly brackets, and look like this: + +<code> + some text with {{placeholder}} in it +</code> + +For these strings, don't translate the placeholder. It needs to stay exactly +the same for the text to be inserted properly: + +<code> + ein Text mit {{placeholder}} in ihm +</code> + +Similarly, some strings may contain small bits of HTML — these will have +code in angle brackets (it might really be indicating that the text is a link, +or that it needs special formatting). For example: + +<code> + please <a href=\"{{url}}\">send it to us</a> +</code> + +Again, don't edit the bits between the angle brackets — preserve them in your +translation, and just edit the text around them. So the example might become: + +<code> + bitte <a href=\"{{url}}\">schicken Sie es uns</a> +</code> + +Some strings are in the form of two pieces of text separated by a vertical +bar (`|`) character, e.g. `IncomingMessage|Subject`. These represent attribute +names, so `IncomingMessage|Subject` is the subject attribute of an incoming +message on the site. Do not prioritise these types of text when translating -- +they do not appear on the site anywhere at the moment, and when they do, they +will only be used in the admin interface. If you do translate them, only +translate the text that comes *after* the `|`. + +## Translation process: developers' view + +**If you're writing new code for Alaveteli, then you're a developer, and you +need to understand how to make any text you add easy for translators to work +with.** + +Please read our [internationalisation +guide](http://mysociety.github.io/internationalization.html) for our advice on +using strings that will need translation. This applies across all mySociety +projects, not just Alaveteli. + +The release manager will enforce a translation freeze just before a new release +is cut. During such time, you must not introduce new strings to the code if +your work is due for inclusion in this release. This is necessary to allow +translators time to complete and check their translations against all the known +strings. diff --git a/docs/developers/api.md b/docs/developers/api.md new file mode 100644 index 000000000..cbd4c7c85 --- /dev/null +++ b/docs/developers/api.md @@ -0,0 +1,82 @@ +--- +layout: page +title: API +--- + +# Alaveteli API + +<p class="lead"> + There are two parts to the API for accessing or inserting data programmatically: the read API, and the write API. +</p> + +## Read API + +This is provided via JSON versions of most entities in the system, plus atom +feeds for listing entities: + +### Atom feeds + +There are Atom feeds on most pages which list FOI requests, which you can use +to get updates and links in XML format. Find the URL of the Atom feed in one of +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. + +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, +or by status. See the advanced search tips for details. + +### JSON structured data + +Quite a few pages have JSON versions, which let you download information about +objects in a structured form. Find them by: + +* adding `.json` to the end of the URL. +* looking for the `<link rel="alternate" type="application/json">` tag in the head of the HTML. + +Requests, users and authorities all have JSON versions containing basic +information about them. Every Atom feed has a JSON equivalent, containing +information about the list of events in the feed. + +### Starting new requests programmatically + +To encourage users to make links to a particular public authority, use URLs of +the form `http://<yoursite>/new/<publicbody_url_name>`. These are the +parameters you can add to those URLs, either in the URL or from a form: + +* `title` - the default summary of the new request. +* `default_letter` - the default text of the body of the letter. The salutation and signoff for your locale are wrapped round this. +* `body` - as an alternative to `default_letter`, this sets the default entire text of the request, so you can customise the salutation and signoff. +* `tags` - space separated list of tags, so you can find and link up any requests made later, e.g. `openlylocal spending_id:12345`. The `:` indicates it is a machine tag. The values of machine tags may also include colons, useful for URIs. + +## Write API + +The write API is designed to be used by public bodies to create their own +requests in the system. Currently used by mySociety's [FOI +Register](https://github.com/mysociety/foi-register) software to support using +Alaveteli as a disclosure log for all FOI activity at a particular public body. + +All requests must include an API key as a variable `k`. This key can be viewed +on each authority's page in the admin interface. Other variables should be sent +as follows: + +* `/api/v2/request` - POST the following json data as a form variable `json` to create a new request: + * `title` - title for the request + * `body` - body of the request + * `external_user_name` - name of the person who originated the request + * `external_url` - URL where a canonical copy of the request can be found + Returns JSON containing a `url` for the new request, and its `id` +* `/api/v2/request/<id>.json` - GET full information about a request +* `/api/v2/request/<id>.json` - POST additional correspondence regarding a request: + * 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 + * `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 + + + + diff --git a/docs/developers/directory_structure.md b/docs/developers/directory_structure.md new file mode 100644 index 000000000..e073a96ce --- /dev/null +++ b/docs/developers/directory_structure.md @@ -0,0 +1,257 @@ +--- +layout: page +title: Directory structure +--- + + +# Alaveteli's directory structure + +<p class="lead">This page gives you an overview of where to find things in Alaveteli's +directories.</p> + +**You'll probably never need to worry about this** if you're just installing +Alaveteli -- this is really more useful if you're a developer planning on +making more substantive changes to the code. You don't need to be familiar with +Ruby to install or make basic [customisations to your +installation](/docs/customising). + +<!-- (and if you do, +remember to read the page about [feeding your changes back](/feeding-back)).--> + +Alaveteli uses Ruby on Rails, which is a common "Model-View-Controller" web +framework — if you're familiar with Rails this will look very familiar. For +more information about the Rails structure see the [Ruby on Rails +website](http://guides.rubyonrails.org/getting_started.html). + +## Key directories and what they're for + +<dl class="dir-structure"> + <dt> + app + </dt> + <dd> + <p><em>the core Alaveteli application code</em></p> + <dl> + <dt> + controllers + </dt> + <dt> + helpers + </dt> + <dt> + mailers + </dt> + <dt> + models + </dt> + <dt> + sass + </dt> + <dt class="last"> + views + </dt> + </dl> + </dd> + <dt> + assets + </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> + <dt> + bootstrap + </dt> + <dd> + <p> + Alaveteli's default style uses Bootstrap. + </p> + <dt> + commonlib + </dt> + <dd> + <p><em>mySociety's library of common functions</em></p> + <p> + We maintain a <a href="https://github.com/mysociety/commonlib">common + library</a> that we use across many of our projects (not just + Alaveteli). This is implemented as a <a + href="http://git-scm.com/book/en/Git-Tools-Submodules">git submodule</a>, + so Alaveteli contains it even though the code is separate. Normally, you + don't need to think about this (because git handles it automatically)... + but if you really <em>do</em> need to change anything here, be aware that + it is a separate git repository. + </p> + </dd> + <dt> + config + </dt> + <dd> + <p><em>configuration files</em></p> + <p> + The primary configuration file is <code>general.yml</code>. This file isn't in the git + repository (since it will contain information specific to your installation, including + the database password), but example files are. + </p> + </dd> + <dt> + db + </dt> + <dd> + <p><em>database files</em></p> + <dl> + <dt class="last"> + migrate + </dt> + <dd class="last"> + Rails' migration (updating the database scheme up or down + as the code develops). + </dd> + </dl> + </dd> + <dt> + doc + </dt> + <dd> + <p><em>documentation</em></p> + <p> + These are technical notes. This is in addition to the <a + href="http://code.fixmystreet.com">core documentation</a> — which + you are reading now — which is actually stored in the git + repository in the <code>gh-pages</code> branch, and published as GitHub + pages. + </p> + </dd> + <dt> + lib + </dt> + <dd> + <p><em>custom libraries</em></p> + <dl> + <dt> + tasks + </dt> + <dt class="last"> + whatdotheyknow + </dt> + </dl> + </dd> + <dt> + locale + </dt> + <dd> + <p><em>translations (internationalisation/i18n)</em></p> + <p> + The translation strings are stored in <code>.po</code> files in directories specific to + the locale and encoding. For example, <code>es/</code> contains the translations for the Spanish site. + </p> + </dd> + <dt> + public + </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> + </dd> + <dt> + script + </dt> + <dd> + <p><em>server-side shell scripts</em></p> + <p> + For example, <code>alert-overdue-requests</code> for running the script + which finds overdue requests and mails them out. + </p> + </dd> + <dt> + spec + </dt> + <dd> + <p><em>tests</em></p> + <p> + Alaveteli's test suite runs under <a href="TODO">spec</a>. + </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> + <p> + <em>temporary files</em> + </p> + </dd> + <dt class="last"> + vendor + </dt> + <dd class="last"> + <p><em>third-party software</em></p> + <dl> + <dt class="last">plugins</dt> + <dd class="last"> + <p> + Plugins + </p> + </dd> + </dl> + </dd> +</dl> + +We've missed out some of the less important subdirectories here just to keep +things clear. diff --git a/docs/developers/index.md b/docs/developers/index.md new file mode 100644 index 000000000..4b90c9232 --- /dev/null +++ b/docs/developers/index.md @@ -0,0 +1,84 @@ +--- +layout: page +title: For developers +--- + +# Information for developers + +<p class="lead"> + Alaveteli is an open source project. Full-time mySociety developers together with devs from all around the world actively contribute to the codebase. These notes and links will help you if you want to help too. +</p> + +* The software is written in **Ruby on Rails 3.x**. We support postgresql as + the backend database. A configured mail transfer agent (MTA) like exim, + postfix or sendmail is necessary to parse incoming emails. We have production + sites deployed on Debian Squeeze and Ubuntu (10.04 LTS). For performance + reasons, we recommend the use of [Varnish](https://www.varnish-cache.org). + +* To help you understand what the code is doing, read this [high-level + overview]({{ site.baseurl }}docs/developers/overview), which includes a diagram of + the models and how they are related. + +* See the [API documentation]({{ site.baseurl }}docs/developers/api) for how to get + data into or out of Alaveteli. + +* If you need to change or add strings in the interface, see our [guidelines + for internationalisation](http://mysociety.github.io/internationalization.html + ), which include notes about our use of `gettext`. + +* We use the [git flow branching + model](http://nvie.com/posts/a-successful-git-branching-model/), with a small + change: currently our `develop` branch is called `rails-3-develop`, which + means that the latest development version is always found on the + [rails-3-develop + branch](https://github.com/mysociety/alaveteli/tree/rails-3-develop). The + latest stable version is always on the [master + branch](https://github.com/mysociety/alaveteli). If you plan to collaborate + on the software, you may find the [git flow + extensions](https://github.com/nvie/gitflow) useful. + +* 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. If you've got your own server, run the + [installation script]({{ site.baseurl }}docs/installing/script/), or follow the + instructions for a + [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 + for help. + +* A standard initial step for customising your deployment is [writing a + theme]({{ site.baseurl }}docs/customising/themes). **If you only read one thing, + it should be this!** + +* Like many Ruby on Rails sites, the software is not hugely performant (see + some notes about [[performance issues]] gathered over time with + WhatDoTheyKnow). The site will run on a server with 512MB RAM but at least + 2GB is recommended. Deployment behind [Varnish](https://www.varnish-cache.org) is also fairly essential. See + [[Production Server Best Practices]] for more. + +* There's a number of [proposals for enhancements](https://github.com/mysociety/alaveteli/wiki/Proposals-for-enhancements), + such as more user-focused features, but see also... + +* ...the [github issues](https://github.com/mysociety/alaveteli/issues). We + mark issues with the label **suitable for volunteers** if we think they are + especially suitable for diving into if you're just looking for something + relatively small to get your teeth into. + +* We try to ensure every commit has a corresponding issue in the issue tracker. + This makes changelogs easier as we can gather all the fixes for a particular + release against a milestone in the issue tracker, [like this 0.4 + release](https://github.com/mysociety/alaveteli/issues?milestone=7&state=close + d). + +* If you're experiencing memory issues, [this blog post about some strategies + used in the + past](http://www.mysociety.org/2009/09/17/whatdotheyknow-growing-pains-and-rub + y-memory-leaks/) might be useful. + +* If you're coding on a mac, see these [MacOS X installation notes]({{ site.baseurl }}docs/installing/macos). <!-- [[OS X Quickstart]] --> + +* We try to adhere to similar good practice across all our projects: see + [mysociety.github.io](http://mysociety.github.io/) for things like our + [coding standards](http://mysociety.github.io/coding-standards.html) diff --git a/docs/developers/overview.md b/docs/developers/overview.md new file mode 100644 index 000000000..ca2d27985 --- /dev/null +++ b/docs/developers/overview.md @@ -0,0 +1,51 @@ +--- +layout: page +title: High-level overview +--- + +# High-level overview + +<p class="lead"> + This page describes the process and entities that make up Alaveteli. + It's a high-level overview of how Alaveteli works to help you orientate yourself to the code. +</p> + +_See also the [schema diagram](#schema-diagram) at the bottom of this page._ + +The main entity is **InfoRequest**, which represents a request for information by a +**User** to a **PublicBody**. A new InfoRequest results in an initial **OutgoingMessage**, +which represents the initial email. + +Once an InfoRequest is made, its state is tracked using **InfoRequestEvents**. For +example, a new InfoRequest has an initial state of `awaiting_response` and an +associated InfoRequestEvent of type `initial_request`. An InfoRequest event can +have an OutgoingMessage or an IncomingMessage or neither associated with it. + +Replies are received by the system by piping raw emails (represented by a **RawEmail**) +from the MTA to a script at `scripts/mailin`. This parses the email, tries to identify the +associated InfoRequest, and then generates an **IncomingMessage** which references +both the RawEmail and the InfoRequest. + +Any User can make **Comments** on InfoRequests. + +All events (e.g., Comments, OutgoingMessages) are tracked in InfoRequestEvent. + +A **TrackThing** is a canned search that allows users to be alerted when events +matching their criteria are found. (How this worked changed after we'd +launched, so there's still some deprecated code there for things we've phased +out.) + +The **MailServerLog** is a representation of the parsed MTA log files. +MailServerLog entries are created by a cron job that runs +`scripts/load-mail-server-logs`. This checks incoming emails and matches them +to InfoRequests; then `script/check-recent-requests-send` checkes these logs to +ensure they have an envelope-from header set (to combat spam). + +## Schema diagram + +<a name="schema-diagram" href="{{ site.baseurl }}images/railsmodels.png"><img src="{{ site.baseurl }}images/railsmodels.png"></a> + +This schema for the Rails models was generated from the code on 19 Dec 2012 using +[Railroad](http://railroad.rubyforge.org/). + +The railroad command is: `railroad -M | dot -Tpng > railsmodels.png` diff --git a/docs/getting_started.md b/docs/getting_started.md new file mode 100644 index 000000000..4bfd9eb24 --- /dev/null +++ b/docs/getting_started.md @@ -0,0 +1,380 @@ +--- +layout: page +title: Getting started +--- + +# Getting started with Alaveteli + +<p class="lead"> + This guide is aimed at people who are thinking about setting up their own + Alaveteli website in a new jurisdiction. +</p> + +For inspiration, take a look at some of the existing Alaveteli websites, like +[tuderechoasaber.es](http://tuderechoasaber.es) (Spain), +[AskTheEU](http://asktheeu.org) (EU), or +[WhatDoTheyKnow](http://www.whatdotheyknow.com) (UK). These sites all use the +Alaveteli software, plus their own custom themes installed on top to make them +look different. + +You don't even need to make a custom theme to get started. You can have a +website that looks like [the demo website](http://demo.alaveteli.org) and +simply drop in your own logo. + +The process of getting your own Alaveteli website up and running could take +anywhere from one day to three months, depending on the scale of your ambition +for customising the software, your access to technical skills, and your +available time. + +You can get a feeling for how things might turn out by reading [how an +Alaveteli was set up in +Spain](http://www.alaveteli.org/2012/04/a-right-to-know-site-for-spain/) +(remember that this was with an experienced developer in charge). You will also +need to think about how you will run the website; a successful Alaveteli +requires lots of ongoing effort to moderate and publicise (see Step 6 and Step +7, below). + +Here are the steps we suggest you follow in order to get started. + +* [Step zero: assemble your initial team](#step-0) +* [Step one: get a working, uncustomised version running](#step-1) +* [Step two: start to gather data about public authorities](#step-2) +* [Step three: customise the site](#step-3) +* [Step four: translate everything](#step-4) +* [Step five: Test drive the site](#step-5) +* [Step six: Market the website](#step-6) +* [Step seven: Maintain the website](#step-7) + + +<a name="step-0"> </a> + +## Step zero: assemble your initial team + +You're unlikely to be able to get much done on your own. You will need +translators, people to hunt down email addresses of authorities, possibly a +designer, and preferably a technical expert to help with customisations. Read +through this guide first, and think about the skills you will need to +successfully launch and maintain the website. + +It took about [ten people (including translators) working for three +days](http://groups.google.com/group/alaveteli-dev/msg/1bd4afd3091f8b4f) to +launch [Queremos Saber](http://queremossaber.org.br/), a Brazilian version of +Alaveteli. + +> It was really cool setting the site up. And even with some minor +> difficulties (most related to the fact that we had no one really experienced +> with both Ruby on Rails and Postfix) it was pretty quick and in less than a +> week we had a fully featured website! +> +> -- _Pedro Markun, Queremos Saber_ + +[AskTheEU](http://asktheeu.org), a much more complete and polished version with +a custom theme and several other customisations, took a team of 2 or 3 people +about 3 months (part time) to complete. + +Ask members of your team to consider joining one of the mailing lists. If you +have any questions, these are the first places to ask. +[alaveteli-users](http://groups.google.com/group/alaveteli-users) is a mailing +list for non-technical users of the software. Post messages there to ask for +advice about getting your project started, questions about how people use the +software, and so on. +[alaveteli-dev](http://groups.google.com/group/alaveteli-dev) is the place to +ask questions of a technical nature, such as problems installing Alaveteli. + +<a name="step-1"> </a> + +## Step one: get a working, uncustomised version running + +You have two options here: install your own copy, or ask the Alaveteli team to +provide a hosted version. + +If you install your own copy, you have complete control over the website, its +performance, how often it is upgraded, and so on. We recommend this as the best +approach. However, you will need some resources to do this. + +Alternatively, we have very limited capacity to run a handful of Alaveteli +sites for willing volunteers. We want to learn more about how we can support +third parties, and to do so we're happy to help host low-volume sites for two +or three partners. However, you will have no service level agreement, no +warranties, and no guarantee on our time: if the website goes down when we're +on holiday, you'll have to wait until we're back! If you want to try this +route, please [get in touch](http://alaveteli.org/contact-us) to find out if +we have capacity. + +### Install your own copy + +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 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). + +Alternatively, you could use Amazon Web Services. This has the +added advantage that you can use our preconfigured [Alaveteli EC2 +AMI]({{ site.baseurl }}docs/installing/ami) to get you +started almost instantly. However, it's more expensive than Rackspace, +especially if you want more RAM. + +### Play around with it + +You'll need to understand how the website works. Until your own copy is +available, you can try the copy running on the [demo +server](http://demo.alaveteli.org) (though note this isn't guaranteed to be +available or working). + +Right now we don't have a guide book, so you'll just have to explore on your +own. + +When you have your own version running, try logging into the admin interface by +adding `/admin` onto the end of your domain name. This will take you to the +administrative interface. It's plain and simple, but functional. For example, +try adding new authorities there, perhaps with your own email address, so you +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. + +<a name="step-2"> </a> + +## Step two: start to gather data about public authorities + +One of the most important things you need to do before launching is to gather +together a list of all the bodies to whom you want to address FOI requests. + +It's a good idea to make a shared speadsheet that you can ask your supporters +to help fill out. A template like [this Google +spreadsheet](https://docs.google.com/spreadsheet/ccc?key=0AgIAm6PdQexvdDJKdzlNdXEtdjBETi1SLVhoUy1QM3c&hl=en_US) is ideal. + +If you email possible supporters asking for help, in addition to helping make +your job easier, it will also help you identify eager people who might be +interested in helping you maintain and run the website. We have written [a +blog post about +this](http://www.alaveteli.org/2011/07/you-need-volunteers-to-make-your-website-work/). + +The admin interface includes a page where you can upload a CSV file (that's a +file containing comma-separated values) to create or edit authorities. CSV is a +convenient format -- for example, it's easy to save data from a spreadsheet as +a CSV file. + +<a name="step-3"> </a> + +## Step three: customise the site + +### Name and social media + +Obviously, you'll want to put your own visual stamp on the site. Once you have +a name for your project (e.g., WhatDoTheyKnow in the UK, AskTheEU in the EU, +InformateZyrtare in Kosovo), register a twitter username, and a domain name. +Alaveteli relies on you keeping a blog for its "News" section, so you might +want to consider setting up a free blog at http://wordpress.com or +http://blogger.com and announce your project with a new blog post. + +### Branding and theming + +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. + +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]({{ site.baseurl }}docs/customising/themes/). You +might spend anywhere between 1 and 15 days on this. + +### Legislative differences + +We rely on users to help categorise their own requests (e.g., as "successful", +or "refused"). We call these categories "states". Most FOI laws around the +world are sufficiently similar that you can probably use Alaveteli's states +exactly as they come out of the box. + +In addition, we have found that it's generally a bad idea to try to implement +laws exactly in the user interface. They are often complicated, and confusing +for users. Since the concept of Alaveteli is to make it easy to exercise the +right to know, we take the view that it's best to implement how a FOI process +*should* be, rather than how it *actually is right now*. + +However, if you really feel you need to alter the states that a request can go +through, it is possible to do this to some degree within your theme. Have a +think about what is required, and then send a message to the Alaveteli mailing +list for feedback and discussion. Then you'll need to ask your developer to +implement the new states. It's usually no more than a couple of days' work, +often less. But complicated workflows might take a bit longer. + +### Write the help pages + +The default help pages in Alaveteli are taken from WhatDoTheyKnow, and are +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/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. + +Once the pages are written, ask your tech person to add them to your theme. + +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). See the +[Administrator's Manual]({{ site.baseurl }}docs/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 + +Perhaps you would like a new usability-related feature not in Alaveteli +already, like the automated language detection for multi-language websites; or +Facebook integration; or an iPhone app. + +Perhaps you've found an area relating to translations that Alaveteli doesn't +yet support fully (for example, we've not yet needed to implement a site with a +language written right-to-left). + +Perhaps your jurisdiction *requires* a new feature not in Alaveteli -- for +example, users may need to send extra information with their requests. + +In these cases, you will need to get your tech person (or some other software +developer) to make these changes for you. This can be time consuming; new +software development, testing, and deployment is often complex. You should get +expert advice on the amount of extra time this will require. Typically, changes +like these could add between one and three months onto the project schedule. + +<a name="step-4"> </a> + +## Step four: translate everything + +This is potentially a big job! + +If you need to support multiple languages in your jurisdiction, you will need +to translate: + +* public authority names, notes, etc +* public authority bodies +* help pages +* all of the web interface instructions in the software + +It's a bit easier if you only need to support one language in your +jurisdiction: because you'll already have written the help and public authority +information, you'll only need to translate the web interface. + +Public authority names can be edited via the admin interface, or by uploading a +spreadsheet. The help pages need to have one copy saved for each language; your +tech person will put them in the right place. + +The web interface translations are managed and collaborated via a website +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.com/projects/p/alaveteli/>; the translations all live in a +single translation file called +[`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) + +There are (at the time of writing) around 1000 different sentences or fragments +of sentences (collectively known as "strings") to be translated. The meaning of +many strings should be fairly obvious, but others less so. Until we write a +guide for translators, the best route to take is translate everything you can, +and then ask your tech person or the project mailing list for advice on +anything you're unsure about. + +Over time, as bugs are fixed and new features are added, new strings are added +to the file. Therefore, you need to keep an eye on `app.pot` and periodically +review the untranslated strings. + +<a name="step-5"> </a> + +## Step five: Test drive the site + +For launch, the tech person should review the [Production Server Best +Practices]({{ site.baseurl }}docs/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 +authorities. Responses are likely to vary widely between and within +jurisdictions, and the right way of making your website a success will vary +with these responses. + +<a name="step-6"> </a> + +## Step six: Market the website + +In general, the best way to engage authorities is with a mixture of +encouragement and exposure. In private, you can explain that in addition to +helping them meet their legal requirements and civic obligations, you may be +reducing their workload by preventing repeat requests. In public, you can work +with journalists to praise authorities that are doing a good job, and highlight +ones that refuse to take part. It is, therefore, very important to make links +with journalists with an interest in freedom of information. + +The other important marketing tool is [Google +Grants](http://www.google.com/grants/), a scheme run by Google that gives free +AdWords to charities in lots of countries around the world. You'll find these +an incredibly useful resource for driving traffic to your site. It's well worth +setting yourself up as a charity if only to take advantage of this programme. + +<a name="step-7"> </a> + +## Step seven: Maintain the website + +Running a successful Alaveteli website requires some regular, ongoing input. +This will be easier to do with a small team of people sharing jobs. Hopefully +you have been lucky enough to get funding to pay people to do these tasks. +However, you are also likely to have to rely on volunteers. We've written [a +blog post about the importance of +volunteers](http://www.alaveteli.org/2011/07/you-need-volunteers-to-make-your-we +bsite-work/), which you should read. + +You'll need to set up a group email address for all the people who will manage +the website. All site user queries will go here, as will automatic +notifications from Alaveteli. A group address is really useful for helping +coordinate responses, discuss policy, etc. + +You could get by with just one or two hours per week. This means keeping an eye +on the "holding pen" of the website, where incoming messages that the site +doesn't know how to handle are stored (things like spam, misaddressed messages, +etc). However, the more effort you put into this, the more successful your +website is. To ensure its success, you should be doing things like: + +* Responding to user help enquiries by email +* Monitoring new requests, looking for people who might need help, posting + encouraging comments on their requests +* Monitoring responses from authorities, looking for ones who are trying to + refuse to answer, offering advice to the person who made the request, possibly coming up with publicity to "shame" the authority into answering +* Tweeting about interesting requests and responses +* Writing blog posts about the progress of the project +* Communicating with journalists about potentially interesting stories +* Recruiting volunteers to help with the site +* Categorising uncategorised requests + +See also the [Administrator's Manual](/docs/running/admin_manual), which describes +some of the typical tasks you'll need to perform when your site is up and +running. + +### What else? + +If there's anything you think would be really useful to have in this getting +started guide which is currently missing, let us know so we can add it. diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 000000000..8d2f815f9 --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,590 @@ +--- +layout: page +title: Glossary +--- + +Glossary +==================== + +<p class="lead"> + Glossary of terms for Alaveteli, mySociety's freedom of information + platform. +</p> + +Definitions +----------- + +<ul class="definitions"> + <li><a href="#alaveteli">Alaveteli</a></li> + <li><a href="#agnostic">asker agnostic</a></li> + <li><a href="#authority">authority</a></li> + <li><a href="#blackhole">black hole</a></li> + <li><a href="#capistrano">Capistrano</a></li> + <li><a href="#censor-rule">censor rule</a></li> + <li><a href="#development">development site</a></li> + <li><a href="#foi">freedom of information</a></li> + <li><a href="#git">git</a></li> + <li><a href="#holding_pen">holding pen</a></li> + <li><a href="#mta">MTA</a></li> + <li><a href="#production">production site</a></li> + <li><a href="#publish">publish</a></li> + <li><a href="#recaptcha">recaptcha</a></li> + <li><a href="#redact">redacting</a></li> + <li><a href="#regexp">regular expression</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="#staging">staging site</a></li> + <li><a href="#state">state</a></li> + <li><a href="#theme">theme</a></li> +</ul> + + +<dl class="glossary"> + + <dt> + <a name="alaveteli">Alaveteli</a> + </dt> + <dd> + <strong>Alaveteli</strong> is the name of the open source software platform created + by <a href="http://www.mysociety.org">mySociety</a> for submitting, + managing and archiving Freedom of Information requests. + <p> + It grew from the successful FOI UK project + <a href="http://www.whatdotheyknow.com">WhatDoTheyKnow</a>. + We use the name <em>Alaveteli</em> to distinguish the software + that runs the platform from any specific website that it is powering. + </p> + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + The Alaveteli website is at <a href="http://www.alaveteli.org">www.alaveteli.org</a> + </li> + <li> + The name "Alaveteli" comes from + <a href="http://en.wikipedia.org/wiki/Alaveteli,_Finland">Alaveteli in Finland</a> + where + <a href="http://en.wikipedia.org/wiki/Anders_Chydenius">an early FOI campaigner</a> + once worked. + </li> + </ul> + </div> + </dd> + + <dt> + <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 + 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> + 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 + to FoI requests privately, instead of publishing their responses themselves. One of the + functions of Alaveteli is, therefore, to act as a public repository of published answers. + This also serves to reduce duplicate requests, by publishing the answer instead of + requiring it to be asked again. + </p> + </dd> + + <dt> + <a name="authority">authority</a> + </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>. + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + An administrator can add, edit, or remove authorities in the admin + </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 + 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 + to it, or which we believe should be accountable in this way. + </li> + </ul> + </div> + </dd> + + <dt> + <a name="blackhole">black hole</a> + </dt> + <dd> + A <strong>black hole</strong> is an email address that accepts and destroys + any email messages that are sent to it. Alaveteli uses this for "do not + reply" emails, which are usually automatically generated system emails. + </p> + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + Use the config setting + <code><a href="{{site.baseurl}}docs/customising/config/#blackhole_prefix">BLACKHOLE_PREFIX</a></code> + to specify what this email address looks like. + </li> + <li> + Conversely, see + <code><a href="{{site.baseurl}}docs/customising/config/#contact_email">CONTACT_EMAIL</a></code> + to specify the email address to which users' emails (such as support + enquiries) will be delivered. + </li> + </ul> + </div> + </dd> + + <dt> + <a name="capistrano">Capistrano</a> + </dt> + <dd> + <strong>Capistrano</strong> is a remote server automation and deployment tool written in Ruby. + Alaveteli's deployment mechanism, which is optional, uses it. + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + how to <a href="{{ site.baseurl }}docs/installing/deploy">deploy Alaveteli</a> (and why it's + a good idea) + </li> + <li> + The <a href="http://capistranorb.com/">Capistrano website</a> has thorough documentation + about the tool + </li> + </ul> + </div> + </dd> + + <dt> + <a name="censor-rule">censor rule</a> + </dt> + <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>. + </p> + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + see the + <a href="{{ site.baseurl }}docs/running/admin_manual/">admin manual</a> + for more about censor rules + </li> + <li> + censor rules may simply redact text that exactly matches a + particular sentence or phrase, or may use + <a href="regexp">regular expressions</a> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="development">development site</a> (also: dev, development server) + </dt> + <dd> + A <strong>dev server</strong> is one that is running your Alaveteli site + 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 + users actually visit running with live data, or a + <a href="#staging" class="glossary">staging server</a>, + which is used for testing code before it goes live. + <p> + On your dev server, you should set + <code><a href="{{site.baseurl}}docs/customising/config/#staging_site">STAGING_SITE</a></code> + to <code>1</code>. + </p> + </dd> + + <dt> + <a name="foi">Freedom of Information</a> (also FOI) + </dt> + <dd> + <strong>Freedom of information</strong> laws allow access by the general public + to data held by national governments. They establish a "right-to-know" + legal process by which requests may be made for government-held + information, to be received freely or at minimal cost, barring standard + exceptions. + <br> + <em>[from wikipedia]</em> + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + Wikipedia summary of <a href="http://http://en.wikipedia.org/wiki/Freedom_of_information_laws_by_country">FOI laws by country</a>. + </li> + </ul> + </div> + </dd> + + <dt> + <a name="git">git</a> (also github, git repository, and git repo) + </dt> + <dd> + We use a popular source code control system called <strong>git</strong>. This + helps us track changes to the code, and also makes it easy for other people + to duplicate and even contribute to our software. + <p> + The website <a href="http://github.com/mysociety">github.com</a> is a central, public + place where we make our software available. Because it's Open Source, you can + inspect the code there (Alaveteli is mostly written in the programming language + Ruby), report bugs, suggest features and many other useful things. + </p> + <p> + The entire set of files that form the Alaveteli platform is called the + <strong>git repository</strong> or <strong>repo</strong>. When you + install Alaveteli, you are effectively cloning our repository on your + own machine. + </p> + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + See the <a href="{{ site.baseurl }}docs/installing">installation instructions</a> which will + clone the Alaveteli repo. + </li> + <li> + Everything about git from the <a + href="//http://git-scm.com">official website</a>. + </li> + <li> + See <a href="http://github.com/mysociety">the mySociety projects on + github</a>. + </li> + </ul> + </div> + </dd> + + <dt> + <a name="holding pen">holding pen</a> + </dt> + <dd> + The <strong>holding pen</strong> is the conceptual place where responses that + could not be delivered are held. They need attention from a administrator. + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + see the <a href="{{ site.baseurl }}docs/running/admin_manual">admin manual</a> for + information on dealing with emails in the holding pen + </li> + </ul> + </div> + </dd> + + <dt> + <a name="mta">MTA</a> (Mail Transfer Agent) + </dt> + <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. + All this email goes through the MTA, which is a seperate service on your system. + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + see these instructions for <a href="{{ site.baseurl }}docs/installing/email">configuring your MTA</a> + (examples are for exim4 and postfix, two of the most common) + </li> + </ul> + </div> + </dd> + + <dt> + <a name="production">production site</a> (also: live, production server) + </dt> + <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 + 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 + 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 + 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 + deployed, the <code>rails_env.rb</code> file that enables Rails's production + mode won't be created until you run <code>rails-post-deploy</code>. + <p> + If you have a staging server, the system environment of your staging and + production servers should be identical. + </p> + <p> + You should never need to edit code directly on your production server. + We strongly recommend you use Alaveteli's + <a href="{{ site.baseurl }}docs/installing/deploy/">deployment mechanism</a> + (using Capistrano) to make changes to your production site. + </p> + </dd> + + <dt> + <a name="publish">publish</a> + </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. + 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 + information provided in response. + </dd> + + <dt> + <a name="response">response</a> + </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>. + </dd> + + <dt> + <a name="recaptcha">recaptcha</a> + </dt> + <dd> + <strong>Recaptcha</strong> is a mechanism that deters non-human users, + such as automated bots, from submitting requests automatically. + It requires the (human) user to identify a pattern of letters presented + in an image, which is difficult or impossible for a non-human to + do. Alaveteli uses this to prevent incoming spam. + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + use the config settings + <code><a href="{{site.baseurl}}docs/customising/config/#recaptcha_public_key">RECAPTCHA_PUBLIC_KEY</a></code> + and + <code><a href="{{site.baseurl}}docs/customising/config/#recaptcha_private_key">RECAPTCHA_PRIVATE_KEY</a></code> + to set this up. + </li> + <li> + see the <a href="http://www.google.com/recaptcha/">recaptcha website</a> for more details + </li> + </ul> + </div> + </dd> + + <dt> + <a name="redact">redacting</a> (also: redaction) + </dt> + <dd> + <strong>Redacting</strong> means removing or hiding part of a message so it + cannot be read: you are effectively removing part of a document from + your site. + <p> + This may be necessary for a variety of reasons. For example, a user may + accidentally put personal information into their request, or an + authority may include it in their response. You may also need to + redact parts of requests or responses that are libellous or legally + sensitive. + </p> + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + see the + <a href="{{ site.baseurl }}docs/running/admin_manual/">admin manual</a> + for more about how and when you may need to redact information + </li> + <li> + you can do text-only redaction with Alaveteli's + <a href="#censor-rule" class="glossary">censor rules</a> + </li> + <li> + some things are easier to redact than others — especially in PDFs, + things like signatures or images can be difficult to partially remove. + In such cases, you may need to remove the document entirely. + </li> + </ul> + </div> + </dd> + + <dt> + <a name="regexp">regular expression</a> (also: regexp) + </dt> + <dd> + 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 + phrase, you can describe a whole range of <em>similar</em> phrases with one + single regular expression. + <p> + Regular expressions can be complicated, but also powerful. If you're not + familiar with using them, it's easy to make mistakes. Be careful! + </p> + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + for example, the regular expression + <code>Jo(e|ey|seph)\s+Blogg?s</code> would match names + including + "<code>Joe Bloggs</code>", "<code>Joey Bloggs</code>" and + "<code>Joseph Blogs</code>", but not + "<code>John Bloggs</code>". + </li> + <li> + see <a href="http://en.wikibooks.org/wiki/Regular_Expressions"><em>Regular + Expressions</em> on wikibooks</a> for more information + </li> + </div> + </dd> + + <dt> + <a name="request">request</a> + </dt> + <dd> + In Alaveteli, a <strong>request</strong> is the + <a href="#foi" class="glossary">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> + to all the requests it sends. + </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 }}docs/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 }}docs/customising/themes/#changing-the-colour-scheme">changing + your colour scheme</a>, which uses Sass + </li> + </ul> + </div> + </dd> + + <dt> + <a name="staging">staging server</a> (also: staging site) + </dt> + <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 + make everything work, or the + <a href="#production" class="glossary">production server</a>, which is the + site your users visit running with live data. + <p> + On your staging server, you should set + <code><a href="{{site.baseurl}}docs/customising/config/#staging_site">STAGING_SITE</a></code> + to <code>1</code>. + </p> + <p> + If you have a staging server, the system environment of your staging and + production servers should be identical. + </p> + <p> + You should never need to edit code directly on your production or staging servers. + We strongly recommend you use Alaveteli's + <a href="{{ site.baseurl }}docs/installing/deploy/">deployment mechanism</a> + (using Capistrano) to make changes to these sites. + </p> + </dd> + + <dt> + <a name="state">state</a> + </dt> + <dd> + Each <a href="#request" class="glossary">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>. + </p> + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + <a href="{{ site.baseurl }}docs/running/states">example states for WhatDoTheyKnow</a> + (Alaveteli site running in the UK) + </li> + <li> + for comparison, <a href="{{ site.baseurl }}docs/running/states_informatazyrtare">example states for InformataZyrtare</a> + (Alaveteli site running in Kosovo) + </li> + <li> + to customise or add your own states, see <a href="{{ site.baseurl }}docs/customising/themes">Customising the request states</a> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="theme">theme</a> + </dt> + <dd> + A <strong>theme</strong> is the collection of changes to the templates + and the code that causes the site to look or behave differently from the + default. Typically you'll need a theme to make Alaveteli show your own + brand. + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + <a href="{{ site.baseurl }}docs/customising +/themes">about themes</a> + </li> + </ul> + </div> + </dd> + +</dl> diff --git a/docs/installing/ami.md b/docs/installing/ami.md new file mode 100644 index 000000000..42f2907cb --- /dev/null +++ b/docs/installing/ami.md @@ -0,0 +1,59 @@ +--- +layout: page +title: Installing the easy way +--- + +# Installation on Amazon EC2 + +<p class="lead"> + We've made an Amazon Machine Image (AMI) so you can quickly deploy on Amazon EC2. This is handy if you just want to evaluate Alaveteli, for example. +</p> + +Note that there are [other ways to install Alaveteli]({{ site.baseurl }}docs/installing). + +## 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. + +Unfortunately, Alaveteli will not run properly on a free Micro +instance due to the low amount of memory available on those +instances; you will need to use at least a Small instance, which +Amazon will charge for. + +The AMI can be found in the EU West (Ireland) region, with the ID ami-8603f4f1 +and name “Basic Alaveteli installation 2014-01-29”. You can launch an instance +based on that AMI with [this +link](https://console.aws.amazon.com/ec2/home?region=eu-west-1#launchAmi=ami-8603f4f1). + +When you create an EC2 instance based on that AMI, make sure that you choose +Security Groups that allows at least inbound HTTP, HTTPS, SSH and, if you want +to test incoming mail as well, SMTP. + +When your EC2 instance is launched, you will be able to log in as the `ubuntu` +user. This user can `sudo` freely to run commands as root. However, the code is +actually owned by (and runs as) the `alaveteli` user. After creating the +instance, you may want to edit a configuration file to customize the site's +configuration. That configuration file is +`/var/www/alaveteli/alaveteli/config/general.yml`, which can be edited with: + + ubuntu@ip-10-58-191-98:~$ sudo su - alaveteli + alaveteli@ip-10-58-191-98:~$ cd alaveteli + alaveteli@ip-10-58-191-98:~/alaveteli$ nano config/general.yml + +Then you should restart the Thin webserver with: + + alaveteli@ip-10-58-191-98:~/alaveteli$ logout + ubuntu@ip-10-58-191-98:~$ sudo /etc/init.d/alaveteli restart + +If you find the hostname of your EC2 instance from the AWS console, you should +then be able to see the site at +`http://your-ec2-hostname.eu-west-1.compute.amazonaws.com` + +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/deploy.md b/docs/installing/deploy.md new file mode 100644 index 000000000..5378b89d6 --- /dev/null +++ b/docs/installing/deploy.md @@ -0,0 +1,167 @@ +--- +layout: page +title: Deploying +--- + +# Deploying 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, + especially on your <a href="{{ site.baseurl }}docs/glossary/#production">production server</a>. + Alaveteli provides a deployment mechanism using Capistrano. +</p> + +## Why deploy? + +Although you can [install Alaveteli]({{ site.baseurl }}docs/installing/) in a number +of ways, once you're running, sooner or later you'll need to make changes to +the site. A common example is updating your site when we issue a new release. + +The deployment mechanism takes care of putting all the right files into the +right place, so when you need to put changes live, there's no risk of you +forgetting the update all the files you've changed, or breaking the +configuration by accident. Instead, deployment does all this for you +automatically. It's also more efficient because it is faster than making +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. + +## Capistrano + +<a href="{{site.baseurl}}docs/glossary/#capistrano" class="glossary">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]` +commands on your local machine, and Capistrano connects to your server (using +`ssh`) and does the corresponding task there for you. + +### Set up + +Capistrano requires things to be set up at both ends -- that is, on the server +where you want Alaveteli to run, and on your own local machine. + +* *the server* is the machine that will be running the Alaveteli + instance you're deploying + +* your *local machine* may be your laptop or similar device -- as well as those + belonging to anyone in your team whom you want to be able to deploy + +In order to allow the Capistrano deployment mechanism work, you need to set up +the server so that the Alaveteli app is being served from a directory called +`current`. Once you've done that, deploying a new version is essentially +creating a timestamped sister directory to the `current` directory, and +switching the symlink `current` from the old timestamped directory to the new +one. Things that need to persist between deployments, like config files, are +kept in a `shared` directory that is at the same level, and symlinked-to from +each timestamped deploy directory. + +We're [working on making this easier](https://github.com/mysociety/alaveteli/issues/1596), +but for now, here's the manual process you need to follow to set up this +deployment mechanism. Remember, you only have to do this once to set it up, +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 + directory (temporarily, your site will be missing, until the deployment puts + new files in place) + +Next, on your local machine: + +* install Capistrano: + * Capistrano requires Ruby 1.9 or more, and can be installed using rubygems + * do: `gem install capistrano` +* install Bundler if you don't have it already -- do: `gem install bundler` +* checkout the [Alaveteli repo](http://github.com/mysociety/alaveteli/) (you + 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`. +* `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 + +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 + Capistrano just created on the server: + * `general.yml` + * `database.yml` + * `rails_env.rb` + * `newrelic.yml` + * `aliases` ← if you're using Exim as your MTA +* if you're using Exim as your MTA, edit the `aliases` file you just copied across + so that the path to Alaveteli includes the `current` element. If it was + `/var/www/alaveteli/alaveteli/script/mailin`, it should now be + `/var/www/alaveteli/alaveteli/current/script/mailin`. +* copy the following directories from your temporary copy of Alaveteli to the + `shared` directory created by Capistrano on the server: + * `cache/` + * `files/` + +Now, back on your local machine: + +* make sure you're still in the Alaveteli repo (if not, `cd` back into it) +* 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> +* 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`. +* 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`. +* Update the MTA config to include the `current` element in the paths it uses. + If you installed using the installation script, the MTA will be postfix, + and you will need to edit `/etc/postfix/master.cf` to replace + `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. + +Phew, you're done! + +You can delete the temporary copy of Alaveteli (perhaps in your +home directory) now. + +### Usage + +Before you issue any Capistrano commands, `cd` into the checkout of the +Alaveteli repo on your local machine (because that's where it will look +for the config that you've set up). + +Ensure you've got a `config/deploy.yml` file with the correct settings for your +site. If there are other people in your team who need to deploy, you'll need to +share it with them too -- it might be a good idea to keep the latest +version in a [Gist](http://gist.github.com/). + +* to deploy to staging, just run `cap deploy` +* to deploy to production, run `cap -S stage=production deploy` + +You might notice that, after deploying, the old deploy directory is still there +-- that is, the one that was `current` until you replaced it with the new one. +By default, the deploy mechanism keeps the last five deployments there. Run +`cap deploy:cleanup` to tidy up older versions. + +For additional usage instructions, see the [Capistrano +website](http://capistranorb.com/). + +### Whoops, that's not what I expected + +If a deployment goes wrong, or you discover after doing it that you're not +ready for the latest version after all, don't panic! Run `cap deploy:rollback` +and it will switch `current` back to the previous deployment. + diff --git a/docs/installing/email.md b/docs/installing/email.md new file mode 100644 index 000000000..98dff0087 --- /dev/null +++ b/docs/installing/email.md @@ -0,0 +1,213 @@ +--- +layout: page +title: Installing MTA +--- + +# Installing the MTA + +<p class="lead"> + 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 }}docs/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 }}docs/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 }}docs/customising/config/#mta_log_path) and +[`MTA_LOG_TYPE`]({{ site.baseurl }}docs/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 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 + +We suggest you add the following to your exim configuration. + +In `/etc/exim4/conf.d/main/04_alaveteli_options`, set: + + ALAVETELI_HOME=/path/to/alaveteli/software + ALAVETELI_USER=www-data + log_file_path=/var/log/exim4/exim-%slog-%D + MAIN_LOG_SELECTOR==+all -retry_defer + extract_addresses_remove_arguments=false + +The user ALAVETELI_USER should have write permissions on ALAVETELI_HOME. + +The name and location of the log files created by Exim must match what the +`load-mail-server-logs` script expects, which is why you must provide the +`log_file_path` setting. + +The `check-recent-requests-sent` scripts expects the logs to contain the +`from=<...>` envelope information, so we make the logs more verbose with +`log_selector`. The ALAVETELI_USER may need to also need to be added to the +`trusted_users` list in your Exim config in order to set the return path on +outgoing mail, depending on your setup. + +In `/etc/exim4/conf.d/router/04_alaveteli`: + + alaveteli_request: + debug_print = "R: alaveteli for $local_part@$domain" + driver = redirect + data = ${lookup{$local_part}wildlsearch{ALAVETELI_HOME/config/aliases}} + pipe_transport = alaveteli_mailin_transport + +In `/etc/exim4/conf.d/transport/04_alaveteli`: + + alaveteli_mailin_transport: + driver = pipe + command = $address_pipe ${lc:$local_part} + current_directory = ALAVETELI_HOME + home_directory = ALAVETELI_HOME + user = ALAVETELI_USER + group = ALAVETELI_USER + +And, assuming you set +[`INCOMING_EMAIL_PREFIX`]({{ site.baseurl }}docs/customising/config/#incoming_email_prefix) +in your config at `config/general.yml` to "foi+", create `config/aliases` with the following +content: + + ^foi\\+.*: |/path/to/alaveteli/software/script/mailin + +You should also configure exim to discard any messages sent to the +[`BLACKHOLE_PREFIX`]({{ site.baseurl }}docs/customising/config/#blackhole_prefix) +address, whose default value is +`do-not-reply-to-this-address`. For example, add the following to +`config/aliases`: + + # 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 +[`TRACK_SENDER_EMAIL`]({{ site.baseurl }}docs/customising/config/#track_sender_email) +address to be filtered through +`script/handle-mail-replies`. Messages that are not bounces or +out-of-office autoreplies will be forwarded to +[`FORWARD_NONBOUNCE_RESPONSES_TO`]({{ site.baseurl }}docs/customising/config/#forward_nonbounce_responses_to). +For example, in WhatDoTheyKnow the +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'` + +Finally, make sure you have `dc_use_split_config='true'` in +`/etc/exim4/update-exim4.conf.conf`, and execute the command +`update-exim4.conf`. + +Note that if the file `/etc/exim4/exim4.conf` exists then `update-exim4.conf` +will silently do nothing. Some distributions include this file. If +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>'`). + +### Troubleshooting (exim) + +To test mail delivery, run: + + exim -bt foi+request-1234@localhost + +This should tell you which routers are being processed. You should +see something like: + + $ exim -bt foi+request-1234@localhost + R: alaveteli pipe for snafflerequest-234@localhost + snafflerequest-234@localhost -> |/home/alaveteli/alaveteli/script/mailin + transport = alaveteli_mailin_transport + +This tells you that the routing part (making emails to +`foi\+.*@localhost` be forwarded to Alaveteli's `mailin` script) is +working. + +There is a great +[Exim Cheatsheet](http://bradthemad.org/tech/notes/exim_cheatsheet.php) +online that you may find useful. diff --git a/docs/installing/index.md b/docs/installing/index.md new file mode 100644 index 000000000..98efa7b8a --- /dev/null +++ b/docs/installing/index.md @@ -0,0 +1,62 @@ +--- +layout: page +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>. +</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 **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 +first. In this environment you can see debug messages, and you don't need to +worry too much about the efficiency and performance of the site (because it's +not really getting lots of traffic). + +A **production** site is different: you want your production site to run as +efficiently as possible, so things like caching are swiched on, and debug +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), +which is used solely to test new code in an identical environment to your +production site but 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 +production server. + +## Deployment + +If you're running a production server, we **strongly recommend** you +use the Capistrano [deployment mechanism]({{ site.baseurl }}docs/installing/deploy/) +that's included with Alaveteli. Set this up and you never have to edit files on +those servers, because Capistrano takes care of that for you. + +## Installing the core code + +* [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 + +If you're setting up a development server on MacOS X, we've also got +[MacOS installation instructions]({{ site.baseurl }}docs/installing/macos). + +## Other installation information + +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 }}docs/installing/email) diff --git a/docs/installing/macos.md b/docs/installing/macos.md new file mode 100644 index 000000000..6e1986d59 --- /dev/null +++ b/docs/installing/macos.md @@ -0,0 +1,155 @@ +--- +layout: page +title: Installing on MacOS X +--- + +# Installation on MacOS X + +<p class="lead"> + We don't recommend using OS X in production, but if you want to get + Alaveteli running on your Mac for development, these guidelines should + help. +</p> + +Note that there are [other ways to install Alaveteli]({{ site.baseurl }}docs/installing). + +## MacOS X 10.7 + +Follow these instructions to get Alaveteli running locally on an OS X machine. These instructions have been tested with Xcode 4.1 on OS X Lion (10.7). We do not recommend using OS X in production. + +**Note:** This guide is currently incomplete. Please help by posting issues to the [alaveteli-dev Google group](https://groups.google.com/group/alaveteli-dev) or by submitting pull requests. + +## Xcode + +If you are using OS X Lion, download *Command Line Tools for Xcode* from [Apple](https://developer.apple.com/downloads/index.action). This is a new package from Apple that provides the command-line build tools separate from the rest of Xcode. You need to register for a free Apple Developer account. + +**Note:** As of Xcode 4.2, a non-LLVM version of GCC is no longer included. Homebrew has dealt with it by [switching to Clang](https://github.com/mxcl/homebrew/issues/6852). However, you may encounter errors installing RVM. *Please report these on the [mailing list](https://groups.google.com/group/alaveteli-dev).* The following instructions have been tested with Xcode 4.1. If necessary, you can install GCC from Xcode 4.1 by running: + + brew install http://github.com/adamv/homebrew-alt/raw/master/duplicates/apple-gcc42.rb + +## Homebrew + +Homebrew is a package manager for OS X. It is preferred over alternatives such as MacPorts and Fink. If you haven't already installed Homebrew, run the command: + + ruby <(curl -fsSkL raw.github.com/mxcl/homebrew/go) + +Next, install packages required by Alaveteli: + + brew install catdoc elinks gnuplot gs imagemagick libmagic libyaml links mutt poppler tnef wkhtmltopdf wv xapian unrtf + + +### Install postgresql + +Alaveteli uses PostgreSQL by default. If you've tested Alaveteli with MySQL or SQLite, let us know in the [alaveteli-dev Google group](https://groups.google.com/group/alaveteli-dev). + + brew install postgresql + initdb /usr/local/var/postgres + mkdir -p ~/Library/LaunchAgents + cp /usr/local/Cellar/postgresql/9.0.4/org.postgresql.postgres.plist ~/Library/LaunchAgents/ + launchctl load -w ~/Library/LaunchAgents/org.postgresql.postgres.plist + +## PDF Toolkit + +[Download the installer package](https://github.com/downloads/robinhouston/pdftk/pdftk.pkg) and install. + +## Ruby + +### Install RVM + +RVM is the preferred way to install multiple Ruby versions on OS X. Alaveteli uses Ruby 1.8.7. The following commands assume you are using the Bash shell. + + curl -L https://get.rvm.io | bash -s stable + +Read `rvm notes` and `rvm requirements` carefully for further instructions. Then, install Ruby: + + rvm install 1.8.7 + rvm install 1.9.3 + rvm use 1.9.3 --default + +### Install mahoro and pg with flags + +The `mahoro` and `pg` gems require special installation commands. Rubygems must be downgraded to 1.6.2 to avoid deprecation warnings when running tests. + + rvm 1.8.7 + gem update --system 1.6.2 + gem install mahoro -- --with-ldflags="-L/usr/local/Cellar/libmagic/5.09/lib" --with-cppflags="-I/usr/local/Cellar/libmagic/5.09/include" + env ARCHFLAGS="-arch x86_64" gem install pg + +#### Update + +As of August 22, 2012 or earlier, you can install `mahoro` in Ruby 1.9.3 on OS X 10.7 Lion with: + + brew install libmagic + gem install mahoro + +## Alaveteli + +The following is mostly from [the manual installation process]({{ site.baseur l}}/installing/manual_install). + +### Configure database + +Creates Alaveteli databases and an `foi` user with password `foi`. + + echo "CREATE DATABASE foi_development encoding = 'UTF8'; + CREATE DATABASE foi_test encoding = 'UTF8'; + CREATE USER foi WITH CREATEUSER; + ALTER USER foi WITH PASSWORD 'foi'; + ALTER USER foi WITH CREATEDB; + GRANT ALL PRIVILEGES ON DATABASE foi_development TO foi; + GRANT ALL PRIVILEGES ON DATABASE foi_test TO foi; + ALTER DATABASE foi_development OWNER TO foi; + ALTER DATABASE foi_test OWNER TO foi;" | psql -h localhost template1 + +### Clone Alaveteli + +We don't want to vendor Rails, as it causes problems locally. + + git clone https://github.com/mysociety/alaveteli.git + cd alaveteli + git submodule init + + sed -i~ 's/\\[submodule "vendor\/rails"\\]//' .git/config + + sed -i~ 's/url = git:\/\/github.com\/rails\/rails.git//' .git/config + git submodule update + +**Note:** Due to Markdown bugs, the first `sed` command above does not display properly if it appears in blockquote. + +### Configure Alaveteli + +Copy the example configuration files and configure `database.yml`. + + cp -f config/general.yml-example config/general.yml + cp -f config/memcached.yml-example config/memcached.yml + cp -f config/database.yml-example config/database.yml + sed -i~ 's/<username>/foi/' config/database.yml + sed -i~ 's/<password>/foi/' config/database.yml + sed -i~ 's/ port: 5432//' config/database.yml + sed -i~ 's/ # PostgreSQL 8.1 pretty please//' config/database.yml + +### Bundler + +Install the gems and finish setting up Alaveteli. + + rvm 1.8.7 + bundle + bundle exec rake db:create:all + bundle exec rake db:migrate + bundle exec rake db:test:prepare + +## Troubleshooting + +### Ruby version + +Ensure you are using the latest versions of Ruby. For example, some versions of Ruby 1.8.7 will segmentation fault, for example: + +``` +/Users/james/.rvm/gems/ruby-1.8.7-p357/gems/json-1.5.4/ext/json/ext/json/ext/parser.bundle: [BUG] Segmentation fault +ruby 1.8.7 (2011-12-28 patchlevel 357) [i686-darwin11.3.0] +``` + +Running `rvm install 1.8.7` should install the latest Ruby 1.8.7 patch level. Remember to switch to the new Ruby version before continuing. + +### Rake tasks + +Remember to run Rake tasks with `bundle exec`. To run the tests, for example, run `bundle exec rake`. diff --git a/docs/installing/manual_install.md b/docs/installing/manual_install.md new file mode 100644 index 000000000..c9625c0c9 --- /dev/null +++ b/docs/installing/manual_install.md @@ -0,0 +1,570 @@ +--- +layout: page +title: Manual installation +--- + + +# Manual Installation + +<p class="lead"> + 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 }}docs/installing/script">installation script</a> + or the + <a href="{{ site.baseurl }}docs/installing/ami">Amazon EC2 AMI</a>. +</p> + +Note that there are [other ways to install Alaveteli]({{ site.baseurl }}docs/installing). + +## 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 +have instructions for [installing on MacOS]({{ site.baseurl }}docs/installing/macos). + +Commands are intended to be run via the terminal or over ssh. + + +## Get Alaveteli + +To start with, you may need to install git, e.g. with `sudo apt-get install +git-core` + +Next, get hold of the Alaveteli source code from github: + + git clone https://github.com/mysociety/alaveteli.git + cd alaveteli + +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): + + git checkout master + +## Install mySociety libraries + +Next, install mySociety's common ruby libraries. To fetch the contents of the +submodules, run: + + git submodule update --init + +## Install system dependencies + +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. + +Add the following repositories to `/etc/apt/sources.list`: + +**Debian Squeeze** + + cat > /etc/apt/sources.list.d/debian-backports.list <<EOF + deb http://backports.debian.org/debian-backports squeeze-backports main contrib non-free + EOF + +The repositories above let you install `wkhtmltopdf-static` and `bundler` using +`apt`. + +**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 + 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 +apt sources. + + cat > /etc/apt/sources.list.d/mysociety-debian.list <<EOF + deb http://debian.mysociety.org squeeze main + EOF + +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 - + +You should also configure package-pinning to reduce the priority of this +repository. + + 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 +dependencies manually, as follows: + +1. If you would like users to be able to get pretty PDFs as part of the +downloadable zipfile of their request history, install +[wkhtmltopdf](http://code.google.com/p/wkhtmltopdf/downloads/list). We +recommend downloading the latest, statically compiled version from the project +website, as this allows running headless (that is, without a graphical interface +running) on Linux. If you do install `wkhtmltopdf`, you need to edit a setting +in the config file to point to it (see below). If you don't install it, +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 +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 + +Refresh the sources after adding the extra repositories: + + sudo apt-get update + +Now install the packages relevant to your system: + + # Debian Squeeze + sudo apt-get install $(cat config/packages.debian-squeeze) + + # Ubuntu Precise + sudo apt-get install $(cat config/packages.ubuntu-precise) + +Some of the files also have a version number listed in config/packages - check +that you have appropriate versions installed. Some also list "`|`" and offer a +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 +process above). You could also install it as a gem: + + sudo gem install bundler + +## Configure Database + +There has been a little work done in trying to make the code work with other +databases (e.g., SQLite), but the currently supported database is PostgreSQL +("postgres"). + +If you don't have postgres installed: + + $ sudo apt-get install postgresql postgresql-client + +Create a `foi` user from the command line, like this: + + # sudo -u postgres createuser -s -P foi + +_Note:_ Leaving the password blank will cause great confusion if you're new to +PostgreSQL. + +Then create the databases: + + # sudo -u postgres createdb -T template0 -E SQL_ASCII -O foi foi_production + # sudo -u postgres createdb -T template0 -E SQL_ASCII -O foi foi_test + # sudo -u postgres createdb -T template0 -E SQL_ASCII -O foi foi_development + +We create using the ``SQL_ASCII`` encoding, because in postgres this is means +"no encoding"; and because we handle and store all kinds of data that may not +be valid UTF (for example, data originating from various broken email clients +that's not 8-bit clean), it's safer to be able to store *anything*, than reject +data at runtime. + +Now you need to set up the database config file to contain the name, username +and password of your postgres database. + +* Copy `database.yml-example` to `database.yml` in `alaveteli/config` +* Edit it to point to your local postgresql database in the development + and test sections. + +Example `development` section of `config/database.yml`: + + development: + adapter: postgresql + database: foi_development + username: foi + password: secure-password-here + host: localhost + port: 5432 + +Make sure that the user specified in `database.yml` exists, and has full +permissions on these databases. As they need the ability to turn off +constraints whilst running the tests they also need to be a superuser + +If you don't want your database user to be a superuser, you can add this line +to the test config in `database.yml` (as seen in `database.yml-example`) + + constraint_disabling: false + +## Configure email + +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 }}docs/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/](http://mailcatcher.me/) for more +details. Start mailcatcher by running `bundle exec mailcatcher` in your +application directory. + +### Minimal + +If you just want to get the tests to pass, you will at a minimum need to allow +sending emails via a `sendmail` command (a requirement met, for example, with +`sudo apt-get install exim4`). + +### Detailed + +When an authority receives an email, the email's `reply-to` field is a magic +address which is parsed and consumed by the Rails app. + +To receive such email in a production setup, you will need to configure your +MTA to pipe incoming emails to the Alaveteli script `script/mailin`. Therefore, +you will need to configure your MTA to accept emails to magic addresses, and to +pipe such emails to this script. + +Magic email addresses are of the form: + + <foi+request-3-691c8388@example.com> + +The respective parts of this address are controlled with options in +`config/general.yml`, thus: + + INCOMING_EMAIL_PREFIX = 'foi+' + INCOMING_EMAIL_DOMAIN = 'example.com' + +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 }}docs/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. + +## Set up configs + +Copy `config/general.yml-example` to `config/general.yml` and edit to your +taste. + +Note that the default settings for frontpage examples are designed to work with +the dummy data shipped with Alaveteli; once you have real data, you should +certainly edit these. + +The default theme is the "Alaveteli" theme. When you run `rails-post-deploy` +(see below), that theme gets installed automatically. + +Finally, copy `config/newrelic.yml-example` to `config/newrelic.yml`. This file +contains configuration information for the New Relic performance management +system. By default, monitoring is switched off by the `agent_enabled: false` +setting. See New Relic's [remote performance analysis](https://github.com/newrelic/rpm) instructions for switching it on +for both local and remote analysis. + + +## Deployment + +In the `alaveteli` directory, run: + + script/rails-post-deploy + +(This will need execute privs so `chmod 755` if necessary.) This sets up +directory structures, creates logs, installs/updates themes, runs database +migrations, etc. You should run it after each new software update. + +One of the things the script does is install dependencies (using `bundle +install`). Note that the first time you run it, part of the `bundle install` +that compiles `xapian-full` takes a *long* time! + +If you want some dummy data to play with, you can try loading the fixtures that +the test suite uses into your development database. You can do this with: + + script/load-sample-data + +Next, create the index for the search engine (Xapian): + + script/rebuild-xapian-index + +If this fails, the site should still mostly run, but it's a core component so +you should really try to get this working. + +## Run the Tests + +Make sure everything looks OK: + + bundle exec rake spec + +If there are failures here, something has gone wrong with the preceding steps +(see the next section for a common problem and workaround). You might be able +to move on to the next step, depending on how serious they are, but ideally you +should try to find out what's gone wrong. + +### glibc bug workaround + +There's a [bug in +glibc](http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=637239) which causes +Xapian to segfault when running the tests. Although the bug report linked to +claims it's fixed in the current Debian stable, it's not as of version +`2.11.3-2`. + +Until it's fixed (e.g. `libc6 2.13-26` does work), you can get the tests to +pass by setting `export LD_PRELOAD=/lib/libuuid.so.1`. + +## Run the Server + +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` + +The server should have told you the URL to access in your browser to see the +site in action. + +## Administrator privileges + +The administrative interface is at the URL `/admin`. + +Only users with the `super` admin level can access the admin interface. Users +create their own accounts in the usual way, and then administrators can give +them `super` privileges. + +There is an emergency user account which can be accessed via +`/admin?emergency=1`, using the credentials `ADMIN_USERNAME` and +`ADMIN_PASSWORD`, which are set in `general.yml`. To bootstrap the +first `super` level accounts, you will need to log in as the emergency +user. You can disable the emergency user account by setting `DISABLE_EMERGENCY_USER` to `true` in `general.yml`. + +Users with the superuser role also have extra privileges in the website +frontend, such as being able to categorise any request, being able to view +items that have been hidden from the search, and being presented with "admin" +links next to individual requests and comments in the front end. + +It is possible completely to override the administrator authentication by +setting `SKIP_ADMIN_AUTH` to `true` in `general.yml`. + +## 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 `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 +* `user`: the user that the software runs as +* `site`: a string to identify your alaveteli instance + +There is a rake task that will help to rewrite this file into one that is +useful to you, which can be invoked with: + + bundle exec rake config_files:convert_crontab \ + DEPLOY_USER=deploy \ + VHOST_DIR=/dir/above/alaveteli \ + VCSPATH=alaveteli \ + SITE=alaveteli \ + CRONTAB=config/crontab-example > crontab + +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. + +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. + +`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). +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): + + deploy ALL = NOPASSWD: /etc/init.d/foi-alert-tracks, /etc/init.d/foi-purge-varnish + +The cron jobs refer to a program `run-with-lockfile`. See [this +issue](https://github.com/mysociety/alaveteli/issues/112) for a discussion of +where to find this program, and how you might replace it. This [one line +script](https://gist.github.com/3741194) can install this program system-wide. + +## Set up production web server + +It is not recommended to run the website using the default Rails web server. +There are various recommendations here: http://rubyonrails.org/deploy + +We usually use Passenger / mod_rails. The file at `conf/httpd.conf-example` +gives you an example config file for WhatDoTheyKnow. At a minimum, you should +include the following in an Apache configuration file: + + PassengerResolveSymlinksInDocumentRoot on + PassengerMaxPoolSize 6 # Recommend setting this to 3 or less on servers with 512MB RAM + +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`. + +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 +domain and you will need to configure an SSL terminator to sit in front of +Varnish. If you're already using Apache as a web server you could simply use +Apache as the SSL terminator. A minimal configuration would look something like +this: + + <VirtualHost *:443> + ServerName www.yourdomain + + ProxyRequests Off + ProxyPreserveHost On + ProxyPass / http://localhost:80/ + ProxyPassReverse / http://localhost:80/ + RequestHeader set X-Forwarded-Proto 'https' + + SSLEngine on + SSLProtocol all -SSLv2 + SSLCipherSuite ALL:!ADH:!EXPORT:!SSLv2:RC4+RSA:+HIGH:+MEDIUM + + SSLCertificateFile /etc/apache2/ssl/ssl.crt + SSLCertificateKeyFile /etc/apache2/ssl/ssl.key + SSLCertificateChainFile /etc/apache2/ssl/sub.class2.server.ca.pem + SSLCACertificateFile /etc/apache2/ssl/ca.pem + SetEnvIf User-Agent ".*MSIE.*" nokeepalive ssl-unclean-shutdown + + </VirtualHost> + +Notice the line `RequestHeader` that sets the `X-Forwarded-Proto` header. This +is important. This ultimately tells Rails that it's serving a page over https +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/). + +## Upgrading Alaveteli + +The developer team policy is that the master branch in git should always +contain the latest stable release. Therefore, in production, you should usually +have your software deployed from the master branch, and an upgrade can be +simply `git pull`. + +Patch version increases (e.g. 1.2.3 → 1.2.**4**) should not require any further +action on your part. + +Minor version increases (e.g. 1.2.4 → 1.**3**.0) will usually require further +action. You should read the `CHANGES.md` document to see what's changed since +your last deployment, paying special attention to anything in the "Updgrading" +sections. + +Any upgrade may include new translations strings, i.e. new or altered messages +to the user that need translating to your locale. You should visit Transifex +and try to get your translation up to 100% on each new release. Failure to do +so means that any new words added to the Alaveteli source code will appear in +your website in English by default. If your translations didn't make it to the +latest release, you will need to download the updated `app.po` for your locale +from Transifex and save it in the `locale/` folder. + +You should always run the script `scripts/rails-post-deploy` after each +deployment. This runs any database migrations for you, plus various other +things that can be automated for deployment. + +## Troubleshooting + +* **Incoming emails aren't appearing in my Alaveteli install** + + 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]({{ site.baseurl }}docs/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 + valid "To" address for a request in your system. You can do this + through your site's admin interface, or from the command line, + like so: + + $ ./script/console + Loading development environment (Rails 2.3.14) + >> InfoRequest.find_by_url_title("why_do_you_have_such_a_fancy_dog").incoming_email + => "request-101-50929748@localhost" + + Now take the source of a valid email (there are some sample emails in + `spec/fixtures/files/`); edit the `To:` header to match this address; + and then pipe it through the mailin script. A non-zero exit code + means there was a problem. For example: + + $ cp spec/fixtures/files/incoming-request-plain.email /tmp/ + $ perl -pi -e 's/^To:.*/To: <request-101-50929748@localhost>/' /tmp/incoming-request-plain.email + $ ./script/mailin < /tmp/incoming-request-plain.email + $ echo $? + 75 + + The `mailin` script emails the details of any errors to + `CONTACT_EMAIL` (from your `general.yml` file). A common problem is + for the user that the MTA runs as not to have write access to + `files/raw_emails/`. + +* **Various tests fail with "*Your PostgreSQL connection does not support + unescape_bytea. Try upgrading to pg 0.9.0 or later.*"** + + You have an old version of `pg`, the ruby postgres driver. In + Ubuntu, for example, this is provided by the package `libdbd-pg-ruby`. + + Try upgrading your system's `pg` installation, or installing the pg + gem with `gem install pg` + +* **Some of the tests relating to mail are failing, with messages like + "*when using TMail should load an email with funny MIME settings' + FAILED*"** + + This sounds like the tests are running using the `production` + environment, rather than the `test` environment, for some reason. + +* **Non-ASCII characters are being displayed as asterisks in my incoming messages** + + We rely on `elinks` to convert HTML email to plain text. + Normally, the encoding should just work, but under some + circumstances it appears that `elinks` ignores the parameters + passed to it from Alaveteli. + + To force `elinks` always to treat input as UTF8, add the following + to `/etc/elinks/elinks.conf`: + + set document.codepage.assume = "utf-8" + set document.codepage.force_assumed = 1 + + You should also check that your locale is set up correctly. See + [this issue followup](https://github.com/mysociety/alaveteli/issues/128#issuecomment-1814845) + for further discussion. + +* **I'm seeing `rake: command not found` when running the post install script** + + The script uses `rake`. + + It may be that the binaries installed by bundler are not put in the + system `PATH`; therefore, in order to run `rake` (needed for + deployments), you may need to do something like: + + ln -s /usr/lib/ruby/gems/1.8/bin/rake /usr/local/bin/ + + + diff --git a/docs/installing/script.md b/docs/installing/script.md new file mode 100644 index 000000000..d4382c98f --- /dev/null +++ b/docs/installing/script.md @@ -0,0 +1,65 @@ +--- +layout: page +title: Installing the easy way +--- + +# Installation script + +<p class="lead"> + If you prefer to use your own server, we've provided an installation script which does most of the work for you. +</p> + +Note that there are [other ways to install Alaveteli]({{ site.baseurl }}docs/installing). + +## Installing with the installation script + +If you have a clean installation of Debian squeeze 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. + +**Warning: only use this script on a newly installed server – it will make +significant changes to your server’s setup, including modifying your nginx +setup, creating a user account, creating a database, installing new packages +etc.** + +To download the script, run the following command: + + curl -O https://raw.github.com/mysociety/commonlib/master/bin/install-site.sh + +If you run this script with `sh install-site.sh`, you'll see its usage message: + + Usage: ./install-site.sh [--default] <SITE-NAME> <UNIX-USER> [HOST] + HOST is only optional if you are running this on an EC2 instance. + --default means to install as the default site for this server, + rather than a virtualhost for HOST. + +In this case `<SITE-NAME>` should be `alaveteli`. `<UNIX-USER>` is the name of +the Unix user that you want to own and run the code. (This user will be created +by the script.) + +The `HOST` parameter is a hostname for the server that will be usable +externally – a virtualhost for this name will be created by the script, unless +you specified the `--default` option. This parameter is optional if you are on +an EC2 instance, in which case the hostname of that instance will be used. + +For example, if you wish to use a new user called `alaveteli` and the hostname +`alaveteli.127.0.0.1.xip.io`, creating a virtualhost just for that hostname, +you could download and run the script with: + + sudo sh install-site.sh alaveteli alaveteli alaveteli.127.0.0.1.xip.io + +([xip.io](http://xip.io/) is a helpful domain for development.) + +Or, if you want to set this up as the default site on an EC2 instance, you +could download the script, make it executable and then invoke it with: + + sudo ./install-site.sh --default alaveteli alaveteli + +When the script has finished, you should have a working copy of the website, +accessible via the hostname you supplied to the script. + +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/running/admin_manual.md b/docs/running/admin_manual.md new file mode 100644 index 000000000..bd3a44855 --- /dev/null +++ b/docs/running/admin_manual.md @@ -0,0 +1,301 @@ +--- +layout: page +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="http://www.whatdotheyknow.com">whatdotheyknow.com</a>. +</p> + +## What's involved? + +The overhead in managing a successful FOI website is quite high. Richard, a +volunteer, wrote a [blog +post](http://www.mysociety.org/2009/10/13/behind-whatdotheyknow/) about some of +this in 2009. + +WhatDoTheyKnow usually has about 3 active volunteers at any one time managing +the support, plus a few other less active people who help out at different +times. + +Administration tasks can be split into **maintenance** and **user support**. +The boundaries of these tasks is in fact quite blurred; the main distinction is +that the former happen exclusively through the web admin interface, whereas the +latter are mediated by email directly with end users (but often result in +actions through the web admin interface). + +In one randomly chosen week in December 2010, the support team acted on 66 +different events, comprising 44 user **support** emails and 22 **maintenance** +tasks. + +Most of the support emails require some time to investigate; some (e.g. those +with legal implications) require quite a lot of policy discussion and debate in +order to address them. Maintenance tasks tend to be much more straightforward +to address, although sometimes they need expert knowledge (e.g. about mail +server bounce messages). + +During that week, the tasks broke down as follows: + +### Regular maintenance tasks + +* 18 misdelivered / undelivered responses (a.k.a. the "Holding Pen") +* 4 requests that are unclassified 21 days after response needing classification +* 2 requests that have been marked as needing admin attention +* 2 things marked as errors (message refused by server - spam, full mailbox, etc) to fix + +### User interaction tasks + +* 16 general, daily admin: i.e. things that resulted in admin actions on the + site (bounces, misdelivered responses, etc) +* 14 items wrongly addressed (i.e. to the support team rather than an authority) +* 6 users needed support using the website (problems finding authorities, or authorities having problems following up) +* 4 users wanted advice about FOI or data protection +* 3 requests to redact personal information +* 2 requests to redact defamatory information + +## Types of user interaction + +There follows a breakdown of the most common kinds of user interaction. It's +intended for use as a guide to the kind of policies and training that a support +team might need to develop. + +### Dealing with email that's not getting through to the authority + +Emails may not get through to the authority in the first place for a few +reasons: + +* The recipient's domain has marked the email as spam and not sent it on +* It's gone into the recipient's spam folder due to their own mail client setup +* The recipient has a mail filter configured in their client that otherwise skips their inbox + +The first reason is the most common. The solution is to send a standard email +to the recipient's IT department to whitelist email from your service (and of +course send a message to the original recipient about this). The Alaveteli +admin interface also has an option to "resend" any particular message. + +An Alaveteli administrator will typically only become aware of this when a +request has become very overdue without any correspondence at all from the +authority. Sometimes the authority's mail server will bounce the email, in +which case it appears in the administrative interface as "needs admin +attention". + +### Requests to take down information + +#### Legal action + +This is where someone tells us that information on the site might be subject to +legal action. The scenario will vary wildly across different legal +jurisdictions. In the UK, this kind of request is most likely to be related to +defamation. + +##### Action + +* Get the notification by email to a central support email address, so there is + a written record +* Act according to standard legal advice (e.g. you may need to temporarily take + down requests while you debate it, even if you think they should stay up; or + you may be able to redact them temporarily rather than take them down) +* Centrally log the entire conversation and the actions you have taken +* Get further legal advice where necessary. For example, you may get a risk + assessment that suggests you can republish the request, or show it with + limited redactions. + +#### Copyright / Commercial + +Public authorities who have not quite understood that their responses are +public sometimes don't like this, and claim copyright. Occasionally other +copyright assertions are made about content, but this is the most common one. +"Commercially sensitive" data might also be considered private information. + +##### Action + +* In the case of threatened legal action, see above. +* Otherwise, in the first instance, treat this as an advocacy case, on the + basis that FOI requests can be made repeatedly by anyone, the data should be + public anyway, and publishing it should actually save the authority money. + +##### Example email to authority + +> As I'm sure you know, our Freedom of Information law is "applicant blind", +> so anyone in the world can request the same document and get a copy of it. +> To save tax payers' money by preventing duplicate requests, and for good +> public relations, we'd advise you not to ask us to take down the +> information or to apply for a license. I would also note that +> <authority_name> has allowed re-use of FOI responses through our +> website since last year, without any trouble. + + +#### Personal data + +This includes everything from inadvertently revealed personal data such as +personally identifying information about benefits claimants to the name of a +user of the site who later develops "Google remorse". + +##### Action + +* Assess request, with reference to local Data Protection laws. Don't + automatically presume in favour of taking something down, but weighing the + nuisance/harm caused to the individual which would be relieved by taking the + material down against the public interest in publishing / continuing to + publish the material. "Sensitive" personal data will typically require a + much higher level of public interest. +* [WhatDoTheyKnow considers](http://www.whatdotheyknow.com/help/privacy#takedown) there to be a + strong public interest in retaining the names of officers or servants of + public authorities +* For users who want their name removed entirely from the site, in the first + instance, try to persuade them not to do so: +* Find out why they want their name removing +* Explain that the site is a permanent archive, and it's hard to remove things + from the Internet once posted +* Find examples of valuable requests they've made, to show why we want to keep + it +* Explain technical difficulties of removal (if relevant) +* With persistent requests, consider changing their account name to abbreviate + their first name to an initial, as this won't confuse existing requests too + much. Where there are grounds of personal safety, name should be removed and + replaced with suitable redaction text. +* Where redaction is hard (e.g. removing a scanned signature from a PDF, ask + them to resend their response with redaction in place. This has a benefit of + training them not to do this in the future, which is a good thing. +* Where redactions take place, it is advisable to add an annotation to the + request + + +### Incorrectly addressed + +Emails that arrive at the support team address, but shouldn't have. Two main types: + +* Users who think the site is a place to contact agencies directly (e.g. people + going though immigration and asylum processes who want to contact the UK + Borders Agency) +* Users who email the support email address rather than using the online form; + usually because they've replied to a system email rather than followed the + link in the message + +#### Action + +Respond to user and point them in the right direction. + +##### Example message: + +> I like to know some information about my EEA2 application which i applied on +> july 2010.i do not get any response yet ...please let me know what i will do. + +##### Example response: + +> You have written to the team responsible for the WhatDoTheyKnow.com website; +> we only run that website and are not part of the UK Government. +> +> As you are asking about your own personal circumstances you need to contact +> the UKBA directly; their contact information is available at: +> +> http://www.bia.homeoffice.gov.uk/contact/contactspage/ +> http://www.ukba.homeoffice.gov.uk/contact/contactspage/contactcentres/ +> +> You might also want to consider contacting your local MP. You could ask your +> local council or the Citizens Advice Bureau if there is an immigration advice +> centre where you are. + +##### Example message: + +> is the greenwaste collection paying for its self? .i suspect due to +> the low numbers of residents taking up the scheme, what is the true +> cost of these collections? is the scheme liable to be scrapped ? + +##### Example response: + +> You've written to the team responsible for the website WhatDoTheyKnow.com +> and not <authority_name> +> +> If you want to make a freedom of information request to them you can do so, +> in public, via our site. To get started click "make a new freedom of +> information request" at: +> +> http://www.whatdotheyknow.com/body/<authority_name> + +### Wants advice + +Two common examples are: + +* A user isn't sure where to direct their request +* Wants to know the best way to ask an authority for all the personal data they + hold about themselves + +##### Example request: + +> I would like to know at this stage under the freedom act can ask +> directly to UK embassies or high commission abroad to disclose some +> information. or I have to contact FCO through this website. + +##### Example response: + +> I would suggest making your request to the FCO as they are they body +> technically subject to the Freedom of Information Act. +> +> When you make your request it will be sent to the FCO's central FOI team they +> will then co-ordinate the response with the relevant parts of their +> organisation. + + +### General assistance required + +Can be for many reasons, e.g. + +* They had withdrawn their request, and an authority had subsequently + replied, marking the request as open again. +* Suggested corrections to authority names / details from users or authorities + themselves +* A reply has been automatically filed under the wrong request + +## Vexatious users + +Some users persistently misuse the website. An alaveteli site should have a +policy on banning users, for example giving them a first warning, informing +them about moderation policy, etc. + +## Mail import errors + +These are currently occurring at a rate of about two a month. Sometimes the +root cause seems to be blocking in the database when two mails are received for +the same request at about the same time, sometimes it just seems to be IO +timeout if the server is busy. When a mail import error occurs, the mail +handler (Exim) is sent an exit code of 75 and so should try to deliver the mail +again. A mail is sent to the support address for the site, indicating that an +error occurred, with the error and the incoming mail as attachments. Usually +Exim will redeliver the mail to the application. On the rare occasion it +doesn't, you can import it manually, by putting the raw mail (as attached to +the error sent to the site support address) in a file without the first "From" +line, and piping the contents of that file into the mail handling script. e.g. +```cat missing_mail.txt | script/mailin``` + +## Censor rules + +Censor rules can be attached to a request or to a user and define bits of text +to be removed (either from the request (and all associated files e.g. incoming +message attachments) or from all requests associated with a user), and some +replacement text. In binary files, the replacement text will always be a series +of 'x' characters identical in length to the text replaced, in order to +preserve file length. The attachment censoring does not work consistently, as +it is difficult to write rules that will match the exact contents of the +underlying file, so always check the results. Make sure to also add censor +rules for the real text and check the "View as HTML" option; this is currently +(Sept 2013) generated from the uncensored PDF or other binary file. + +You can make a censor rule apply as a [regular +expression](http://en.wikipedia.org/wiki/Regular_expression) by checking the +"Is it regexp replacement?" checkbox in the admin interface for censor rules. +Otherwise it will literally just replace any occurrences of the text entered. +Like regular text-based censor rules, regular expression based rules will be +run over binary files related to the request too, so a regular expression that +is quite loose in what it matches may have unexpected consequences if it also +matches the underlying sequence of characters in a binary file. Also, complex +or loose regular expressions can be very expensive to run (in some cases +hanging the application altogether), so please: + +* Restrict your use of them to cases that can't otherwise be easily covered. +* Keep them as simple and specific as possible. + + + diff --git a/docs/running/index.md b/docs/running/index.md new file mode 100644 index 000000000..3db94f713 --- /dev/null +++ b/docs/running/index.md @@ -0,0 +1,28 @@ +--- +layout: page +title: Running +--- + +# Running Alaveteli + + +<p class="lead"> + Keeping your Alaveteli site up and running requires some ongoing effort. +</p> + +Alaveteli is not just software. To run a successful +<a href="{{ site.baseurl }}docs/glossary/#foi" class="glossary">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. + +* the [administrator's guide]({{ site.baseurl }}docs/running/admin_manual) describes + what you need to do and know to run your site + +* we've prepared a checklist of + [things to consider]({{ site.baseurl }}docs/running/server) + when setting up your production server + +* see the [different states a request can be in]({{ site.baseurl }}docs/running/states) + + diff --git a/docs/running/server.md b/docs/running/server.md new file mode 100644 index 000000000..63ec1800f --- /dev/null +++ b/docs/running/server.md @@ -0,0 +1,122 @@ +--- +layout: page +title: Production server best practices +--- + +# Production server best practices + +<p class="lead"> + These notes serve as a checklist of things to consider when you're ready + to deploy your Alaveteli site to production. +</p> + + +## Hosting options + +Your production server must be reliable and secure. If you don't run your own +servers already, consider one of these options: + +* Cloud Server +* Virtual Private Server + +In some cases, we can host new Alaveteli projects — if you need help, +ask us about hosting. + +## Cron jobs + +Don't forget to set up the cron jobs as outlined in the +[installation instructions]({{ site.baseurl }}docs/installing/manual_install). +As of October 2011, they rely on a small program created by mySociety called +`run-with-lockfile`. A discussion of where the source for this can be found, +and possible alternatives, lives in +[Alaveteli issue #112](https://github.com/mysociety/alaveteli/issues/112). + +## Webserver configuration + +We recommend running your site behind +[Apache](https://httpd.apache.org) + +[Passenger](https://www.phusionpassenger.com). Refer to the +[installation instructions]({{ site.baseurl }}docs/installing/manual_install) +regarding `PassengerMaxPoolSize`, which you should +experiment with to match your available RAM. It is very unlikely that you'll +ever need a pool larger than [Passenger's +default](http://www.modrails.com/documentation/Users%20guide%20Apache.html#_passengermaxpoolsize_lt_integer_gt) of 6. + +We recommend you run your server behind an HTTP accelerator like +[Varnish](https://www.varnish-cache.org). +Alaveteli ships with a +[sample varnish VCL](https://github.com/mysociety/alaveteli/blob/master/config/varnish-alaveteli.vcl). + +## Security + +You _must_ change all key-related [config settings]({{ site.baseurl }}docs/customising/config) +in `general.yml` from their default values. This includes (but may not be limited to!) +these settings: + +* [`INCOMING_EMAIL_SECRET`]({{ site.baseurl }}docs/customising/config/#incoming_email_secret) +* [`ADMIN_USERNAME`]({{ site.baseurl }}docs/customising/config/#admin_username) +* [`ADMIN_PASSWORD`]({{ site.baseurl }}docs/customising/config/#admin_password) +* [`COOKIE_STORE_SESSION_SECRET`]({{ site.baseurl }}docs/customising/config/#cookie_store_session_secret) +* [`RECAPTCHA_PUBLIC_KEY`]({{ site.baseurl }}docs/customising/config/#recaptcha_public_key) +* [`RECAPTCHA_PRIVATE_KEY`]({{ site.baseurl }}docs/customising/config/#recaptcha_private_key) + +You should consider running the admin part of the site over HTTPS. This can be +achieved with rewrite rules that redirect URLs beginning with `/admin`. + +## Email configuration + +See the [configuration for exim or postfix]({{ site.baseurl }}docs/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 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 +deliverability of your email: + +* Set up [SPF records](http://www.openspf.org/) for your domain +* Set up <a + href="http://en.wikipedia.org/wiki/Feedback_loop_(email)#Feedback_loop_links_f + or_some_email_providers">feedback loops</a> with the main email providers + (Hotmail and Yahoo! are recommended) +* Especially if deploying from Amazon EC2, use an external SMTP relay for + sending outgoing mail. See [Alaveteli EC2 AMI]( {{ site.baseurl }}docs/installing/ami) + for more suggestions. + +## Backup + +Most of the data for the site lives in the production database. The exception +is the raw incoming email data, which is stored on the filesystem, as specified +in the setting +[`RAW_EMAILS_LOCATION`]({{ site.baseurl }}docs/customising/config/#raw_emails_location) +setting in `config/general.yml`. + +Refer to the [Postgres +documentation](http://www.postgresql.org/docs/8.4/static/backup.html) for +database backup strategies. The most common method is to use `pg_dump` to +create a SQL dump of the database, and backup a zipped copy of this. + +Raw emails would be best backed up using an incremental strategy. +[Rsync](http://rsync.samba.org/) is one way of doing this. + +Another belt-and-braces backup strategy is to set up your MTA to copy all +incoming and outgoing mail to a backup mailbox. One way of doing this with exim +is to put the following in your exim config: + + system_filter = ALAVETELI_HOME/config/exim.filter + system_filter_user = ALAVETELI_USER + +And then create a filter file at `ALAVETELI_HOME/config/exim.filter`, with +something like: + + if error_message then finish endif + if $header_to: contains "mydomain.org" + then + unseen deliver "backup@mybackupdomain.org" + endif + + if $sender_address: contains "mydomain.org" + then + unseen deliver "backup@mybackupdomain.org" + endif + diff --git a/docs/running/states.md b/docs/running/states.md new file mode 100644 index 000000000..73e49eba7 --- /dev/null +++ b/docs/running/states.md @@ -0,0 +1,217 @@ +--- +layout: page +title: States of requests +--- + +# Request states + +<p class="lead"> + A <a href="{{site.baseurl}}docs/glossary/#request" class="glossary">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 +customise them, you can — see +<a href="{{ site.baseurl }}docs/customising/themes">Customising the request states</a> for details. + +## WhatDoTheyKnow example + +Requests made on the UK's Alaveteli instance, [WhatDoTheyKnow](http://www.whatdotheyknow.com), +may be in any of the states described below. + +Note that your site doesn't need to use the same states as WhatDoTheyKnow does. For example, +Kosovo's instance uses slightly different states: see +[this comparison of their differences]({{ site.baseurl }}docs/running/states_informatazyrtare). + +### States + +<ul class="definitions"> + <li><a href="#waiting_response">waiting_response</a></li> + <li><a href="#waiting_classification">waiting_classification</a></li> + <li><a href="#waiting_response_overdue">waiting_response_overdue</a></li> + <li><a href="#waiting_response_very_overdue">waiting_response_very_overdue</a></li> + <li><a href="#waiting_clarification">waiting_clarification</a></li> + <li><a href="#gone_postal">gone_postal</a></li> + <li><a href="#not_held">not_held</a></li> + <li><a href="#rejected">rejected</a></li> + <li><a href="#successful">successful</a></li> + <li><a href="#partially_successful">partially_successful</a></li> + <li><a href="#internal_review">internal_review</a></li> + <li><a href="#error_message">error_message</a></li> + <li><a href="#requires_admin">requires_admin</a></li> + <li><a href="#user_withdrawn">user_withdrawn</a></li> + <li><a href="#awaiting_description">awaiting_description</a></li> +</ul> + + +<dl class="glossary"> + + <dt> + <a name="waiting_response">waiting_response</a> + </dt> + <dd> + Waiting for the public authority to reply + <ul> + <li>The default initial state</li> + <li>Can't transition here from internal_review</li> + </ul> + </dd> + + <dt> + <a name="waiting_classification">waiting_classification</a> + </dt> + <dd> + Waiting for a classification of a response + <ul> + <li>The default state after receiving a response</li> + </ul> + </dd> + + <dt> + <a name="waiting_response_overdue">waiting_response_overdue</a> + </dt> + <dd> + Waiting for a reply for too long + <ul> + <li>Automatic, if today's date is after the request date + holidays + 20 days</li> + <li>When a user updates / visits an item in this state, thank user and tell them how long they should have to wait</li> + <li>Alert user by email when something becomes overdue</li> + </ul> + </dd> + + <dt> + <a name="waiting_response_very_overdue">waiting_response_very_overdue</a> + </dt> + <dd> + Waiting for a reply for a very long time + <ul> + <li>Automatic, if today's date is after the request date + holidays + (60 days (for schools) or 40 days (everyone else))</li> + <li>When a user updates / visits something in this state, suggest they might want to complain about it; show things they might want to do</li> + <li>Alert user by email when this state happens</li> + </ul> + </dd> + + <dt> + <a name="waiting_clarification">waiting_clarification</a> + </dt> + <dd> + The public authority would like part of the request explained + <ul> + <li>Prompt user to write followup</li> + <li>if a user sends an outgoing message on a request in this state, automatically transitions to {{waiting_response}}</li> + <li>three days after this state change occurs, send reminder to user to action it (assuming user isn't banned)</li> + <li>Can't transition here from internal_review</li> + </ul> + </dd> + + <dt> + <a name="gone_postal">gone_postal</a> + </dt> + <dd> + The public authority would like to / has responded by post + <ul> + <li>If selected, remind user that in most cases authority should respond by email, and encourage followup.</li> + <li>Give most recent authority correspondence email address for user to request postal by private email.</li> + <li>Encourage user to update thread with annotation at later date.</li> + </ul> + </dd> + + <dt> + <a name="not_held">not_held</a> + </dt> + <dd> + The public authority does not have the information requested + <ul> + <li>Suggest user might want to try a different authority, or complain</li> + </ul> + </dd> + + <dt> + <a name="rejected">rejected</a> + </dt> + <dd> + The request was refused by the public authority + <ul> + <li>Show page of possible next steps</li> + </ul> + </dd> + + + <dt> + <a name="successful">successful</a> + </dt> + <dd> + All of the information requested has been received + <ul> + <li>Suggest they add annotations or make a donation</li> + </ul> + </dd> + + + <dt> + <a name="partially_successful">partially_successful</a> + </dt> + <dd> + Some of the information requested has been received + <ul> + <li>Suggest they make a donation; give ideas what to do next</li> + </ul> + </dd> + + <dt> + <a name="internal_review">internal_review</a> + </dt> + <dd> + Waiting for the public authority to complete an internal review of their handling of the request + <ul> + <li>Tell user they should expect a response within 20 days</li> + <li>When sends email to authority, adds “Internal review of” to Subject</li> + <li>Can be transitioned from the followup form</li> + </ul> + </dd> + + <dt> + <a name="error_message">error_message</a> + </dt> + <dd> + Received an error message, such as delivery failure. + <ul> + <li>Thank user for reporting, and suggest they use a form to give new email address for authority if that was the problem</li> + <li>Mark as needs admin attention</li> + </ul> + </dd> + + <dt> + <a name="requires_admin">requires_admin</a> + </dt> + <dd> + A strange reponse, required attention by the WhatDoTheyKnow team + <ul> + <li>a user is confused and doesn't know what state to set, so an admin can intervene</li> + <li>Redirect to form to ask for more information</li> + <li>Mark as needs admin attention</li> + </ul> + </dd> + + <dt> + <a name="user_withdrawn">user_withdrawn</a> + </dt> + <dd> + The requester has abandoned this request for some reason. + <ul> + <li>Prompt user to write message to tell authority</li> + </ul> + </dd> + + <dt> + <a name="awaiting_description">awaiting_description</a> + </dt> + <dd> + This state, awaiting_description, is not really a state but a flag indicating that there is no state. + </dd> + +</dl> + diff --git a/docs/running/states_informatazyrtare.md b/docs/running/states_informatazyrtare.md new file mode 100644 index 000000000..8097244c5 --- /dev/null +++ b/docs/running/states_informatazyrtare.md @@ -0,0 +1,88 @@ +--- +layout: page +title: States of requests (InformataZyrtare) +--- + +# Request states: example comparison + +<p class="lead"> + This page shows differences between states used on two different + Alaveteli instances — one in Kosovo and one in the UK. This + is a practical example showing that you can customise the states that + your site uses. +</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). + +## InformataZyrtare.org (Kosovo) example + +Requests made on Kosovo's Alaveteli instance, +[InformataZyrtare](http://informatazyrtare.org), use slightly different states +from those on the UK's instance, [WhatDoTheyKnow](http://www.whatdotheyknow.com) +(WDTK). + +Generally, this arises simply because the local legislation, or the way the +groups running the sites work, are different in different places. Alavateli +facilitates this by allowing you to customise the states that are used. + +This example is to show clearly that you can use different states depending on +your local requirements, and how that might look. See [Customising the request +states]({{ site.baseurl }}docs/customising/themes) for details on how to do this. + +### States used by InformataZyrtare but not WDTK + + * <a href="#deadline_extended">deadline_extended</a> + * <a href="#partial_rejected">partial_rejected</a> + * <a href="#wrong_response">wrong_response</a> + +### States used by WDTK but not InformataZyrtare + + * <a href="{{ site.baseurl }}docs/running/states/#awaiting_description">awaiting_description</a> + * <a href="{{ site.baseurl }}docs/running/states/#gone_postal">gone_postal</a> + * <a href="{{ site.baseurl }}docs/running/states/#internal_review">internal_review</a> + * <a href="{{ site.baseurl }}docs/running/states/#user_withdrawn">user_withdrawn</a> + * <a href="{{ site.baseurl }}docs/running/states/#waiting_response_very_overdue">waiting_response_very_overdue</a> + +For more details, see all the [states used by WhatDoTheyKnow]({{site.baseurl}}docs/running/states)) for details. + + +--- + + + +### Details of InformataZytare states + +The states which aren't represented on [WDTK's states]({{ site.baseurl }}docs/running/states/) are described +in a little more detail here: + +<ul class="definitions"> + <li><a href="#deadline_extended">deadline_extended</a></li> + <li><a href="#partial_rejected">partial_rejected</a></li> + <li><a href="#wrong_response">wrong_response</a></li> +</ul> + +<dl class="glossary"> + <dt> + <a name="deadline_extended">deadline_extended</a> + </dt> + <dd> + The Authority has requested deadline extension. + </dd> + <dt> + <a name="partial_rejected">partial_rejected</a> + </dt> + <dd> + Only part of the request has being refused but the successful request + to an information has not been attached. + </dd> + <dt> + <a name="wrong_response">wrong_response</a> + </dt> + <dd> + The authority has replied but the response does not correspond to the request. + </dd> + +</dl> + |