diff --git a/docs/adding-new-fields.md b/docs/adding-new-fields.md deleted file mode 100644 index ce139334..00000000 --- a/docs/adding-new-fields.md +++ /dev/null @@ -1,52 +0,0 @@ -# Adding new building attribute fields - -This document is a checklist for adding a new building attribute to the system. It's split into three sections - actions that apply when adding any field, and additional steps to add a field that will be visualised on the map. -The second section would be required when adding a new category or when changing which field should be visualised for a category. -The third section would apply to any data which can be amended via the API. -When adding a new attribute a set of seed data should be identified, the base data set for many fields is Polly Hudsons PhD data set. This data set is required to; -- Test visualisation elements (map styling) -- Provide some data for users to relate to and encourage them to fill in the field -- Test the API and database elements. - - -## Adding any attribute - -### In database -1. Add a column to the `buildings` table in the database. -2. Add any check constraints or foreign key constraints on the column, if necessary (if the foreign key constraint is used to restrict the column to a set of values, the table with the values might need to be created from scratch) -3. If a source is being collected for field. Add a column `fieldName_source` to the `sources` table. -4. If verification is being enabled. Add a column `bieldName_verifications` to the `verfication` table. - - -### In API -1. Add field name to `BUILDING_FIELD_WHITELIST` in the building service to allow saving changes to the field -2. Add any special domain logic for processing updates to the field in the `processBuildingUpdate()` function - -### In frontend -1. Add the field description to the `dataFields` object in `data_fields.ts` -2. Add the data entry React component of the appropriate type (text, numeric etc) to the appropriate category view component in the `building/data-containers` folder. Link to `dataFields` for static string values (field name, description etc) - - -### In data extracts -1. Add the field to the select list in the COPY query in `maintenance/extract_data/export_attributes.sql` -2. Add a description of the field to the `README.txt` file - -## Adding an attribute which is used to colour the map - -All steps from the previous section need to be carried out first. - -### In tileserver -1. Add a SQL query for calculating the value to be visualised to `BUILDING_LAYER_DEFINITIONS` in `app/src/tiles/dataDefinition.ts` -2. Add Mapnik rendering style in `app/map_styles/polygon.xml` - -### In frontend -1. Update the category to field name mapping in the `tilesetByCat` object inside the `ColouringMap` React component (`map.tsx` file) -2. Add an entry for the field to the `LEGEND_CONFIG` object in `legend.tsx` file - - -## Testing - -Run tests on staging to confirm; -- Database changes accepted -- API is working and data is getting posted to the database -- Map styling is applied and style is appropriate way to visualise the data diff --git a/docs/configuring-colouring-cities.md b/docs/configuring-colouring-cities.md deleted file mode 100644 index 38a35c9e..00000000 --- a/docs/configuring-colouring-cities.md +++ /dev/null @@ -1,82 +0,0 @@ -# Configuring the Colouring Cities Core Platform - -## Introduction - -We have added new configuration options to the Colouring Cities Core Platform, in order to make it easier to customise the platform for different cities/countries without unnecessary custom code and diverging codebases. - -This is done using configuration files, which are described in detail later in this document. - -Our hope is that every project in the Colouring Cities Research Programme (CCRP) will use this method to customise the interfaces of the Colouring Cities Platform for their own use as the programme moves forwards. - -Some location specific information can be also added into database - for example location info used by search function can be customized for a given location. - -## The Config Files -The configuration files are located here: - -`app/src/cc-config.ts` -`app/src/cc-config.json` - -### > cc-config.json -The JSON file contains the definition of the values of the variables. - -Currently, these parameters include: - -- **'cityName'** (string) - The name of the city/country. -- **'projectBlurb'** (string) - A line of text describing the relationship of the project to the CCRP -- **'githubURL'** (string) - The URL of the *project specific* GitHub repository -- **'privacyStatement'** (string) - A description of where user data is stored and what safeguards are in place - -These text strings are then used at various points throughout the Platform's interface. - -There are also some other values to customise the behaviour of the application: - -- **'initialMapPosition'** (string) - The default latitude and longitude of the map when the page loads. -- **'initialZoomLevel'** (string) - The default zoom level when the map loads. -- **'basemapTileUrl'** (string) - URL of basemap, in format accepted by Leaflet, shown under any displayed features. Note that default one is using external servers with own [Usage Policy](https://operations.osmfoundation.org/policies/tiles/) - please review it. -- **'baseAttribution'** (string) - basic attribution, in format accepted by Leaflet, should include basemap attribution, attribution for work of Colouring platform contributors and likely also attribute source of building geometries. Default `baseAttribution` always needs to be edited, though it contains part of required attribution for attribute data and default basemap. - -For example, the [JSON file for Colouring London](https://github.com/colouring-cities/colouring-london/blob/master/app/src/cc-config.json) looks like this: - -```json -{ - "cityName": "London", - "projectBlurb": "Colouring London is also the prototype for the Colouring Cities Research Programme (CCRP)", - "githubURL": "https://github.com/colouring-cities/colouring-london", - "privacyStatement": "Colouring London stores your data at The Alan Turing Institute in London behind the organisation’s firewall in a secure database using industry standard practices", - - "initialMapPosition": [ 51.5245255, -0.1338422 ], - "initialZoomLevel": 16, - - "postcode": "Postcode", - "energy_rating": "Building Research Establishment Environmental Assessment Method (BREEAM) rating" -} -``` - -### > cc-config.ts -This file contains the declaration of the variables that can be configured. - -If you want to add additional parameters into the configuration framework, then they will need to be declared in this file and then defined in the JSON file (see below). - ---- - -**NOTE: Any additional project specific text strings and parameters should be added to this file and the JSON file.** - -*REQUEST: If you find any London-specific text or values, please report them or create a pull request to move them into the configuration framework.* - -## Database - -`search_locations` can be populated with post codes and location names specific for a given area. - -Queries that should be run look like - -```sql -INSERT INTO search_locations(search_str, search_class, center, zoom) VALUES -('TA1 1AA', 'postcode', ST_SetSRID(ST_MakePoint(-3.10964, 51.02344), 4326), 18), ('TA1 1AD', 'postcode', ST_SetSRID(ST_MakePoint(-3.108002733789686, 51.017315853093045), 4326), 18), -('Lboro', 'settlement_name', ST_SetSRID(ST_MakePoint(-1.20552, 52.77230), 4326), 14), -('Loughborough', 'settlement_name', ST_SetSRID(ST_MakePoint(-1.20552, 52.77230), 4326), 14) -; -``` - -See an [example script used by Colouring Britain](https://github.com/colouring-cities/colouring-britain/blob/master/etl/load_postcodes.sh) as a potential inspiration. But other data sources will be needed for locations outside UK. - -After adding new locations run `REINDEX TABLE search_locations;` to improve performance of search. diff --git a/docs/setup-dev-environment.md b/docs/setup-dev-environment.md deleted file mode 100644 index 68a1e485..00000000 --- a/docs/setup-dev-environment.md +++ /dev/null @@ -1,416 +0,0 @@ -# Setting up a local development environment - -### WARNING: Setup document suitable for development environment, not production server - -This document is intended to guide you through setting up a local development environment for the Colouring Cities application. This guide assumes you already have either already have access to an machine with Ubuntu 18.04 installed, or can use VirtualBox to set up an Ubuntu virtual machine as below. - -#### Note -This guide assumes you are working with the ['colouring-core'](https://github.com/colouring-cities/colouring-core) repository. If you are creating your own fork, or want to use a custom city name, then you may wish to change `'colouring-core'` to `'colouring-[your city name]'`. - -
- -Configuring an Ubuntu VM in VirtualBox -

