The building blocks of our wildfire detection & monitoring API.
You can run the API containers using this command:
make runYou can now navigate to http://localhost:8080/docs to interact with the API (or do it through HTTP requests) and explore the documentation.
In order to stop the service, run:
make stopThe back-end core feature is to interact with the metadata tables. For the service to be useful for wildfire detection, multiple tables/object types are introduced and described as follows:
- Groups: defines collections of credentials that share a similar scope (e.g. you won't be able to access the same data as the local firefighters).
- Accesses: stores the hashed credentials and access level for users & devices.
- Users: actual humans registered in the database.
- Devices: the registered cameras.
- Sites: specific locations (firefighter watchtowers, fire stations, etc.).
- Installations: association linking a device & a site over a given timespan.
- Events: wildfire events.
- Media: metadata of a picture and its storage bucket key.
- Alerts: association of a picture, a device, and an event.
- Webhooks: advanced mechanisms to introduce callbacks on specific routes.
The API has been designed to provide, for each wildfire detection, the alert metadata:
- timestamp
- the picture that was used for detection
- the location is was taken at, and the direction it was taken from
With the previously described tables, here are all the steps to send a wildfire alert:
- Prerequisites (ask the instance administrator): register user
- Register a device: declare your device on the API, using your new user credentials.
- Create a media object & upload content: using the device credentials, save the picture metadata and upload the image content.
- Create an alert: using the device credentials, send all the wildfire metadata.
- Docker
- Docker compose
- Poetry
- Make (optional)
The project was designed so that everything runs with Docker orchestration (standalone virtual environment), so you won't need to install any additional libraries.
In order to run the project, you will need to specific some information, which can be done using a .env file.
This file will have to hold the following information:
S3_ACCESS_KEY: public key to access to the S3 storage serviceS3_SECRET_KEY: private key to access the resource.S3_REGION: your S3 bucket is geographically identified by its location's regionS3_ENDPOINT_URL: the URL providing a S3 endpoint by your cloud providerBUCKET_NAME: the name of the storage bucketPOSTGRES_DB: name of postgres databasePOSTGRES_USER: user of postgres databasePOSTGRES_PASSWORD: user password of postgres databaseS3_PROXY_URL: the url of the proxy to hide the real s3 url behind, do not use proxy if "" Optionally, the following information can be added:SENTRY_DSN: the URL of the Sentry project, which monitors back-end errors and report them back.SENTRY_SERVER_NAME: the server tag to apply to events.BUCKET_MEDIA_FOLDER: the optional subfolder to put the media files inTELEGRAM_TOKEN: to send notifications via telegram for a new alert (once per event)POSTHOG_KEY: to enable product analytics
So your .env file should look like something similar to:
S3_ACCESS_KEY=YOUR_ACCESS_KEY
S3_SECRET_KEY=YOUR_SECRET_KEY
S3_REGION=bucket-region
S3_ENDPOINT_URL='https://s3.mydomain.com/'
BUCKET_NAME=my_storage_bucket_name
POSTGRES_USER=dummy_pg_user
POSTGRES_PASSWORD=dummy_pg_pwd
POSTGRES_DB=dummy_pg_db
SENTRY_DSN='https://replace.with.you.sentry.dsn/'
SENTRY_SERVER_NAME=my_storage_bucket_name
The file should be placed at the root folder of your local copy of the project.
This project is a REST-API, and you can interact with the service through HTTP requests. However, if you want to ease the integration into a Python project, take a look at our Python client.
Any sort of contribution is greatly appreciated!
You can find a short guide in CONTRIBUTING to help grow this project!
Distributed under the Apache 2.0 License. See LICENSE for more information.