Move docs from gh-pages branch.

1 files changed, 283 insertions, 0 deletions

diff --git a/docs/install/manual-install.md b/docs/install/manual-install.md
new file mode 100644
index 000000000..45522fd4e
--- /dev/null
+++ b/docs/install/manual-install.md
@@ -0,0 +1,283 @@
+---
+layout: page
+title: Installing
+---
+
+# Manual installation
+
+<p class="lead">
+  This page describes how to install FixMyStreet patform manually.
+  You can use this if you're used to setting up web applications &mdash; 
+  but the other installation options may be easier:</p>
+
+Note that this is just one of 
+[four ways to install FixMyStreet]({{ "/install/" | relative_url }})
+(the other ways are easier!).
+
+
+## Manual installation
+
+If you prefer to set up each required component of FixMyStreet
+yourself, proceed with the instructions below.
+
+### 1. Get the code
+
+Fetch the latest version from GitHub:
+
+{% highlight bash %}
+$ mkdir FixMyStreet
+$ cd FixMyStreet
+$ git clone --recursive https://github.com/mysociety/fixmystreet.git
+$ cd fixmystreet
+{% endhighlight %}
+
+<div class="attention-box helpful-hint">
+If you're running an old version of git, prior to 1.6.5, you'll have to clone
+and then run <code>git submodule update --init</code> separately.
+</div>
+
+### 2. Install prerequisite packages
+
+#### a. Debian / Linux
+
+If you're using Debian or Ubuntu, then the packages to install required
+dependencies are listed in `conf/packages.generic`. To install all of them you
+can run e.g.:
+
+{% highlight bash %}
+$ sudo xargs -a conf/packages.generic apt-get install
+{% endhighlight %}
+
+A similar list of packages should work for other Debian-based distributions.
+(Please let us know if you would like to contribute such a package list or
+instructions for other distributions.)
+
+#### b. Mac OS X
+
+Install either MacPorts or HomeBrew (you might well have one already), and then
+use the command below to install a few packages that FixMyStreet needs, for
+which it's much simpler to install via a packaging system.
+
+##### i. MacPorts
+
+{% highlight bash %}
+$ port install gettext p5-locale-gettext p5-perlmagick jhead postgresql91-server
+{% endhighlight %}
+
+##### ii. HomeBrew
+
+{% highlight bash %}
+$ brew install gettext perlmagick jhead postgresql
+$ brew link gettext --force
+{% endhighlight %}
+
+<div class="attention-box">
+gettext needs to be linked for the Locale::gettext Perl module to install; you
+can unlink gettext once everything is installed.
+</div>
+
+#### c. Other
+
+You need Perl 5.8, ImageMagick with the perl bindings, and gettext.
+If you're expecting a lot of traffic it's recommended that you install memcached: <http://memcached.org/>
+
+### 3. Install prerequisite Perl modules
+
+FixMyStreet uses a number of CPAN modules; to install them, run:
+
+{% highlight bash %}
+$ bin/install_perl_modules
+{% endhighlight %}
+
+This should tell you what it is installing as it goes. It takes some time, so
+feel free to continue with further steps whilst it's running.
+
+<div class="attention-box helpful-hint">
+<!-- Below hopefully not needed as installed p5-locale-gettext above
+<p>Note, with MacPorts you might have to specify some compilation PATHs:</p>
+<pre><code>C_INCLUDE_PATH=/opt/local/include LIBRARY_PATH=/opt/local/lib bin/install_perl_modules</code></pre>
+-->
+<p>It is possible you may need to install some source packages to allow some of
+the included modules to be built, including expat (libexpat1-dev), postgresql
+(postgresql-server-dev-8.4), or the GMP math library (libgmp3-dev).</p>
+</div>
+
+### 4. Generate CSS
+
+There is a script, `bin/make_css`, that converts our SCSS files to CSS files.
+So let's run that:
+
+{% highlight bash %}
+$ bin/make_css
+{% endhighlight %}
+
+### 5. Create a new PostgreSQL database
+
+The default settings assume the database is called fms and the user the same.
+You can change these if you like. Using the defaults, create a user and
+database using the following (do not worry if the `CREATE LANGUAGE` step gives
+an error that it already exists, it might well do depending on how your
+PostgreSQL was installed):
+
+{% highlight sql %}
+$ sudo -u postgres psql
+postgres=# CREATE USER fms WITH PASSWORD 'somepassword';
+CREATE ROLE
+postgres=# CREATE DATABASE fms WITH OWNER fms;
+CREATE DATABASE
+postgres=# \c fms
+postgres=# CREATE LANGUAGE plpgsql;
+postgres=# \q
+$
+{% endhighlight %}
+
+You should be able to connect to the database with `psql -U fms fms` -- if not,
+you will need to investigate [how to allow access to your PostgreSQL database]({{ "/install/database" | relative_url }}).
+
+#### 5b. Install database schema
+
+Now you can use the provided schema migration script to create the required
+tables, triggers, and initial data. Run the following:
+
+{% highlight bash %}
+$ bin/update-schema --commit
+{% endhighlight %}
+
+### 6. Set up config
+
+The settings for FixMyStreet are defined in `conf/general.yml` using the YAML
+markup language. There are some defaults in `conf/general.yml-example` which
+you should copy to `conf/general.yml`:
+
+{% highlight bash %}
+$ cp conf/general.yml-example conf/general.yml
+{% endhighlight %}
+
+The bare minimum of settings you will need to fill in or update are:
+
+* [FMS_DB_PASS]({{ "/customising/config/#fms_db_pass" | relative_url }}) -- this is the password for the database. (Also obviously change any other database settings you did differently here.)
+* [BASE_URL]({{ "/customising/config/#base_url" | relative_url }}) -- for using the development server, set to `'http://localhost:3000/'`. This is the URL of the homepage of your FixMyStreet installation.
+* [MAPIT_URL]({{ "/customising/config/#mapit_url" | relative_url }}) -- for the development server, set to `'http://localhost:3000/fakemapit/'`. This would be the URL of a MapIt installation, as and when you use one.
+
+Some others you might want to look at, though the defaults are enough for it to run:
+
+* [EMAIL_DOMAIN]({{ "/customising/config/#email_domain" | relative_url }}) -- the email domain that emails will be sent from
+* [CONTACT_EMAIL]({{ "/customising/config/#contact_email" | relative_url }}) -- the email address to be used on the site for the contact us form.
+* [DO_NOT_REPLY_EMAIL]({{ "/customising/config/#do_not_reply_email" | relative_url }}) -- the email address to be used on the site for e.g. confirmation emails.
+* [STAGING_SITE]({{ "/customising/config/#staging_site" | relative_url }}) -- if this is 1 then all email (alerts and reports) will be sent to the contact email address. Use this for development sites.
+* [UPLOAD_DIR]({{ "/customising/config/#upload_dir" | relative_url }}) -- this is the location where images will be stored when they are uploaded. It should be accessible by and writeable by the FixMyStreet process.
+* [GEO_CACHE]({{ "/customising/config/#geo_cache" | relative_url }}) -- this is the location where Geolocation data will be cached. It should be accessible by and writeable by the FixMyStreet process.
+
+If you are using Bing or Google maps you should also set one of
+[BING_MAPS_API_KEY]({{ "/customising/config/#bing_maps_api_key" | relative_url }}) or 
+[GOOGLE_MAPS_API_KEY]({{ "/customising/config/#google_maps_api_key" | relative_url }}).
+
+### 7. Set up some required data
+
+You need to generate the data used for the `/reports` page (this is run by the
+crontab, but to have it working from the start, we can run the script
+manually). Also, if you wish to use other languages, you will need to generate
+.mo files for them.
+
+{% highlight bash %}
+$ bin/update-all-reports
+$ commonlib/bin/gettext-makemo FixMyStreet
+{% endhighlight %}
+
+### 8. Run
+
+The development server can now hopefully be run with:
+
+{% highlight bash %}
+$ script/server
+{% endhighlight %}
+
+The server will be accessible as <http://localhost:3000/>. You can run with -r
+in order for the server to automatically restart when you update the code.
+
+
+### Post-install: Things you might want to change
+
+#### Next Steps
+
+* Create a superuser with the `bin/createsuperuser` script to access admin site.
+* [Customise your install using Templates, CSS and a Cobrand module](/customising/).
+* Add contact details for authorities and categories using the admin interface.
+
+#### Tile server
+
+You will also need a tile server to serve up map tiles. FixMyStreet can
+currently use tile servers such as Bing, OpenStreetMap and Google, defaulting
+to OpenStreetMap.
+
+#### Geocoding
+
+Finally, you will need a geolocation service to turn addresses into longitude
+and latitudes. FixMyStreet currently includes code to use Bing, Google, and
+OpenStreetMap geolocation services, again defaulting to OpenStreetMap.
+
+#### Cron jobs
+
+There is an example crontab in `conf/crontab-example`. You can use that as a
+base for your own user crontab.
+
+### Deployment
+
+For <a href="{{ "/glossary/#production" | relative_url }}" class="glossary__link">production</a>
+use of FixMyStreet, we suggest you use Apache or nginx, and
+FastCGI. It should also be possible to run it using Plack/PSGI, if that is
+preferable.
+
+#### Apache
+
+There is an example Apache vhost configuration file in
+`conf/apache-vhost.conf.example` and `conf/httpd.conf-example`, which contain a
+sample configuration and the required redirect rules.
+
+The sample configuration will need the following modules enabled:
+
+* mod_rewrite
+* mod_proxy
+* mod_expires
+* mod_fastcgi
+
+For most Linux distributions you should be able to install these using the
+distribution's packaging system.
+
+#### nginx
+
+There is an example nginx configuration in `conf/nginx.conf.example`. With
+nginx, you need to run the FastCGI service separately - the
+`conf/sysvinit.example` file is an example script you could use to run it as a
+daemon. And you will need to install a FastCGI process manager:
+
+{% highlight bash %}
+$ apt-get install libfcgi-procmanager-perl
+{% endhighlight %}
+
+#### Check it's working
+
+At this point you should be able to restart the webserver and see your
+FixMyStreet installation at the configured URL.
+
+You can run the unit tests by running the following command in the
+`fixmystreet` directory:
+
+{% highlight bash %}
+$ bin/run-tests t
+{% endhighlight %}
+
+The `master` branch of the repository should always be passing all tests for
+our developers and on mySociety's servers.
+
+## Problems?
+
+See some [troubleshooting hints]({{ "/install/troubleshooting/" | relative_url }}) if
+something's not working for you.
+
+## When you've finished
+
+Please see the instructions for [updating your code](/updating/) once it's installed.
+
+If you want to know which bits of FixMyStreet are in which directory, see this
+[summary of the directory structure](/directory_structure).