- -Here we explain how to use VirtualBox and SSH into your Ubuntu installation for convenience. - -When setting up the VirtualBox VM, consider the size of the database you intend to load for use with the application. Consult the [:house: Loading the building data](#house-loading-the-building-data) section of this guide and decide whether you will be using a full city database or will load test data from OSM. - -For "Colouring London", we have found that the size of the database means that a VM with access to 50GB of storage is appropriate. If you are using the OSM test data, the default storage settings in VirtualBox should suffice. - -##### In either case, you should set the memory to at least `2048` MB. - -If you a running Ubuntu in a virtual environment you will need to configure networking to forward ports from the guest to the host. For Virtual Box the following was configured under NAT port forwarding (found under `Settings -> Network -> Advanced -> Port Forwarding`). - -Name | Protocol | Host Port | Guest Port --------- | --------- | ---------- | ----------- -app | TCP | 8080 | 3000 -app_dev | TCP | 3001 | 3001 -ssh | TCP | 4022 | 22 - -The `app_dev` mapping is used in development by Razzle which rebuilds and serves client side assets on the fly. - -To run the commands in the rest of this setup guide, either `ssh` into the VirtualBox environment or open the terminal within the Ubuntu GUI. - -If you wish to `ssh`, you will first need to open the terminal in Ubuntu and run the following. - -```bash -sudo apt-get install -y openssh-server -``` - -You can then `ssh` into the VirtualBox VM set up with the port forwarding described above like so, where `` is the name you set up during the installation of Ubuntu (you can type `whoami` in the Ubuntu terminal to remind yourself of this). - -```bash -ssh @localhost -p 4022 -``` -
- -## Contents - -- [:tulip: Installing the tools and components](#tulip-installing-the-tools-and-components) - - [:red_circle: Installing PostgreSQL](#red_circle-installing-postgresql) - - [:rainbow: Installing Colouring Cities Core Platform](#rainbow-installing-colouring-cities-core-platform) - - [:arrow_down: Installing Node.js](#arrow_down-installing-nodejs) - - [:large_blue_circle: Configuring PostgreSQL](#large_blue_circle-configuring-postgresql) - - [:space_invader: Create an empty database](#space_invader-create-an-empty-database) - - [:arrow_forward: Configuring Node.js](#arrow_forward-configuring-nodejs) - - [:snake: Set up Python](#snake-set-up-python) -- [:house: Loading the building data](#house-loading-the-building-data) -- [:computer: Running the application](#computer-running-the-application) - - [:eyes: Viewing the application](#eyes-viewing-the-application) - -## :tulip: Installing the tools and components - -First upgrade the installed packages to the latest versions, to remove any security warnings. - -```bash -sudo apt-get update -y -sudo apt-get upgrade -y -``` - -Now install some essential tools. - -```bash -sudo apt-get install -y build-essential git wget curl parallel rename -``` - -### :red_circle: Installing PostgreSQL - -Set the postgres repo for apt (these instructions were taken from [postgresql.org](https://www.postgresql.org/download/linux/ubuntu/)). - -```bash -sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list' -``` - -```bash -sudo wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add - -``` - -```bash -sudo apt-get update -``` - -Next install postgres and postgis to enable support for geographical objects. - -```bash -sudo apt-get install -y postgresql-12 postgresql-contrib-12 libpq-dev postgis postgresql-12-postgis-3 -``` - -and additional geo-spatial tools - -```bash -sudo apt-get install -y gdal-bin libspatialindex-dev libgeos-dev libproj-dev -``` - -### :rainbow: Installing Colouring Cities Core Platform - -Now clone the `colouring-core` codebase. - -```bash -cd ~ && git clone https://github.com/colouring-cities/colouring-core.git -``` - -**Note:** We assume here that you will clone the repo into the home directory of your Ubuntu installation. Watch out for later commands in this guide that assume the repo is located at `~/colouring-core` and modify the path if appropriate. - -### :arrow_down: Installing Node.js - -Now install Node. It is helpful to define some local variables. - -```bash -export NODE_VERSION=v16.13.2 -export DISTRO=linux-x64 -wget -nc https://nodejs.org/dist/$NODE_VERSION/node-$NODE_VERSION-$DISTRO.tar.xz -sudo mkdir /usr/local/lib/node -sudo tar xf node-$NODE_VERSION-$DISTRO.tar.xz -C /usr/local/lib/node -sudo mv /usr/local/lib/node/node-$NODE_VERSION-$DISTRO /usr/local/lib/node/node-$NODE_VERSION -rm node-$NODE_VERSION-$DISTRO.tar.xz -``` - -Now add the Node installation to the path and export this to your bash profile. - -```bash -cat >> ~/.profile < /dev/null -``` - -Restart postgres to pick up config changes. - -```bash -sudo service postgresql restart -``` - -Create a superuser role for this user (``) if it does not already exist. The -password `` is arbitrary and probably should not be your Ubuntu login password. - -```bash -sudo -u postgres psql -c "SELECT 1 FROM pg_user WHERE usename = '';" | grep -q 1 || sudo -u postgres psql -c "CREATE ROLE SUPERUSER LOGIN PASSWORD '';" -``` - -
-Note for "Colouring Cities" devs

- -If you intend to load the full CL database from a dump file into your dev environment, run the above `psql` command with `` as "cldbadmin" and use that username in subsequent steps, but also run the above a second time with `` as "clwebapp" (see section [:house: Loading the building data](#house-loading-the-building-data) for more details). - -

- -### :space_invader: Create an empty database - -Now create an empty database configured with geo-spatial tools. The database name (``) is arbitrary. - -Set environment variables, which will simplify running subsequent `psql` commands. - -```bash -export PGPASSWORD= -export PGUSER= -export PGHOST=localhost -export PGDATABASE= -``` - -Create the database. - -```bash -sudo -u postgres psql -c "SELECT 1 FROM pg_database WHERE datname = '';" | grep -q 1 || sudo -u postgres createdb -E UTF8 -T template0 --locale=en_US.utf8 -O -``` - -```bash -psql -c "create extension postgis;" -psql -c "create extension pgcrypto;" -psql -c "create extension pg_trgm;" -``` - -### :arrow_forward: Configuring Node.js - -Now upgrade the npm package manager to the most recent release with global privileges. This needs to be performed as root user, so it is necessary to export the node variables to the root user profile. - -```bash -export NODEJS_HOME=/usr/local/lib/node/node-v16.13.2/bin/ -export PATH=$NODEJS_HOME:$PATH -sudo env "PATH=$PATH" npm install -g npm@latest -``` - -Now install the required Node packages. This needs to done from the `app` directory of your -local repository, so that it can read from the `package.json` file. - -```bash -cd ~/colouring-core/app -npm install -``` - -### :snake: Set up Python - -Install python and related tools. - -```bash -sudo apt-get install -y python3 python3-pip python3-dev python3-venv -``` - -## :house: Loading the building data - -There are several ways to create the Colouring Cities database in your environment. The simplest way if you are just trying out the application would be to use test data from OSM, but otherwise you should follow one of the instructions below to create the full database either from scratch, or from a previously made db (via a dump file). - -To create the full database from scratch, follow [these instructions](../etl/README.md), otherwise choose one of the following: - -
- Create database from dump

- -If you are a developer on the Colouring London project (or another Colouring Cities project), you may have a production database (or staging etc) that you wish to duplicate in your development environment. - -Log into the environment where your production database is kept and create a dump file from the db. - -```bash -pg_dump > -``` - -You should then download the file to the machine where you are setting up your development environment. If you are using Virtualbox, you could host share the dump file with the VM via a shared folder (e.g. [see these instructions for Mac](https://medium.com/macoclock/share-folder-between-macos-and-ubuntu-4ce84fb5c1ad)). - -In your Ubuntu installation where you have been running these setup steps (e.g. Virtualbox VM), you can then recrate the db like so. - -```bash -psql < -``` - -Alternatively, if you get errors using the above command, use pg_restore: - ```bash -pg_restore -d -``` - -#### Run migrations - -Now run all 'up' migrations to create tables, data types, indexes etc. The `.sql` scripts to -do this are located in the `migrations` folder of your local repository. - -```bash -ls ~/colouring-core/migrations/*.up.sql 2>/dev/null | while read -r migration; do psql < $migration; done; -``` - -Again, if you get errors, you may need to manually specify the database name - -```bash -ls ~/colouring-core/migrations/*.up.sql 2>/dev/null | while read -r migration; do psql -d < $migration; done; -``` -
- -
- Create database with test data

- -This section shows how to load test buildings into the application from OpenStreetMaps (OSM). - -#### Load OpenStreetMap test polygons - -Create a virtual environment for python in the `etl` folder of your repository. In the following example we have name the virtual environment *colouringcities* but it can have any name. - -```bash -cd ~/colouring-core/etl -pyvenv colouringcities -``` - -Activate the virtual environment so we can install python packages into it. - -```bash -source colouringcities/bin/activate -``` - -Install python pip package manager and related tools. - -```bash -pip install --upgrade pip -pip install --upgrade setuptools wheel -``` - -Install the required python packages. - -```bash -pip install -r requirements.txt -``` - -To help test the Colouring Cities application, `get_test_polygons.py` will attempt to save a small (1.5km²) extract from OpenStreetMap to a format suitable for loading to the database. - -**NOTE:** You can edit the file by [changing this line](https://github.com/colouring-cities/colouring-core/blob/df651521983665056d442603a329a37d966aede1/etl/get_test_polygons.py#L22) to specify the latitude and longitude used to define the centre of the sample data area, as well as the distance from that point, which are used to generate the sample data. (i.e. you could change it to match the cc-config.json file - as discussed in [configuring-colouring-cities.md](https://github.com/colouring-cities/colouring-core/blob/master/docs/configuring-colouring-cities.md). - -Download the test data. - -```bash -python get_test_polygons.py -``` - -Note: the first time you run it, you will get these warnings: -``` -rm: cannot remove 'test_buildings.geojson': No such file or directory -rm: cannot remove 'test_buildings.3857.csv': No such file or directory -``` - -#### Run migrations - -Now run all 'up' migrations to create tables, data types, indexes etc. The `.sql` scripts to -do this are located in the `migrations` folder of your local repository. - -```bash -ls ~/colouring-core/migrations/*.up.sql 2>/dev/null | while read -r migration; do psql < $migration; done; -``` - -#### Load buildings - -Load all building outlines. - -```bash -./load_geometries.sh ./ -``` - -Create a building record per outline. - -```bash -./create_building_records.sh -``` -
- -After buildings are loaded or their geometries changed, it is necessary to flush cache files so outdated geometries are not shown. -This can be achieved by deleting relevant folder at the server. - -## :computer: Running the application - -Now we are ready to run the application. - -First enter the app directory. - -```bash -cd ~/colouring-core/app -``` - -Then create a folder for the tilecache. - -```bash -mkdir tilecache -``` - -Create some additional variables for running the application (the `APP_COOKIE_SECRET` is arbitrary). - -```bash -export PGPORT=5432 -export APP_COOKIE_SECRET=123456 -export TILECACHE_PATH=~/colouring-core/app/tilecache -``` - -Finally, simply run the application with npm. - -```bash -npm start -``` - -**Note:** You can also specify the variables for `npm start` like so: -
- -Specify variables - - -```bash -PGPASSWORD= PGDATABASE= PGUSER= PGHOST=localhost PGPORT=5432 APP_COOKIE_SECRET=123456 TILECACHE_PATH=~/colouring-core/app/tilecache npm start -``` - -

- -### :eyes: Viewing the application - -The site can then be viewed on http://localhost:8080 on the host computer. - -Finally to quit the application type `Ctrl-C`. diff --git a/docs/setup-production-environment.md b/docs/setup-production-environment.md deleted file mode 100644 index 8a6fa3fc..00000000 --- a/docs/setup-production-environment.md +++ /dev/null @@ -1,332 +0,0 @@ -# Setting Up A Production Environment - -#### Note -This guide assumes you are working with the ['colouring-core'](https://github.com/colouring-cities/colouring-core) repository. If you are creating your own fork, or want to use a custom city name, then you may wish to change `'colouring-core'` to `'colouring-[your city name]'`. - -#### Preliminaries - -This guide assumes a virtual environment (VM) running Ubuntu 20_04. - -Install updates to packages: - -`sudo apt-get update` - -`sudo apt-get dist-upgrade` - - -Install openSSH (if necessary) - -`sudo apt install openssh-server` - - -*** - - -#### Install Essential Components - -Install some useful development tools - -`sudo apt-get install -y build-essential git vim-nox wget curl` - -Install Postgres and associated tools - -`sudo apt-get install -y postgresql postgresql-contrib libpq-dev postgis postgresql-12-postgis-3` - -`sudo apt-get install -y gdal-bin libspatialindex-dev libgeos-dev libproj-dev` - -Install Python 3 and pip - -`sudo apt-get install python3 python3-pip` - - -Install Nginx - -`sudo apt install nginx` - - -Clone the remote Colouring Cities GitHub repository into `/var/www` - -`cd /var/www` - -`sudo git clone https://github.com/colouring-cities/colouring-core.git` - -Create a system user (`nodeapp`) to `chown` the `colouring-core` directory - -`useradd -r -s /bin/nologin nodeapp` - -Add the current user to the `nodeapp` group - -`sudo usermod -a -G nodeapp ` - -Make the `nodeapp` user/group `chown` the `colouring-core` directory and its subdirectories - -`sudo chown -R nodeapp:nodeapp /var/www/colouring-core` - -Now set appropriate permissions on the `colouring-core` directory - -`sudo chmod -R 775 /var/www/colouring-core` - - -*** - - -#### Install Node. - -First define a couple of convenience variables: - -`NODE_VERSION=v12.14.1` - -`DISTRO=linux-x64` - -Get the Node distribution and install it - -`wget -nc https://nodejs.org/dist/$NODE_VERSION/node-$NODE_VERSION-$DISTRO.tar.xz` - -`sudo mkdir /usr/local/lib/node` - -`sudo tar xf node-$NODE_VERSION-$DISTRO.tar.xz -C /usr/local/lib/node` - -`sudo mv /usr/local/lib/node/node-$NODE_VERSION-$DISTRO /usr/local/lib/node/node-$NODE_VERSION` - -`rm node-$NODE_VERSION-$DISTRO.tar.xz` - - -Export the `NODE_JS_HOME` variable to your bash profile - - cat >> ~/.profile < /dev/null` - - -For production we do not want to use our Ubuntu username as the Postgres username. So we need to replace peer authentication with password authentication for local connections. - -`sudo sed -i 's/^local.*all.*all.*peer$/local all all md5/' /etc/postgresql/10/main/pg_hba.conf` - - -Restart Postgres for the configuration changes to take effect - -`sudo service postgresql restart` - -Create a distinct Postgres user - -`sudo -u postgres psql -c "SELECT 1 FROM pg_user WHERE usename = '';" | grep -q 1 || sudo -u postgres psql -c "CREATE ROLE SUPERUSER LOGIN PASSWORD '';"` - - -Create default colouring cities database - -`sudo -u postgres psql -c "SELECT 1 FROM pg_database WHERE datname = 'colouringcitiesdb';" | grep -q 1 || sudo -u postgres createdb -E UTF8 -T template0 --locale=en_US.utf8 -O colouringcitiesdb` - -`psql -d colouringcitiesdb -U -c "create extension postgis;"` - -`psql -d colouringcitiesdb -U -c "create extension pgcrypto;"` - -`psql -d colouringcitiesdb -U -c "create extension pg_trgm;"` - - -Import data from the most recent colouring cities database dump - -`pg_restore --no-privileges --no-owner --username "" --dbname "colouringcitiesdb" --clean ""` - - -*** - - -#### Configure NGINX - -Configure linux firewall - -`sudo ufw allow 'Nginx HTTP'` - -`sudo ufw allow OpenSSH` - -`sudo ufw enable` - -We can check the status of the firewall with - -`sudo ufw status` - - -Now edit `sites-available/default` to create a minimal Nginx configuration to test the installation - -`sudo nano /etc/nginx/sites-available/default` - - - - # Handle HTTP connections with redirect - server { - listen 80 default_server; - listen [::]:80 default_server; - server_name colouring-core; - - location / { - proxy_pass http://localhost:3000/; - proxy_set_header X-Real-IP $remote_addr; - } - - } - - - -Make sure you didn't introduce any syntax errors by typing: - -`sudo nginx -t` - - -If all is well, restart Nginx - -`sudo systemctl restart nginx` - - - -Test out the configuration - -`cd /var/www/colouring-core/app` - - -`npm run build` - - -`PGPASSWORD= PGDATABASE=colouringcitiesdb PGUSER= PGHOST=localhost PGPORT=5432 APP_COOKIE_SECRET= npm run start:prod` - -Now open a browser window on a client machine and navigate to the IP Address of your VM - -`http://` - -You should see the Colouring Cities homepage. - - -*** - - -#### Set up PM2 - -Perform a global install of PM2 - -`sudo su root` - -`export NODEJS_HOME=/usr/local/lib/node/node-v12.14.1/bin/` - -`export PATH=$NODEJS_HOME:$PATH` - -`npm install -g pm2` - -`exit` - - -Create an `ecosystem.config.js` file from the template file - -`cd /var/www/colouring-core` - -`nano ecosystem.config.template.js` - - - // Template for production ecosystem file - - // Copy this file and edit to set up pm2 config - // DO NOT COMMIT details to this file (publicly visible) - // See https://pm2.io/doc/en/runtime/guide/ecosystem-file/ for docs - module.exports = { - apps: [ - { - name: "colouringcities", - script: "./app/build/server.js", - instances: 6, - env: { - NODE_ENV: "production", - PGHOST: "localhost", - PGPORT: 5432, - PGDATABASE: "colouringcitiesdb", - PGUSER: "", - PGPASSWORD: "", - APP_COOKIE_SECRET: "", - TILECACHE_PATH: "/var/www/colouring-core/app/tilecache" - } - } - ] - } - -Edit the above file as appropriate and save as `ecosystem.config.js` - - -Start the colouring-core app - -`cd /var/www/colouring-core` - -`pm2 start ecosystem.config.js` - -Open a browser window on a client machine and navigate to the IP Address of your VM - -`http://` - -You should see the Colouring Cities homepage. - -To stop the colouring-core app type: - -`pm2 stop ecosystem.config.js` - - -*** - -#### Set up data extracts - -Install requirements for the maintenance Python scripts - -`cd /var/www/colouring-core/maintenance` - -`sudo pip3 install -r requirements.txt` - -The maintenance scripts might need environment variables present at the time of execution, notably the database connection details. -If running the scripts manually, the variables can be provided just before execution, for example - -`PGHOST=localhost PGPORT=5432 PGDATABASE=dbname PGUSER=username PGPASSWORD=secretpassword EXTRACTS_DIRECTORY=/var/www/colouring-core/downloads python3 maintenance/extract_data/extract_data.py` - -If the maintenance script is to be run on a schedule, the variables should be loaded before running the script, for example from a `.env` file. - - -#### Set up SSL - TO DO - -DON'T FORGET to open the Ubuntu firewall to HTTPS - - diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md deleted file mode 100644 index 4ac0f570..00000000 --- a/docs/troubleshooting.md +++ /dev/null @@ -1,8 +0,0 @@ -# Troubleshooting Colouring Cities - -## 502 Error -If you get a 502 error on the server after updating the deployment, there are a few solutions you can try to fix it. -Note: This seems to often occur after the dependencies (package-lock.json) have been update. - -- The quickest and easiest solution is to do a full reboot of the server, to get rid of any caching issues. -- Alternatively, try deleting all of the files in the deployment folder (i.e. /var/www/colouring-london/app for Colouring London) before rebuilding/redeploying the app, as that will get rid of any erroneous files. diff --git a/docs/working-with-colouring-core.md b/docs/working-with-colouring-core.md deleted file mode 100644 index 30d7e022..00000000 --- a/docs/working-with-colouring-core.md +++ /dev/null @@ -1,25 +0,0 @@ -# Working with the Colouring Cities Core Platform - -To make Colouring Cities a better and more collaborative platform, we strongly encourage all of our partners to keep their code as unified with the [Core Platform](https://github.com/colouring-cities/colouring-core) as possible. This will help ensure consistency and enable data sharing between the various Colouring Cities projects, and will also allow us all to continue to improve the Core Platform. - -## Working with Forks -By using Forks, GitHub will maintain a link between your project and the Core platform. This will allow you to see any changes that are made to the Core repository and easily synchronise those changes into your own code, as shown below (as well as allowing you to contribute some of your code back to the Core platform). - -## Forking the Core Repository -We recommend that you create a "Fork" of the [colouring-core](https://github.com/colouring-cities/colouring-core) to create the repository for your Colouring Cities project, and then customise the code from the core platform to suit the needs of your projects. - -This can be done by going to the [Core Repository](https://github.com/colouring-cities/colouring-core), clicking the 'Fork' button, as show below and then following the instructions. - -![image](https://user-images.githubusercontent.com/21125422/224355892-7cc76027-6402-4fb1-b12b-7c41e3e4e55d.png) - -## Checking Project Status -On your project repository, you will then see that your project is forked from Colouring Core, and you will also be notified when changes are made to the Core platform, as shown in the example below. - -![image](https://user-images.githubusercontent.com/21125422/224358529-4ef5ac1d-50e2-467b-95aa-033e44cce7af.png) - -You can click on "Sync Fork" and then "Update Branch" to pull the latest changes from Colouring Core into your own project. - -## Customising your Colouring Cities Project -When it comes to customising the Colouring Core platform for use in your country/city, we want to make this as easy as possible, while still maintaining the brand identity of the platform. - -Where possible, customisations should be made using configuration files, rather than by modifying the source code. More information on the current configuration file setup can be found [here](configuring-colouring-cities.md). Please let us know (ideally by creating issues on the [Core repository](https://github.com/colouring-cities/colouring-core) ) if there are other elements that you would like us to add into this configuration framework.