Make docker defaults more useful for local testing setup and update documentation

docker-compose.traefik.yml

@@ -0,0 +1,24 @@
+services:
+  traefik:
+    image: traefik:v2.3
+    restart: unless-stopped
+    ports:
+      - "80:80"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+    command:
+      - --entrypoints.web.address=:80
+      - --providers.docker=true
+    networks:
+      - tm-web
+
+  frontend:
+    labels:
+      - traefik.http.routers.frontend.rule=Host(`localhost`)
+      - traefik.http.services.frontend.loadbalancer.server.port=80
+
+  backend:
+    labels:
+      - traefik.http.routers.backend.rule=Host(`localhost`) && PathPrefix(`/api/`)
+      - traefik.http.services.backend.loadbalancer.server.port=5000
+

docker-compose.yml

@@ -1,62 +1,59 @@
 # To use this file, run `docker-compose up`.
 version: "3.4"
 
-x-backend-config: &backend
-  image: hotosm-tasking-manager:backend
+x-template-config: &template
+  build:
+    context: "."
+    dockerfile: "./scripts/docker/Dockerfile.backend"
+  image: hotosm-tasking-manager:base
   env_file: ${ENV_FILE:-tasking-manager.env}
+  volumes:
+    - .:/usr/src/app
   depends_on:
     - postgresql
-  links:
-    - postgresql
   networks:
     - tm-web
 
 services:
   # Main application
   backend:
-    <<: *backend
-    container_name: backend
-    restart: always
-    labels:
-      - traefik.http.routers.backend.rule=Host(`localhost`) && PathPrefix(`/api/`)
-      - traefik.http.services.backend.loadbalancer.server.port=5000
+    <<: *template
+    container_name: tm_backend
+    restart: unless-stopped
+    ports:
+      - 5000:5000
 
   migration:
-    <<: *backend
-    container_name: migration
+    <<: *template
+    container_name: tm_migration
     restart: on-failure
     command: python manage.py db upgrade
+    depends_on:
+      - backend
 
   frontend:
+    container_name: tm_frontend
+    build:
+      context: "."
+      dockerfile: "./scripts/docker/Dockerfile.frontend"
     image: hotosm-tasking-manager:frontend
-    restart: always
+    volumes:
+      - .:/usr/src/app
+    restart: unless-stopped
+    depends_on:
+      - backend
+    ports:
+      - 3000:80
     networks:
       - tm-web
-    labels:
-      - traefik.http.routers.frontend.rule=Host(`localhost`)
-      - traefik.http.services.frontend.loadbalancer.server.port=80
 
   postgresql:
     image: mdillon/postgis:11
     container_name: postgresql
-    restart: always
+    restart: unless-stopped
     env_file: ${ENV_FILE:-tasking-manager.env}
     networks:
       - tm-web
 
-  traefik:
-    image: traefik:v2.3
-    restart: always
-    ports:
-      - "80:80"
-    volumes:
-      - /var/run/docker.sock:/var/run/docker.sock:ro
-    command:
-      - --entrypoints.web.address=:80
-      - --providers.docker=true
-    networks:
-      - tm-web
-
 networks:
   tm-web:
-    external: true

docs/setup-development.md

@@ -1,6 +1,9 @@
 
 ## Development setup
 
+IN the following your will learn how to install and set up Tasking Manager locally. **Alternatively** you can review how to install a [dockerised setup](./setup-docker.md). That documentation may also complement the following in some aspects.
+
+
 ### Architecture
 
 The Tasking Manager is composed of two parts:
@@ -248,7 +251,3 @@ Finally, add the environmental variable to access the database:
 export TM_DB=postgresql://hottm:hottm@localhost/tasking-manager
 `
 
-
-It is possible to install and run the Tasking Manager using [Docker](https://docker.com) and [Docker Compose](https://docs.docker.com/compose/).
-
-Clone the Tasking Manager repository and use `docker-compose up` to get a working version of the API running.

docs/setup-docker.md

@@ -1,69 +1,79 @@
-## Installation with Docker
+# Installation with Docker
 
-### Get the code
+This requires [Docker](https://docs.docker.com/get-started/) and [Docker Compose](https://docs.docker.com/compose/) to be installed on your system. **Alternatively** you can review how to install a local [development setup](./setup-development.md). That documentation may also complement the following in some aspects.
+
+## Get the code
 
 `git clone https://github.com/hotosm/tasking-manager.git`.
 
-### Configure
+## Configure
 
 * Copy the example configuration file to start your own configuration: `cp example.env tasking-manager.env`.
-* Adjust the `tasking-manager.env` configuration file to fit your configuration.
+* Adjust the `tasking-manager.env` configuration file to fit your configuration. The defaults will create a working local test setup.
 
-#### Public host
+### Authenticate with OpenStreetMap
 
-By default, things are made to work from `localhost`.  If you want to setup a public host, try setting the following:
+The Tasking Manager uses OpenStreetMap accounts for users to login.
 
-* `tasking-manager.env`: `TM_APP_BASE_URL=https://tasks.smartcitiestransport.com/`
-* `docker-compose.override.yml`:
-  * `TM_APP_API_URL=https://tasks.smartcitiestransport.com/api`
-  * ```traefik.http.routers.frontend.rule=Host(`localhost`, `tasks.smartcitiestransport.com`)```
-* `docker-compose.yml`:
-  * ```traefik.http.routers.backend.rule=Host(`localhost`, `tasks.smartcitiestransport.com`) && PathPrefix(`/api/`)```
-  * ```traefik.http.routers.frontend.rule=Host(`localhost`, `tasks.smartcitiestransport.com`)```
+In order to configure this connection you have to go to `https://www.openstreetmap.org/user/<Your_OSM_UserName>/oauth_clients/new` and fill in the form:
 
