diff --git a/docker-compose.override.yml b/docker-compose.override.yml deleted file mode 100644 index 86f7d7ce89..0000000000 --- a/docker-compose.override.yml +++ /dev/null @@ -1,30 +0,0 @@ -# To use this file, run `docker-compose up`. -version: '3.4' - -x-backend-config: &backend - build: - context: "." - dockerfile: "./scripts/docker/Dockerfile.backend" - -services: - # Main application - backend: - <<: *backend - volumes: - - .:/usr/src/app - - # Migration service - migration: - <<: *backend - volumes: - - .:/usr/src/app - - frontend: - build: - context: "." - dockerfile: "./scripts/docker/Dockerfile.frontend" - volumes: - - ".:/usr/src/app" - labels: - - traefik.http.routers.frontend.rule=Host(`localhost`) - - traefik.http.services.frontend.loadbalancer.server.port=80 diff --git a/docker-compose.traefik.yml b/docker-compose.traefik.yml new file mode 100644 index 0000000000..5f2d2f5a56 --- /dev/null +++ b/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 + diff --git a/docker-compose.yml b/docker-compose.yml index 1032c4b914..735c5b2b6c 100644 --- a/docker-compose.yml +++ b/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 diff --git a/docs/assets/osm-oauth-settings.jpg b/docs/assets/osm-oauth-settings.jpg index b62bfe883f..7b715e8858 100644 Binary files a/docs/assets/osm-oauth-settings.jpg and b/docs/assets/osm-oauth-settings.jpg differ diff --git a/docs/setup-development.md b/docs/setup-development.md index c96b881d1a..29e2e5067d 100644 --- a/docs/setup-development.md +++ b/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. diff --git a/docs/setup-docker.md b/docs/setup-docker.md index c9ee684578..556ff56ed6 100644 --- a/docs/setup-docker.md +++ b/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//oauth_clients/new` and fill in the form: -#### Persistent data +Required OSM OAuth settings -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//oauth_clients/new` and fill in the form: +### Public host -Required OSM OAuth settings +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 ``` diff --git a/example.env b/example.env index f62e54a05a..c4b9d4b82e 100644 --- a/example.env +++ b/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