Skip to content

Commit

Permalink
fix: Adjust links for docs that got moved to developers directory
Browse files Browse the repository at this point in the history
  • Loading branch information
robsavoye authored and dakotabenjamin committed Jan 29, 2024
1 parent f317695 commit 669efd2
Show file tree
Hide file tree
Showing 2 changed files with 79 additions and 29 deletions.
4 changes: 2 additions & 2 deletions docs/developers/contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ testing, please comment on the PR directly.

Create pull requests (PRs) for changes that you think are needed. We
would really appreciate your help! We ask that you follow our [coding
contribution guidelines](developers/contributing-guidelines.md)
contribution guidelines](contributing-guidelines.md)

Skills with the following would be beneficial:

Expand All @@ -76,7 +76,7 @@ Our latest task board can be found
## Translating

Review or submit [language
translations](developers/translations.md). Translations are important
translations](translations.md). Translations are important
as it makes Tasking Manager more efficient when it supports local
languages.

Expand Down
104 changes: 77 additions & 27 deletions docs/developers/development-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,9 @@ To learn React, check out the [React documentation](https://reactjs.org/).

### Backend

The backend is made up of a postgres database and an associated API that calls various end points to create tasks, manage task state, and produce analytics.
The backend is made up of a postgres database and an associated API
that calls various end points to create tasks, manage task state, and
produce analytics.

#### Dependencies

Expand All @@ -67,15 +69,22 @@ The backend is made up of a postgres database and an associated API that calls v
* [pip](https://pip.pypa.io/en/stable/installing/)
* [libgeos-dev](https://trac.osgeo.org/geos/)

You can check the [Dockerfile](../scripts/docker/tasking-manager/Dockerfile) to have a reference of how to install it in a Debian/Ubuntu system.
You can check the
[Dockerfile](https://github.com/hotosm/tasking-manager/blob/develop/Dockerfile)
to have a reference of how to install it in a Debian/Ubuntu system.

#### Configuration

There are two ways to configure Tasking Manager. You can set some environment variables on your shell or you can define the configuration in the `tasking-manager.env` file on the repository root directory. To use that last option, follow the below instructions:
There are two ways to configure Tasking Manager. You can set some
environment variables on your shell or you can define the
configuration in the `tasking-manager.env` file on the repository root
directory. To use that last option, follow the below instructions:

* Copy the example configuration file to start your own configuration: `cp example.env tasking-manager.env`.
* 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.
* Make sure that the following variables are set correctly in the `tasking-manager.env` configuration file:
* Make sure that the following variables are set correctly in the
`tasking-manager.env` configuration file:
- `TM_APP_BASE_URL`=web-server-endpoint
- `POSTGRES_DB`=tasking-manager-database-name
- `POSTGRES_USER`=database-user-name
Expand Down Expand Up @@ -113,7 +122,8 @@ In order to send email correctly, set these variables as well:

#### Tests

The project includes a suite of Unit and Integration tests that you should run after any changes
The project includes a suite of Unit and Integration tests that you
should run after any changes.

```
python3 -m unittest discover tests/backend
Expand All @@ -134,7 +144,13 @@ cd frontend && yarn build-locales

#### Create a fresh database

We use [Flask-Migrate](https://flask-migrate.readthedocs.io/en/latest/) to create the database from the migrations directory. Check the instructions on how to setup a PostGIS database with [docker](#creating-a-local-postgis-database-with-docker) or on your [local system](#non-docker). Then you can execute the following command to apply the migrations:
We use
[Flask-Migrate](https://flask-migrate.readthedocs.io/en/latest/) to
create the database from the migrations directory. Check the
instructions on how to setup a PostGIS database with
[docker](#creating-a-local-postgis-database-with-docker) or on your
[local system](#non-docker). Then you can execute the following
command to apply the migrations:

```
flask db upgrade
Expand All @@ -146,23 +162,35 @@ pdm run upgrade

#### Set permissions to create projects

To be able to create projects and have full permissions as an admin user inside TM, login to the TM with your OSM account to populate your user information in the database, then execute the following command on your terminal (with the OS user that is the owner of the database):
To be able to create projects and have full permissions as an admin
user inside TM, login to the TM with your OSM account to populate your
user information in the database, then execute the following command
on your terminal (with the OS user that is the owner of the database):

`psql -d <your_database> -c "UPDATE users set role = 1 where username = '<your_osm_username>'"`

### API

If you plan to only work on the API you only have to build the backend architecture. Install the backend dependencies, and run the server:
If you plan to only work on the API you only have to build the backend
architecture. Install the backend dependencies, and run the server:

`flask run --debug --reload` or `pdm run start`

You can access the API documentation on [http://localhost:5000/api-docs](http://localhost:5000/api-docs), it also allows you to execute requests on your local TM instance. The API docs is also available on our [production](https://tasks.hotosm.org/api-docs) and [staging](https://tasks-stage.hotosm.org/api-docs/) instances.
You can access the API documentation on
[http://localhost:5000/api-docs](http://localhost:5000/api-docs), it
also allows you to execute requests on your local TM instance. The API
docs is also available on our
[production](https://tasks.hotosm.org/api-docs) and
[staging](https://tasks-stage.hotosm.org/api-docs/) instances.

#### API Authentication

In order to authenticate on the API, you need to have an Authorization Token.

1. Run the command line `manage.py` via `flask` with the `gen_token` option and `-u <OSM_User_ID_number>`. The command line can be run in any shell session as long as you are in the tasking-manager directory.
1. Run the command line `manage.py` via `flask` with the `gen_token`
option and `-u <OSM_User_ID_number>`. The command line can be run
in any shell session as long as you are in the tasking-manager
directory.

```
flask gen_token -u 99999999
Expand All @@ -174,27 +202,38 @@ This will generate a line that looks like this:
2. In the Swagger UI, where it says
> Token sessionTokenHere==
replace `sessionTokenHere==` with the string of characters between the apostrophes (' ') above so you end up with something that looks like this in that field:
replace `sessionTokenHere==` with the string of characters between the
apostrophes (' ') above so you end up with something that looks like
this in that field:

> Token SWpFaS5EaEoxRlEubHRVC1DSTVJZ2hfalMc0xlalu3KRk5BUGk0
Your user must have logged in to the local testing instance once of course and have the needed permissions for the API call.
Your user must have logged in to the local testing instance once of
course and have the needed permissions for the API call.

You can get your OSM user id number either by finding it in your local testing/dev database `select * from users` or from OSM by viewing the edit history of your user, selecting a changeset from the list, and then at the bottom link `Changeset XML` and it will be in the `uid` field of the XML returned.
You can get your OSM user id number either by finding it in your local
testing/dev database `select * from users` or from OSM by viewing the
edit history of your user, selecting a changeset from the list, and
then at the bottom link `Changeset XML` and it will be in the `uid`
field of the XML returned.

#### API Authentication on remote instance

To get your token on the production or staging Tasking Manager instances, sign in in the browser and then either:

- go to the user profile page, enable _Expert mode_ in the settings, and copy the token from the _API Key_ section.
- inspect a network request and search for the `Authorization` field in the request headers section.
To get your token on the production or staging Tasking Manager
instances, sign in in the browser and then either:

- go to the user profile page, enable _Expert mode_ in the settings,
and copy the token from the _API Key_ section.
- inspect a network request and search for the `Authorization` field
in the request headers section.

# Docker

## Creating a local PostGIS database with Docker

If you're not able to connect to an existing tasking-manager DB, we have a [Dockerfile]() that will allow you to run PostGIS locally as follows.
If you're not able to connect to an existing tasking-manager DB, we
have a [Dockerfile]() that will allow you to run PostGIS locally as
follows.

### Dependencies

Expand All @@ -210,13 +249,15 @@ Following must be available locally:
docker build -t tasking-manager-db ./scripts/docker/postgis
`

2. The image should be downloaded and build locally. Once complete you should see it listed, with
2. The image should be downloaded and build locally. Once complete
you should see it listed, with

`
docker images
`

3. You can now run the image (this will run PostGIS in a docker container, with port 5432 mapped to localhost):
3. You can now run the image (this will run PostGIS in a docker
container, with port 5432 mapped to localhost):

`
docker run -d -p 5432:5432 tasking-manager-db
Expand All @@ -228,23 +269,29 @@ docker run -d -p 5432:5432 tasking-manager-db
docker ps
`

5. Finally you can set your env variable to point at your containerised DB:
5. Finally you can set your env variable to point at your
containerised DB:

`
export TM_DB=postgresql://hottm:hottm@localhost/tasking-manager
`

6. Refer to the rest of the instructions in the README to setup the DB and run the app
6. Refer to the rest of the instructions in the README to setup the
DB and run the app.

# Non-Docker

## Creating the PostGIS database

It may be the case you would like to set up the database without using Docker for one reason or another. This provides you with a set of commands to create the database and export the database address to allow you to dive into backend development.
It may be the case you would like to set up the database without using
Docker for one reason or another. This provides you with a set of
commands to create the database and export the database address to
allow you to dive into backend development.

### Dependencies

First, ensure that Postgresql and PostGIS are installed and running on your computer.
First, ensure that Postgresql and PostGIS are installed and running on
your computer.

### Create the database user and database

Expand All @@ -265,9 +312,12 @@ 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/).
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.
Clone the Tasking Manager repository and use `docker-compose up` to
get a working version of the API running.

## Sysadmins guide

Expand Down

0 comments on commit 669efd2

Please sign in to comment.