forked from hotosm/fAIr
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request hotosm#146 from chrischank/backend_doc
Backend doc
- Loading branch information
Showing
4 changed files
with
314 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,82 @@ | ||
| <mxfile host="Electron" modified="2023-07-19T12:16:04.547Z" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/21.6.1 Chrome/112.0.5615.204 Electron/24.6.1 Safari/537.36" etag="Il54UgweenfTROzOarhm" version="21.6.1" type="device"> | ||
| <diagram name="Page-1" id="OO4K778CETOuQoV__ca2"> | ||
| <mxGraphModel dx="2074" dy="1239" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0"> | ||
| <root> | ||
| <mxCell id="0" /> | ||
| <mxCell id="1" parent="0" /> | ||
| <mxCell id="vAqhMZnTHLHm_gmnuPH0-4" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=0.5;entryY=0;entryDx=0;entryDy=0;entryPerimeter=0;exitX=0.25;exitY=1;exitDx=0;exitDy=0;" edge="1" parent="1" source="vAqhMZnTHLHm_gmnuPH0-1" target="vAqhMZnTHLHm_gmnuPH0-3"> | ||
| <mxGeometry relative="1" as="geometry" /> | ||
| </mxCell> | ||
| <mxCell id="vAqhMZnTHLHm_gmnuPH0-9" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;exitX=0.75;exitY=1;exitDx=0;exitDy=0;" edge="1" parent="1" source="vAqhMZnTHLHm_gmnuPH0-1" target="vAqhMZnTHLHm_gmnuPH0-2"> | ||
| <mxGeometry relative="1" as="geometry" /> | ||
| </mxCell> | ||
| <mxCell id="vAqhMZnTHLHm_gmnuPH0-1" value="backend<br>Geodjango" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="1"> | ||
| <mxGeometry x="354" y="260" width="120" height="60" as="geometry" /> | ||
| </mxCell> | ||
| <mxCell id="vAqhMZnTHLHm_gmnuPH0-21" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="vAqhMZnTHLHm_gmnuPH0-2" target="vAqhMZnTHLHm_gmnuPH0-7"> | ||
| <mxGeometry relative="1" as="geometry" /> | ||
| </mxCell> | ||
| <mxCell id="vAqhMZnTHLHm_gmnuPH0-2" value="fAIr-Utilities" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="1"> | ||
| <mxGeometry x="490" y="570" width="120" height="60" as="geometry" /> | ||
| </mxCell> | ||
| <mxCell id="vAqhMZnTHLHm_gmnuPH0-3" value="Redis" style="shape=cylinder3;whiteSpace=wrap;html=1;boundedLbl=1;backgroundOutline=1;size=15;" vertex="1" parent="1"> | ||
| <mxGeometry x="330" y="440" width="60" height="80" as="geometry" /> | ||
| </mxCell> | ||
| <mxCell id="vAqhMZnTHLHm_gmnuPH0-6" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;shape=link;" edge="1" parent="1" source="vAqhMZnTHLHm_gmnuPH0-5" target="vAqhMZnTHLHm_gmnuPH0-3"> | ||
| <mxGeometry relative="1" as="geometry"> | ||
| <Array as="points"> | ||
| <mxPoint x="410" y="480" /> | ||
| </Array> | ||
| </mxGeometry> | ||
| </mxCell> | ||
| <mxCell id="vAqhMZnTHLHm_gmnuPH0-20" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="vAqhMZnTHLHm_gmnuPH0-5" target="vAqhMZnTHLHm_gmnuPH0-19"> | ||
| <mxGeometry relative="1" as="geometry" /> | ||
| </mxCell> | ||
| <mxCell id="vAqhMZnTHLHm_gmnuPH0-5" value="Celery<br>(Queue Operations)" style="shape=parallelogram;perimeter=parallelogramPerimeter;whiteSpace=wrap;html=1;fixedSize=1;" vertex="1" parent="1"> | ||
| <mxGeometry x="338" y="790" width="152" height="80" as="geometry" /> | ||
| </mxCell> | ||
| <mxCell id="vAqhMZnTHLHm_gmnuPH0-22" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=1;entryY=0.5;entryDx=0;entryDy=0;shape=link;" edge="1" parent="1" source="vAqhMZnTHLHm_gmnuPH0-7" target="vAqhMZnTHLHm_gmnuPH0-5"> | ||
| <mxGeometry relative="1" as="geometry"> | ||
| <Array as="points"> | ||
| <mxPoint x="550" y="830" /> | ||
| </Array> | ||
| </mxGeometry> | ||
| </mxCell> | ||
| <mxCell id="vAqhMZnTHLHm_gmnuPH0-7" value="RAMP<br>(CNN)" style="ellipse;shape=cloud;whiteSpace=wrap;html=1;" vertex="1" parent="1"> | ||
| <mxGeometry x="490" y="670" width="120" height="80" as="geometry" /> | ||
| </mxCell> | ||
| <mxCell id="vAqhMZnTHLHm_gmnuPH0-24" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;exitPerimeter=0;entryX=0;entryY=0;entryDx=0;entryDy=0;shape=link;" edge="1" parent="1" source="vAqhMZnTHLHm_gmnuPH0-10" target="vAqhMZnTHLHm_gmnuPH0-5"> | ||
| <mxGeometry relative="1" as="geometry" /> | ||
| </mxCell> | ||
| <mxCell id="vAqhMZnTHLHm_gmnuPH0-10" value="OSM DB<br>(PostgresSQL)" style="shape=cylinder3;whiteSpace=wrap;html=1;boundedLbl=1;backgroundOutline=1;size=15;" vertex="1" parent="1"> | ||
| <mxGeometry x="240" y="650" width="100" height="120" as="geometry" /> | ||
| </mxCell> | ||
| <mxCell id="vAqhMZnTHLHm_gmnuPH0-15" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;entryPerimeter=0;" edge="1" parent="1" target="vAqhMZnTHLHm_gmnuPH0-3"> | ||
| <mxGeometry relative="1" as="geometry"> | ||
| <mxPoint x="240" y="480" as="sourcePoint" /> | ||
| </mxGeometry> | ||
| </mxCell> | ||
| <mxCell id="vAqhMZnTHLHm_gmnuPH0-17" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.25;exitY=1;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;shape=link;" edge="1" parent="1" target="vAqhMZnTHLHm_gmnuPH0-5"> | ||
| <mxGeometry relative="1" as="geometry"> | ||
| <mxPoint x="127.5" y="550" as="sourcePoint" /> | ||
| <Array as="points"> | ||
| <mxPoint x="125" y="830" /> | ||
| </Array> | ||
| </mxGeometry> | ||
| </mxCell> | ||
| <mxCell id="vAqhMZnTHLHm_gmnuPH0-13" value="Request" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;labelBorderColor=none;" vertex="1" parent="1"> | ||
| <mxGeometry x="140" y="630" width="60" height="30" as="geometry" /> | ||
| </mxCell> | ||
| <mxCell id="vAqhMZnTHLHm_gmnuPH0-23" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.75;exitY=1;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;entryPerimeter=0;" edge="1" parent="1" source="vAqhMZnTHLHm_gmnuPH0-18" target="vAqhMZnTHLHm_gmnuPH0-10"> | ||
| <mxGeometry relative="1" as="geometry" /> | ||
| </mxCell> | ||
| <mxCell id="vAqhMZnTHLHm_gmnuPH0-18" value="<table border="1" width="100%" height="100%" cellpadding="4" style="width:100%;height:100%;border-collapse:collapse;"><tbody><tr><th align="center">Users</th></tr><tr><td align="center">User 1<br>User 2<br>User 3</td></tr></tbody></table>" style="text;html=1;whiteSpace=wrap;strokeColor=#666666;fillColor=#f5f5f5;overflow=fill;fontColor=#333333;" vertex="1" parent="1"> | ||
| <mxGeometry x="90" y="410" width="150" height="140" as="geometry" /> | ||
| </mxCell> | ||
| <mxCell id="vAqhMZnTHLHm_gmnuPH0-19" value="<table border="1" width="100%" height="100%" cellpadding="4" style="width:100%;height:100%;border-collapse:collapse;"><tbody><tr><th align="center">Users / AWS instance</th></tr><tr><td align="center">Instance 1<br>Instance 2<br>Instance 3</td></tr></tbody></table>" style="text;html=1;whiteSpace=wrap;strokeColor=#666666;fillColor=#f5f5f5;overflow=fill;fontColor=#333333;" vertex="1" parent="1"> | ||
| <mxGeometry x="339" y="920" width="150" height="140" as="geometry" /> | ||
| </mxCell> | ||
| </root> | ||
| </mxGraphModel> | ||
| </diagram> | ||
| </mxfile> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,150 @@ | ||
| ## fAIr Backend | ||
|
|
||
| This repository contains the backend sourcecode for the fAIr project. The backend | ||
| is composed of several services that are orchestrated using Docker Compose. | ||
|
|
||
| The backend of fAIr is powered by | ||
| - tensorflow:2.9.2 | ||
| - django 3.1.2 & geodjango | ||
| - celery and flower | ||
| - solaris | ||
|
|
||
| The pretrained Convolutional Neural Network is base-model is provided by [radiant earth ramp baseline model](https://github.com/radiantearth/model_ramp_baseline) | ||
|
|
||
| The CNN is an EfficientNet-UNet encoder-decoder semantic segmentation model. The baseline model have already been pretrained on 1,200,0000 labelled buildings across 22 individuals AOI. | ||
| The RAMP model was trained with a particular focus on informal settlements and partially constructed buildings, making it an appropriate base-model for HOT application. | ||
|
|
||
| The platform that fAIr provides is a further fine-tuning of the base-line model which enhance the model efficiacy to the desired area. | ||
|
|
||
| > The backend codebase and the containersed docker enviornment is currently optimised for deployment on an Debian AWS instance with 4GB. Nvidia GPU and 16 GB. RAM. | ||
| > It is recommended to use the provided docker images and cloud instance to deploy the RAMP model. As the Docker images with model, model weights, and peripherial requirements will take up at least 10 Gb. of storage space. | ||
| ### Structure | ||
|
|
||
| The backend codebase is organised into the following main directories and files: | ||
|
|
||
| - docker: This directory contains the Docker configurations for the project. | ||
| - ramp: This directory contains the RAMP (Rapid Analytics and Model Prototyping) configurations. | ||
| - solaris: This directory contains the Solaris configurations, a Python library for piping and translation between geospatial and ML formats | ||
|
|
||
| - requirements.txt: This file lists the Python dependencies required by the project. | ||
|
|
||
| ### Deploying | ||
|
|
||
| The user can pull and deploy fAIr backend by running: | ||
|
|
||
| ```bash | ||
| docker build . | ||
| ``` | ||
|
|
||
| Before running the docker container, we need to obtain the pre-trained RAMP model. | ||
| We will also need to mount it: | ||
|
|
||
| ```bash | ||
| git clone https://github.com/kshitijrajsharma/ramp-code-fAIr.git ramp-code &&\ | ||
| pip install gdown &&\ | ||
| gdown --fuzzy 'https://drive.google.com/u/0/uc?id=1wvJhkiOrSlHmmvJ0avkAdu9sslFf5_I0&export=download' &&\ | ||
| unzip checkpoint.tf.zip -d ./ramp-code/ramp && rm -rf checkpoint.tf.zip | ||
| ``` | ||
|
|
||
| Run the built container using | ||
|
|
||
| ```bash | ||
| docker run . | ||
| ``` | ||
|
|
||
| Once insider the docker container, there are several more additional steps to communicate\ | ||
| with the database | ||
|
|
||
| ### Make sure you have postgresql installed with postgis extension enabled | ||
|
|
||
| Configure .env: | ||
|
|
||
| Create .env in the root backend project , and add the credentials as provided on .env_sample , Export your secret key and database url to your env | ||
|
|
||
| ```bash | ||
| # Export your database url | ||
| export DATABASE_URL=postgis://postgres:postgres@localhost:5432/ai | ||
| ``` | ||
|
|
||
| You will need more env variables (Such as Ramp home, Training Home) that can be found on ```.sample_env``` | ||
|
|
||
| Now change your username, password and db name in settings.py accordingly to your database | ||
|
|
||
| > The application is boostrapped by calling `manage.py` to bootstrap the geodjango application. | ||
| ``` bash | ||
| python manage.py makemigrations login | ||
| python manage.py migrate login | ||
| python manage.py makemigrations core | ||
| python manage.py migrate core | ||
| python manage.py makemigrations | ||
| python manage.py migrate | ||
| python manage.py runserver | ||
| ``` | ||
|
|
||
| ### Now server will be available in your 8000 port on web, you can check out your localhost:8000/admin for admin panel | ||
|
|
||
| To login on admin panel, create your superuser and login with your credentials restarting the server | ||
|
|
||
| ```bash | ||
| python manage.py createsuperuser | ||
| ``` | ||
|
|
||
| ### Authentication | ||
|
|
||
| fAIr uses oauth2.0 Authentication using  | ||
|
|
||
| 1. Get your login Url Hit /api/v1/auth/login/ | ||
| - URL will give you login URL which you can use to provide your osm credentials and authorize fAIr | ||
| - After successful login you will get access-token that you can use across all osm login required endpoints in fAIr | ||
| 2. Check authentication by getting back your data Hit /api/v1/auth/me/ | ||
| - URL requires access-token as header and in return you will see your osm username, id and image url | ||
|
|
||
| ### Start celery workers | ||
|
|
||
| ```bash | ||
| celery -A aiproject worker --loglevel=debug -n my_worker | ||
| ``` | ||
|
|
||
| Monitor using flower if you are using redis as result backend, api supports both options django / redis You can start flower to start monitoring your tasks | ||
|
|
||
| ```bash | ||
| celery -A aiproject --broker=redis://127.0.0.1:6379/0 flower | ||
| ``` | ||
|
|
||
| ### Run Tests | ||
|
|
||
| ```bash | ||
| python manage.py test | ||
| ``` | ||
|
|
||
|
|
||
| ### Services | ||
|
|
||
| The backend is composedof the following services: | ||
|
|
||
| - **PostgreSQL Database (with PostGIS)**: This service uses the `postgis/postgis` Docker image | ||
| to provide a spatial enabled RDBMS. This is where the geospatial data for this project is stored | ||
|
|
||
| - **Redis**: This is an key-value in memory database for the queueing system for User/Instance/Worker celery. | ||
| This stores the user list and specifications of task requests for RAMP. | ||
|
|
||
| - **App**: This is hte main application service. Built from the Dockerfile, the django and geodjango | ||
| bootstraps the various API communication services. | ||
|
|
||
| - **Worker**: This is the Celery service that manages the AWS resources. The queueing process can be monitored using **Flower** | ||
| nke | ||
|
|
||
| #### Flowchart | ||
|
|
||
|  | ||
|
|
||
| #### Ports | ||
|
|
||
| The services are exposed on the following ports: | ||
| - PostgreSQL: 5434 | ||
| - Redis: 6379 | ||
| - App: 8000 | ||
| - Worker Dashboard(Flower): 5500 |
Oops, something went wrong.