a_adli/colouring-montreal
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Remove more London-specific text from documentation

Browse Source
This commit is contained in:
Mike Simpson 2023-02-15 10:32:44 +00:00
parent 9a7c0d1a7d
commit bcee1d0ad1
3 changed files with 59 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.github/ISSUE_TEMPLATE/bug_report.md vendored
View File

@ -1,6 +1,6 @@
--- ---
name: Bug report name: Bug report
about: Describe a problem to help us improve Colouring London about: Describe a problem to help us improve Colouring Cities
title: '' title: ''
labels: '' labels: ''
assignees: '' assignees: ''

53
docs/setup-dev-environment.md
View File

@ -2,7 +2,10 @@
### WARNING: Setup document suitable for development environment, not production server ### 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 London 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. 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]'`.
<details> <details>
<summary> <summary>
@ -46,7 +49,7 @@ ssh <linuxusername>@localhost -p 4022
- [:tulip: Installing the tools and components](#tulip-installing-the-tools-and-components) - [:tulip: Installing the tools and components](#tulip-installing-the-tools-and-components)
- [:red_circle: Installing PostgreSQL](#red_circle-installing-postgresql) - [:red_circle: Installing PostgreSQL](#red_circle-installing-postgresql)
- [:rainbow: Installing Colouring London](#rainbow-installing-colouring-london) - [:rainbow: Installing Colouring Cities Core Platform](#rainbow-installing-colouring-cities-core-platform)
- [:arrow_down: Installing Node.js](#arrow_down-installing-nodejs) - [:arrow_down: Installing Node.js](#arrow_down-installing-nodejs)
- [:large_blue_circle: Configuring PostgreSQL](#large_blue_circle-configuring-postgresql) - [:large_blue_circle: Configuring PostgreSQL](#large_blue_circle-configuring-postgresql)
- [:space_invader: Create an empty database](#space_invader-create-an-empty-database) - [:space_invader: Create an empty database](#space_invader-create-an-empty-database)
@ -99,15 +102,15 @@ and additional geo-spatial tools
sudo apt-get install -y gdal-bin libspatialindex-dev libgeos-dev libproj-dev sudo apt-get install -y gdal-bin libspatialindex-dev libgeos-dev libproj-dev
``` ```
### :rainbow: Installing Colouring London ### :rainbow: Installing Colouring Cities Core Platform
Now clone the `colouring-london` codebase. Now clone the `colouring-core` codebase.
```bash ```bash
cd ~ && git clone https://github.com/colouring-cities/colouring-london.git 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-london` and modify the path if appropriate. **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 ### :arrow_down: Installing Node.js
@ -185,7 +188,7 @@ sudo -u postgres psql -c "SELECT 1 FROM pg_user WHERE usename = '<username>';" |
``` ```
<details> <details>
<summary>Note for "Colouring London" devs</summary><p></p> <summary>Note for "Colouring Cities" devs</summary><p></p>
If you intend to load the full CL database from a dump file into your dev environment, run the above `psql` command with `<username>` as "cldbadmin" and use that username in subsequent steps, but also run the above a second time with `<username>` as "clwebapp" (see section [:house: Loading the building data](#house-loading-the-building-data) for more details). If you intend to load the full CL database from a dump file into your dev environment, run the above `psql` command with `<username>` as "cldbadmin" and use that username in subsequent steps, but also run the above a second time with `<username>` as "clwebapp" (see section [:house: Loading the building data](#house-loading-the-building-data) for more details).
@ -193,7 +196,7 @@ If you intend to load the full CL database from a dump file into your dev enviro
### :space_invader: Create an empty database ### :space_invader: Create an empty database
Now create an empty database configured with geo-spatial tools. The database name (`<colouringlondondb>`) is arbitrary. Now create an empty database configured with geo-spatial tools. The database name (`<colouringcitiesdb>`) is arbitrary.
Set environment variables, which will simplify running subsequent `psql` commands. Set environment variables, which will simplify running subsequent `psql` commands.
@ -201,13 +204,13 @@ Set environment variables, which will simplify running subsequent `psql` command
export PGPASSWORD=<pgpassword> export PGPASSWORD=<pgpassword>
export PGUSER=<username> export PGUSER=<username>
export PGHOST=localhost export PGHOST=localhost
export PGDATABASE=<colouringlondondb> export PGDATABASE=<colouringcitiesdb>
``` ```
Create the database. Create the database.
```bash ```bash
sudo -u postgres psql -c "SELECT 1 FROM pg_database WHERE datname = '<colouringlondondb>';" | grep -q 1 || sudo -u postgres createdb -E UTF8 -T template0 --locale=en_US.utf8 -O <username> <colouringlondondb> 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 <username> <colouringcitiesdb>
``` ```
```bash ```bash
@ -230,7 +233,7 @@ Now install the required Node packages. This needs to done from the `app` direct
local repository, so that it can read from the `package.json` file. local repository, so that it can read from the `package.json` file.
```bash ```bash
cd ~/colouring-london/app cd ~/colouring-core/app
npm install npm install
``` ```
@ -244,7 +247,7 @@ sudo apt-get install -y python3 python3-pip python3-dev python3-venv
## :house: Loading the building data ## :house: Loading the building data
There are several ways to create the Colouring London 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). 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: To create the full database from scratch, follow [these instructions](../etl/README.md), otherwise choose one of the following:
@ -256,7 +259,7 @@ If you are a developer on the Colouring London project (or another Colouring Cit
Log into the environment where your production database is kept and create a dump file from the db. Log into the environment where your production database is kept and create a dump file from the db.
```bash ```bash
pg_dump <colouringlondondb> > <dumpfile> pg_dump <colouringcitiesdb> > <dumpfile>
``` ```
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)). 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)).
@ -269,7 +272,7 @@ psql < <dumpfile>
Alternatively, if you get errors using the above command, use pg_restore: Alternatively, if you get errors using the above command, use pg_restore:
```bash ```bash
pg_restore -d <colouringlondondb> <dumpfile> pg_restore -d <colouringcitiesdb> <dumpfile>
``` ```
#### Run migrations #### Run migrations
@ -278,13 +281,13 @@ Now run all 'up' migrations to create tables, data types, indexes etc. The `.sql
do this are located in the `migrations` folder of your local repository. do this are located in the `migrations` folder of your local repository.
```bash ```bash
ls ~/colouring-london/migrations/*.up.sql 2>/dev/null | while read -r migration; do psql < $migration; done; 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 Again, if you get errors, you may need to manually specify the database name
```bash ```bash
ls ~/colouring-london/migrations/*.up.sql 2>/dev/null | while read -r migration; do psql -d <colouringlondondb> < $migration; done; ls ~/colouring-core/migrations/*.up.sql 2>/dev/null | while read -r migration; do psql -d <colouringcitiesdb> < $migration; done;
``` ```
</details> </details>
@ -295,17 +298,17 @@ This section shows how to load test buildings into the application from OpenStre
#### Load OpenStreetMap test polygons #### 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 *colouringlondon* but it can have any name. 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 ```bash
cd ~/colouring-london/etl cd ~/colouring-core/etl
pyvenv colouringlondon pyvenv colouringcities
``` ```
Activate the virtual environment so we can install python packages into it. Activate the virtual environment so we can install python packages into it.
```bash ```bash
source colouringlondon/bin/activate source colouringcities/bin/activate
``` ```
Install python pip package manager and related tools. Install python pip package manager and related tools.
@ -321,7 +324,7 @@ Install the required python packages.
pip install -r requirements.txt pip install -r requirements.txt
``` ```
To help test the Colouring London 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. 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.
Download the test data. Download the test data.
@ -341,7 +344,7 @@ Now run all 'up' migrations to create tables, data types, indexes etc. The `.sql
do this are located in the `migrations` folder of your local repository. do this are located in the `migrations` folder of your local repository.
```bash ```bash
ls ~/colouring-london/migrations/*.up.sql 2>/dev/null | while read -r migration; do psql < $migration; done; ls ~/colouring-core/migrations/*.up.sql 2>/dev/null | while read -r migration; do psql < $migration; done;
``` ```
#### Load buildings #### Load buildings
@ -366,7 +369,7 @@ Now we are ready to run the application.
First enter the app directory. First enter the app directory.
```bash ```bash
cd ~/colouring-london/app cd ~/colouring-core/app
``` ```
Then create a folder for the tilecache. Then create a folder for the tilecache.
@ -380,7 +383,7 @@ Create some additional variables for running the application (the `APP_COOKIE_SE
```bash ```bash
export PGPORT=5432 export PGPORT=5432
export APP_COOKIE_SECRET=123456 export APP_COOKIE_SECRET=123456
export TILECACHE_PATH=~/colouring-london/app/tilecache export TILECACHE_PATH=~/colouring-core/app/tilecache
``` ```
Finally, simply run the application with npm. Finally, simply run the application with npm.
@ -396,7 +399,7 @@ Specify variables
</summary> </summary>
```bash ```bash
PGPASSWORD=<pgpassword> PGDATABASE=<colouringlondondb> PGUSER=<username> PGHOST=localhost PGPORT=5432 APP_COOKIE_SECRET=123456 TILECACHE_PATH=~/colouring-london/app/tilecache npm start PGPASSWORD=<pgpassword> PGDATABASE=<colouringcitiesdb> PGUSER=<username> PGHOST=localhost PGPORT=5432 APP_COOKIE_SECRET=123456 TILECACHE_PATH=~/colouring-core/app/tilecache npm start
``` ```
</details><p></p> </details><p></p>

58
docs/setup-production-environment.md
View File

@ -1,5 +1,7 @@
# Setting Up A Production Environment # 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 #### Preliminaries
@ -42,13 +44,13 @@ Install Nginx
`sudo apt install nginx` `sudo apt install nginx`
Clone the remote Colouring London GitHub repository into `/var/www` Clone the remote Colouring Cities GitHub repository into `/var/www`
`cd /var/www` `cd /var/www`
`sudo git clone https://github.com/colouring-cities/colouring-core.git` `sudo git clone https://github.com/colouring-cities/colouring-core.git`
Create a system user (`nodeapp`) to `chown` the `colouring-london` directory Create a system user (`nodeapp`) to `chown` the `colouring-core` directory
`useradd -r -s /bin/nologin nodeapp` `useradd -r -s /bin/nologin nodeapp`
@ -56,13 +58,13 @@ Add the current user to the `nodeapp` group
`sudo usermod -a -G nodeapp <your_ubuntu_username>` `sudo usermod -a -G nodeapp <your_ubuntu_username>`
Make the `nodeapp` user/group `chown` the `colouring-london` directory and its subdirectories Make the `nodeapp` user/group `chown` the `colouring-core` directory and its subdirectories
`sudo chown -R nodeapp:nodeapp /var/www/colouring-london` `sudo chown -R nodeapp:nodeapp /var/www/colouring-core`
Now set appropriate permissions on the `colouring-london` directory Now set appropriate permissions on the `colouring-core` directory
`sudo chmod -R 775 /var/www/colouring-london` `sudo chmod -R 775 /var/www/colouring-core`
*** ***
@ -121,7 +123,7 @@ Now upgrade the `npm` package manager to the most recent release with global pri
Now install the required Node packages as designated in `package.json` Now install the required Node packages as designated in `package.json`
`cd /var/www/colouring-london/app && npm install` `cd /var/www/colouring-core/app && npm install`
*** ***
@ -152,20 +154,20 @@ Create a distinct Postgres user
`sudo -u postgres psql -c "SELECT 1 FROM pg_user WHERE usename = '<postgres_username>';" | grep -q 1 || sudo -u postgres psql -c "CREATE ROLE <postgres_username> SUPERUSER LOGIN PASSWORD '<postgres_password>';"` `sudo -u postgres psql -c "SELECT 1 FROM pg_user WHERE usename = '<postgres_username>';" | grep -q 1 || sudo -u postgres psql -c "CREATE ROLE <postgres_username> SUPERUSER LOGIN PASSWORD '<postgres_password>';"`
Create default colouring london database Create default colouring cities database
`sudo -u postgres psql -c "SELECT 1 FROM pg_database WHERE datname = 'colouringlondondb';" | grep -q 1 || sudo -u postgres createdb -E UTF8 -T template0 --locale=en_US.utf8 -O <postgres_username> colouringlondondb` `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 <postgres_username> colouringcitiesdb`
`psql -d colouringlondondb -U <postgres_username> -c "create extension postgis;"` `psql -d colouringcitiesdb -U <postgres_username> -c "create extension postgis;"`
`psql -d colouringlondondb -U <postgres_username> -c "create extension pgcrypto;"` `psql -d colouringcitiesdb -U <postgres_username> -c "create extension pgcrypto;"`
`psql -d colouringlondondb -U <postgres_username> -c "create extension pg_trgm;"` `psql -d colouringcitiesdb -U <postgres_username> -c "create extension pg_trgm;"`
Import data from the most recent colouring london database dump Import data from the most recent colouring cities database dump
`pg_restore --no-privileges --no-owner --username "<postgres_username>" --dbname "colouringlondondb" --clean "<path/to/database/dump/file>"` `pg_restore --no-privileges --no-owner --username "<postgres_username>" --dbname "colouringcitiesdb" --clean "<path/to/database/dump/file>"`
*** ***
@ -196,7 +198,7 @@ Now edit `sites-available/default` to create a minimal Nginx configuration to te
server { server {
listen 80 default_server; listen 80 default_server;
listen [::]:80 default_server; listen [::]:80 default_server;
server_name colouring-london; server_name colouring-core;
location / { location / {
proxy_pass http://localhost:3000/; proxy_pass http://localhost:3000/;
@ -220,19 +222,19 @@ If all is well, restart Nginx
Test out the configuration Test out the configuration
`cd /var/www/colouring-london/app` `cd /var/www/colouring-core/app`
`npm run build` `npm run build`
`PGPASSWORD=<postgres_password> PGDATABASE=colouringlondondb PGUSER=<postgres_username> PGHOST=localhost PGPORT=5432 APP_COOKIE_SECRET=<secret> npm run start:prod` `PGPASSWORD=<postgres_password> PGDATABASE=colouringcitiesdb PGUSER=<postgres_username> PGHOST=localhost PGPORT=5432 APP_COOKIE_SECRET=<secret> npm run start:prod`
Now open a browser window on a client machine and navigate to the IP Address of your VM Now open a browser window on a client machine and navigate to the IP Address of your VM
`http://<ip_address_of_vm>` `http://<ip_address_of_vm>`
You should see the Colouring London homepage. You should see the Colouring Cities homepage.
*** ***
@ -255,7 +257,7 @@ Perform a global install of PM2
Create an `ecosystem.config.js` file from the template file Create an `ecosystem.config.js` file from the template file
`cd /var/www/colouring-london` `cd /var/www/colouring-core`
`nano ecosystem.config.template.js` `nano ecosystem.config.template.js`
@ -268,18 +270,18 @@ Create an `ecosystem.config.js` file from the template file
module.exports = { module.exports = {
apps: [ apps: [
{ {
name: "colouringlondon", name: "colouringcities",
script: "./app/build/server.js", script: "./app/build/server.js",
instances: 6, instances: 6,
env: { env: {
NODE_ENV: "production", NODE_ENV: "production",
PGHOST: "localhost", PGHOST: "localhost",
PGPORT: 5432, PGPORT: 5432,
PGDATABASE: "colouringlondondb", PGDATABASE: "colouringcitiesdb",
PGUSER: "<postgres_username>", PGUSER: "<postgres_username>",
PGPASSWORD: "<postgres_password>", PGPASSWORD: "<postgres_password>",
APP_COOKIE_SECRET: "<longrandomsecret>", APP_COOKIE_SECRET: "<longrandomsecret>",
TILECACHE_PATH: "/var/www/colouring-london/app/tilecache" TILECACHE_PATH: "/var/www/colouring-core/app/tilecache"
} }
} }
] ]
@ -288,9 +290,9 @@ Create an `ecosystem.config.js` file from the template file
Edit the above file as appropriate and save as `ecosystem.config.js` Edit the above file as appropriate and save as `ecosystem.config.js`
Start the colouring-london app Start the colouring-core app
`cd /var/www/colouring-london` `cd /var/www/colouring-core`
`pm2 start ecosystem.config.js` `pm2 start ecosystem.config.js`
@ -298,9 +300,9 @@ Open a browser window on a client machine and navigate to the IP Address of your
`http://<ip_address_of_vm>` `http://<ip_address_of_vm>`
You should see the Colouring London homepage. You should see the Colouring Cities homepage.
To stop the colouring-london app type: To stop the colouring-core app type:
`pm2 stop ecosystem.config.js` `pm2 stop ecosystem.config.js`
@ -311,14 +313,14 @@ To stop the colouring-london app type:
Install requirements for the maintenance Python scripts Install requirements for the maintenance Python scripts
`cd /var/www/colouring-london/maintenance` `cd /var/www/colouring-core/maintenance`
`sudo pip3 install -r requirements.txt` `sudo pip3 install -r requirements.txt`
The maintenance scripts might need environment variables present at the time of execution, notably the database connection details. 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 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-london/downloads python3 maintenance/extract_data/extract_data.py` `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. 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.