-#### Persistent data
+<img width="300" alt="Required OSM OAuth settings" src="./assets/osm-oauth-settings.jpg">
 
-If you may be removing and starting the postgresql container, you may want to setup a persistent volume:
+Afterwards copy the consumer key and secret from OpenStreetMap into your configuration file `tasking-manager.env`, and set the two variables: `TM_CONSUMER_KEY` and `TM_CONSUMER_SECRET`.
 
-In `docker-compose.override.yml`:
-
-```yaml
-services:
-  postgresql:
-    volumes:
-      - "postgresql-data:/var/lib/postgresql/data"
+**NB**: if you've configured a custom OSM server, make sure that you create the user and oAuth client there.
 
-volumes:
-  postgresql-data:
-```
+## Run the Tasking Manager
+
+* One command to get everything together and start the Tasking Manager: `docker-compose up -d`
+* Visit with your browser [http://localhost:3000](http://localhost:3000)
+  * The API is available at [http://localhost:5000](http://localhost:5000/api-docs).
 
-#### Connect with OpenStreetMap
+Stop the containers with: `docker-compose down` or access the logs with `docker-compose logs -f`
 
-The Tasking Manager uses OpenStreetMap accounts for users to login. 
+Some functionality in the Tasking Manager and the API need special privileges. You can promote yourself to _Administrator_ after your first login, if you want to use this advanced functionality on your local instance. Log in to the backed database (see below) and change your users _role_ in the *Users* table to **1**.
 
-In order to configure this connection you have to go to `https://www.openstreetmap.org/user/<Your_OSM_UserName>/oauth_clients/new` and fill in the form:
+### Public host
 
-<img width="300" alt="Required OSM OAuth settings" src="./assets/osm-oauth-settings.jpg">
+By default, things are made to work from `localhost`. If you want to setup a public host in production, at least the following settings need to be adapted:
 
-Afterwards copy the consumer key and secret from OpenStreetMap into your configuration file `tasking-manager.env`, and set the two variables: `TM_CONSUMER_KEY` and `TM_CONSUMER_SECRET`.
+* `tasking-manager.env`:
+  * `TM_APP_BASE_URL=https://your_domain:3000` e.g. `TM_APP_BASE_URL=https://tasks.smartcitiestransport.com:3000`
+  * `TM_APP_API_URL=https://your_domain:5000`
+
+Yet, we suggest to use a reverse proxy like [traefik](https://traefik.io/traefik/) to route your traffic and expose the frontend and the api both behind port 80 under different paths. See [docker-compose.traefik.yaml](../docker-compose.traefik.yaml) for an example on how to configure it. Run `docker-compose -f docker-compose.yml -f docker-compose.traefik.yml up -d` and visit [http://localhost](http://localhost) to see it in action. Make sure to update `tasking-manager.env` accordingly.
 
-**NB**: if you've configured a custom OSM server, make sure that you create the user and oAuth client there. 
+### Backend database
 
-### Run the Tasking Manager
+#### Persistent data
 
-The **easiest way** to run the Tasking Manager requires [Docker](https://docs.docker.com/get-started/) and [Docker Compose](https://docs.docker.com/compose/) to be installed on your system.  Afterwards you'll just need:
+If you may be removing and starting the postgresql container, you may want to setup a persistent volume:
 
-* One command to get everything together and start the Tasking Manager: `docker-compose up -d`
-* Visit with your browser `http://127.0.0.1:5000`
+In `docker-compose.override.yml`:
 
-For stopping this command do the job: `docker-compose stop`
-And you can check the logs with `docker-compose logs -f`
+```yaml
+services:
+  postgresql:
+    volumes:
+      - "./postgresql-data:/var/lib/postgresql/data"
+```
 
-**Alternatively** you can review how to install a [development setup](./setup-development.md).
+#### Database access
+
+To access the backend database, you need to make it available on your host machine:
+
+In `docker-compose.override.yml`:
+
+```yaml
+services:
+  postgresql:
+    ports:
+      - a_free_port_on_your_host:5432
+```
 
-### Working with the setup
+# Using make
 
-The Tasking Manager Docker setup comes with pre-built client modules and backend requirements. To start all required services to run tasking manager locally, run
+The most common docker actions are available in a [make](https://www.gnu.org/software/make/) script for convenience. To start all required services to run tasking manager locally, run
 ```
 make up
 ```

example.env

@@ -5,14 +5,14 @@
 
 # The TM_APP_BASE_URL defines the URL of the frontend and is used by the backend
 # to configure links on emails and some authentication callbacks.
-# On development instances it should be 127.0.0.1:3000 or localhost:3000
-# On production instances, use the public URL of your frontend
+# On development instances it should be 127.0.0.1:3000 or localhost:3000 .
+# On production instances, use the public URL of your frontend.
 TM_APP_BASE_URL=http://127.0.0.1:3000
 
 # The TM_APP_API_URL defines the URL of your backend server. It will be used by
 # both the backend and by the frontend
 # On development instances it should be 127.0.0.1:5000 or localhost:5000
-# On production instances, use the public URL of your backend
+# On production instances, use the public URL of your backend.
 TM_APP_API_URL=http://127.0.0.1:5000
 
 # Defines the version of the API and will be used after /api/ on the url