Suppress new rubocop warning

[rails.git] / INSTALL.md

diff --git a/INSTALL.md b/INSTALL.md
index c79e365a53be5fec888b30ed3649ca9211f994b0..4c2c7c6c80a66137e46716b5ab9f8a4fb927204a 100644 (file)
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -24,14 +24,15 @@ of packages required before you can get the various gems installed.
 * Bundler
 * Javascript Runtime
 
-These can be installed on Ubuntu 16.04 or later with:
+These can be installed on Ubuntu 18.04 or later with:
 
 ```
+sudo apt-get update
 sudo apt-get install ruby2.5 libruby2.5 ruby2.5-dev bundler \
                      libmagickwand-dev libxml2-dev libxslt1-dev nodejs \
-                     apache2 apache2-dev build-essential git-core \
-                     postgresql postgresql-contrib libpq-dev postgresql-server-dev-all \
-                     libsasl2-dev imagemagick libffi-dev libgd-dev libarchive-dev libbz2-dev
+                     apache2 apache2-dev build-essential git-core phantomjs \
+                     postgresql postgresql-contrib libpq-dev libsasl2-dev \
+                     imagemagick libffi-dev libgd-dev libarchive-dev libbz2-dev
 sudo gem2.5 install bundler
 ```
 
@@ -45,7 +46,7 @@ For Fedora, you can install the minimum requirements with:
 sudo dnf install ruby ruby-devel rubygem-rdoc rubygem-bundler rubygems \
                  libxml2-devel js \
                  gcc gcc-c++ git \
-                 postgresql postgresql-server postgresql-contrib postgresql-devel \
+                 postgresql postgresql-server postgresql-contrib \
                  perl-podlators ImageMagick libffi-devel gd-devel libarchive-devel \
                  bzip2-devel nodejs-yarn
 ```
@@ -123,6 +124,23 @@ We use [Yarn](https://yarnpkg.com/) to manage the Node.js modules required for t
 bundle exec rake yarn:install
 ```
 
+## Prepare local settings file
+
+This is a workaround. [See issues/2185 for details](https://github.com/openstreetmap/openstreetmap-website/issues/2185#issuecomment-508676026).
+
+```
+touch config/settings.local.yml
+```
+
+## Storage setup
+
+The Rails port needs to be configured with an object storage facility - for
+development and testing purposes you can use the example configuration:
+
+```
+cp config/example.storage.yml config/storage.yml
+```
+
 ## Database setup
 
 The Rails Port uses three databases -  one for development, one for testing, and one for production. The database-specific configuration
@@ -164,20 +182,10 @@ psql -d openstreetmap -c "CREATE EXTENSION btree_gist"
 
 ### PostgreSQL Functions
 
-We need to install special functions into the PostgreSQL databases, and these are provided by a library that needs compiling first.
-
-```
-cd db/functions
-make libpgosm.so
-cd ../..
-```
-
-Then we create the functions within each database. We're using `pwd` to substitute in the current working directory, since PostgreSQL needs the full path.
+We need to install some special functions into the PostgreSQL database:
 
 ```
-psql -d openstreetmap -c "CREATE FUNCTION maptile_for_point(int8, int8, int4) RETURNS int4 AS '`pwd`/db/functions/libpgosm', 'maptile_for_point' LANGUAGE C STRICT"
-psql -d openstreetmap -c "CREATE FUNCTION tile_for_point(int4, int4) RETURNS int8 AS '`pwd`/db/functions/libpgosm', 'tile_for_point' LANGUAGE C STRICT"
-psql -d openstreetmap -c "CREATE FUNCTION xid_to_int4(xid) RETURNS int4 AS '`pwd`/db/functions/libpgosm', 'xid_to_int4' LANGUAGE C STRICT"
+psql -d openstreetmap -f db/functions/functions.sql
 ```
 
 ### Database structure
@@ -208,10 +216,51 @@ Rails comes with a built-in webserver, so that you can test on your own machine
 bundle exec rails server
 ```
 
-You can now view the site in your favourite web-browser at `http://localhost:3000/`
+You can now view the site in your favourite web-browser at [http://localhost:3000/](http://localhost:3000/)
 
 Note that the OSM map tiles you see aren't created from your local database - they are just the standard map tiles.
 
 # Configuration
 
 After installing this software, you may need to carry out some [configuration steps](CONFIGURE.md), depending on your tasks.
+
+# Installing compiled shared library database functions (optional)
+
+There are special database functions required by a (little-used) API call, the migrations and diff replication. The former two are provided as *either* pure SQL functions or a compiled shared library. The SQL versions are installed as part of the recommended install procedure above and the shared library versions are recommended only if you are running a production server making a lot of `/changes` API calls or need the diff replication functionality.
+
+If you aren't sure which you need, stick with the SQL versions.
+
+Before installing the functions, it's necessary to install the PostgreSQL server development packages. On Ubuntu this means:
+
+```
+sudo apt-get install postgresql-server-dev-all
+```
+
+On Fedora:
+
+```
+sudo dnf install postgresql-devel
+```
+
+The library then needs compiling.
+
+```
+cd db/functions
+make libpgosm.so
+cd ../..
+```
+
+If you previously installed the SQL versions of these functions, we'll need to delete those before adding the new ones:
+
+```
+psql -d openstreetmap -c "DROP FUNCTION IF EXISTS maptile_for_point"
+psql -d openstreetmap -c "DROP FUNCTION IF EXISTS tile_for_point"
+```
+
+Then we create the functions within each database. We're using `pwd` to substitute in the current working directory, since PostgreSQL needs the full path.
+
+```
+psql -d openstreetmap -c "CREATE FUNCTION maptile_for_point(int8, int8, int4) RETURNS int4 AS '`pwd`/db/functions/libpgosm', 'maptile_for_point' LANGUAGE C STRICT"
+psql -d openstreetmap -c "CREATE FUNCTION tile_for_point(int4, int4) RETURNS int8 AS '`pwd`/db/functions/libpgosm', 'tile_for_point' LANGUAGE C STRICT"
+psql -d openstreetmap -c "CREATE FUNCTION xid_to_int4(xid) RETURNS int4 AS '`pwd`/db/functions/libpgosm', 'xid_to_int4' LANGUAGE C STRICT"
+```