diff options
| -rw-r--r-- | docs/developers/i18n.md | 24 | ||||
| -rw-r--r-- | docs/developers/index.md | 2 | ||||
| -rw-r--r-- | docs/installing/deploy.md | 41 | ||||
| -rw-r--r-- | docs/installing/manual_install.md | 10 | ||||
| -rw-r--r-- | docs/installing/script.md | 2 |
5 files changed, 65 insertions, 14 deletions
diff --git a/docs/developers/i18n.md b/docs/developers/i18n.md index deabc99a1..24c0c31e0 100644 --- a/docs/developers/i18n.md +++ b/docs/developers/i18n.md @@ -7,7 +7,7 @@ title: Internationalisation (for devs) <p class="lead"> This page describes some technical aspects of internationalising the - Alaveteli code. It's mostly aimed at devs who are working on the + Alaveteli code. It's mostly aimed at devs who are working on the codebase — if you just want to translate Alaveteli into your own language, see <a href="{{ site.baseurl }}docs/customising/translation">translating Alaveteli</a> @@ -29,11 +29,27 @@ work and turns it into the files that Alaveteli needs (using gettext). For example, to deploy English and Spanish translations at once: - * Ensure their `.po` files are at ```locale/en/app.po``` and ```locale/es/app.po``` + * Ensure their `.po` files are at ```locale/en/app.po``` and ```locale/es/app.po``` (for example, by downloading them from Transifex) * Set <code><a href="{{ site.baseurl }}docs/customising/config/#available_locales">AVAILABLE_LOCALES</a></code> to <code>en es</code> +### What to do if you don't have complete translations for an older release of Alaveteli + +Before a new release of Alaveteli is made, the translation files are +pulled from Transifex and added to Alaveteli's ``locale/`` directory in +github. These represent the most complete translations for the previous +release. Then the files in Transifex are updated with any new strings +that need to be translated for the upcoming release. At this point old +strings that are no longer used in the new release are also removed. The +latest [release tag](https://github.com/mysociety/alaveteli/releases) +for a release in github should contain the most complete translations +for that release from Transifex. + +If you're using an older release of Alaveteli and you want to add to or +change the translations, you can edit the .po files directly using a +local program such as [PoEdit](http://poedit.net/). + ### How to add new strings to the translations You need to do this if you've added any new strings to the code that need @@ -63,7 +79,7 @@ For more details about the translations, see the page about This is complicated by the fact that there are two competing ways to define a locale+territory combination. The POSIX (and gettext and Transifex) way is like `en_GB`; the Rails way is like `en-US`. Because we are using gettext and -Transifex for translations, we must deal with both. +Transifex for translations, we must deal with both. * for the Rails version of the currently selected locale, use `I18n.locale` * for the POSIX version of the locale, use `FastGettext.locale` @@ -85,7 +101,7 @@ Some hints for adding the strings into the Alaveteli code: * We allow some inline HTML where it helps with meaningful context, for example: ``` -_('<a href="{{browse_url}}">Browse all</a> or <a href="{{add_url}}">ask us to add it</a>.', +_('<a href="{{browse_url}}">Browse all</a> or <a href="{{add_url}}">ask us to add it</a>.', :browse_url => @browse_url, :add_url => @add_url) ``` diff --git a/docs/developers/index.md b/docs/developers/index.md index 22390f236..f1167a22b 100644 --- a/docs/developers/index.md +++ b/docs/developers/index.md @@ -45,7 +45,7 @@ title: For developers [manual installation]({{ site.baseurl }}docs/installing/manual_install/). Alternatively, there's an [Alaveteli EC2 AMI]({{ site.baseurl }}docs/installing/ami/) that might help you get up and running quickly. - [Get in touch](http://www.alaveteli.org/contact/) on the project mailing list or IRC + [Get in touch]({{ site.baseurl }}community/) on the project mailing list or IRC for help. * A standard initial step for customising your deployment is [writing a diff --git a/docs/installing/deploy.md b/docs/installing/deploy.md index c71c987bb..64ecde088 100644 --- a/docs/installing/deploy.md +++ b/docs/installing/deploy.md @@ -69,7 +69,11 @@ and thereafter you'll be able to deploy very easily (see [usage, below](#usage)) First, on the server: * [install Alaveteli]({{ site.baseurl }}docs/installing/) -* then move the Alaveteli app to a temporary place on the server, like your home +* give the Unix user that runs Alaveteli the ability to ssh to your server. Either give them a password or, preferably, set up ssh keys for them so they can ssh from your local machine to the server: + * to give them a password (if they don't already have one) - `sudo passwd [UNIX-USER]`. Store this password securely on your local machine e.g in a password manager + * to set up ssh keys for them, follow the instructions in the [capistrano documentation](http://capistranorb.com/documentation/getting-started/authentication-and-authorisation/). There's no need to set up ssh keys to the git repository as it is public. +* make sure the Unix user that runs Alaveteli has write permissions on the parent directory of your Alaveteli app +* move the Alaveteli app to a temporary place on the server, like your home directory (temporarily, your site will be missing, until the deployment puts new files in place) @@ -83,15 +87,27 @@ Next, on your local machine: need some of the files available locally even though you might not be running Alaveteli on this machine) * copy the example file `config/deploy.yml.example` to `config/deploy.yml` -* now customise the deployment settings in that file: edit `config/deploy.yml` - appropriately -- for example, edit the name of the server. Also, change - `deploy_to` to be the path where Alaveteli is currently installed on the - server -- if you used the installation script, this will be - `/var/www/alaveteli/alaveteli`. +* now customise the deployment settings in that file: edit + `config/deploy.yml` appropriately -- for example, edit the name of the + server. Also, change `deploy_to` to be the path where Alaveteli is + currently installed on the server -- if you used the installation + script , this will be `/var/www/[HOST or alaveteli]/alaveteli`. If + you're running the thin application server rather than passenger, + you'll need to set `rails_app_server` to `thin` and `rails_app_port` + to whatever port it's running on. If you installed with the install + script, this will be port 3300. + + * `cd` into the Alaveteli repo you checked out (otherwise the `cap` commands you're about to execute won't work) * still on your local machine, run `cap -S stage=staging deploy:setup` to setup capistrano on the server +If you get an error `SSH::AuthenticationFailed`, and are not prompted for the password of the deployment user, you may have run into [a bug](http://stackoverflow.com/questions/21560297/capistrano-sshauthenticationfailed-not-prompting-for-password) in the net-ssh gem version 2.8.0. Try installing version 2.7.0 instead: + + gem uninstall net-ssh + + gem install net-ssh -v 2.7.0 + Back on the server: * copy the following config files from the temporary copy of Alaveteli you made at @@ -120,10 +136,13 @@ Now, back on your local machine: * 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__link">staging site</a>, or... * `cap -S stage=production deploy` for <a href="{{site.baseurl}}docs/glossary/#production" class="glossary__link">production</a> + +Back on the server: + * update the webserver config (either apache or nginx) to add the `current` element to the path where it is serving Alaveteli from. If you installed using the installation script, this will be replacing `/var/www/alaveteli/alaveteli/` with - `/var/www/alaveteli/alaveteli/current` in `etc/nginx/sites-available/default`. + `/var/www/alaveteli/alaveteli/current` in `/etc/nginx/sites-available/default`. * edit the server crontab so that the paths in the cron jobs also include the `current` element. If you used the installation script the crontab will be in `etc/cron.d/alaveteli`. @@ -133,7 +152,13 @@ Now, back on your local machine: `argv=/var/www/alaveteli/alaveteli/script/mailin` with `argv=/var/www/alaveteli/alaveteli/current/script/mailin`. If you're using Exim as your MTA, edit `etc/exim4/conf.d/04_alaveteli_options` - to update the `ALAVETELI_HOME` variable to the new Alaveteli path. + to update the `ALAVETELI_HOME` variable to the new Alaveteli path. Restart the MTA after you've made these changes. + +* You will also need to update the path to Alaveteli in your [init scripts]({{site.baseurl}}docs/installing/manual_install/#cron-jobs-and-init-scripts). + You should have a script for running the alert tracks + (`/etc/init.d/foi-alert-tracks`), and possibly scripts for purging the + varnish cache (`/etc/init.d/foi-purge-varnish`), and restarting the + app server (`/etc/init.d/alaveteli`). Phew, you're done! diff --git a/docs/installing/manual_install.md b/docs/installing/manual_install.md index 821188b85..603db14c0 100644 --- a/docs/installing/manual_install.md +++ b/docs/installing/manual_install.md @@ -480,6 +480,16 @@ by your deploy user (named `deploy` in this case). deploy ALL = NOPASSWD: /etc/init.d/foi-alert-tracks, /etc/init.d/foi-purge-varnish +There is also an example config for stopping and starting the +Alaveteli app server as a service in `config/sysvinit.example`. This +example assumes you're using Thin as an application server, so will +need tweaking for Passenger or any other app server. You can install +this by copying it to `/etc/init.d/alaveteli` and setting the +`SITE_HOME` variable to the path where Alaveteli is running, and the +`USER` variable to the Unix user that will be running Alaveteli. Once +that's done, you can restart Alaveteli with `/etc/init.d/alaveteli +restart`. + ## Set up production web server It is not recommended to run the website using the default Rails web server. diff --git a/docs/installing/script.md b/docs/installing/script.md index 0d826ac8a..61cb76587 100644 --- a/docs/installing/script.md +++ b/docs/installing/script.md @@ -25,7 +25,7 @@ etc.** To download the script, run the following command: - curl -O https://raw.github.com/mysociety/commonlib/master/bin/install-site.sh + curl -O https://raw.githubusercontent.com/mysociety/commonlib/master/bin/install-site.sh If you run this script with `sh install-site.sh`, you'll see its usage message: |