Skip to content

Home

Jump to bottom
Francisca Barros edited this page Jun 26, 2021 · 2 revisions

Welcome

Welcome to FIRELab wiki, From vegetation characterization to fire segmentation and progression, and much more, FIRELab helps environmental researchers, data scientists and engineers streamline their work. All this aligned with a responsive, easy-to-use, all-in-one platform.

This project was developed in the context of Project in Informatics curricular unit, part of the Informatics Engineering Degree of University of Aveiro.

Table of Contents

User guide

To learn about the project in more detail and to answer questions about implementation and usage, check the technical report, available in the project's repository

Release notes

The summary of all releases can be found at the Github repository releases page

Installation Guide

As a web platform, FIRELab is available on a variety of Linux distros, macOS and Windows through the usage of Docker and/or local installation of all the requirements. The guides in this section will use bash commands for linux terminal, but there are similar versions of them for both macOS and Windows as well as the Docker Desktop's GUI.

Quickstart

The easiest way to install the tool locally is through the docker-compose.yml present in the repository's FIRELAB_website directory

Prerequisites

Setting up

  1. Either download a released version of the source code in the link provided in the Release notes section or clone the repository through the command 
    $ git clone https://github.com/itskikat/firelab.git

Run the docker-compose file

  1. On the root folder, open the directory FIRELab_website where all the source code is:

    $ cd FIRELab_website

  2. Build and run the tool with docker-compose:

    $ docker-compose up -d --build

    This might take some time due to the fact that images for both the database and the framework are being installed, as well as the project's dependencies. Note: for subsequent uses, and after the image has been built, to restart the docker containers you may simply run:

    $ docker-compose up -d

  3. Migrate the database schema inside the docker container to properly set up the PostgeSQL database:

    $ docker exec -it firelab_website_web_1 bash
python3 manage.py makemigration main
python3 manage.py migrate
exit

    If everything runs smoothly, the database is ready for use.

  4. Enter the localhost's port 8000 in a web-browser to see the web application running. Note: if localhost refuses to connect and the site can't be reached, try the following command:

    $ docker exec -it firelab_website_web_1 bash
python3 manage.py runserver 0.0.0.0:8000

    After that use Ctrl+p followed by Ctrl+q to detach from the container while leaving the application running; Note that if you use Ctrl+z the application will stop running.

Stop the docker-compose file

  1. When you are done working, you can shut down the web application by running: 
    $ docker-compose down
    Don't worry, all saved data in the database will be preserved if you do this.

Uninstall and delete

  1. To completly uninstall the web application, first make sure you stopped the docker-compose:

    $ docker-compose down

  2. After that, remove the volume that stores the persistent data of the database

    $ docker volume ls
$ docker volume rm firelab_website_postgis-data

    Note: if after running $ docker volume ls you dont't see listed under VOLUME NAME firelab_website_postgis-data, then the volume has already been erased

  3. Delete the project's docker images. You can list all images with:

    $ docker images

    Copy the IMAGE ID of the firelab_website_web REPOSITORY and run the following command, replacing $ID with the copied IMAGE ID:

    $ docker image rm $ID

    Note: the project also makes use of the kartoza/postgis and python images, which can be deleted if no other project of yours does, so proceed with caution.

  4. Finally you can safely delete the source code and the repository root folder.

Manual Installation without Docker

This section will guide you through how to manually install the tool without using docker or docker-compose, while installing all required dependencies on your machine.

Prerequisites

Setting up

  1. Either download a released version of the source code in the link provided in the Release notes section or clone the repository through the command 
    $ git clone https://github.com/itskikat/firelab.git

Create and activate a virtual environment

  1. Move to the source code directory of the root folder of the project:

    $ cd FIRELab_website

  2. Create a virtual environment (venv) to run the tool on:

    $ python3 -m venv venv

    Note the last venv can be replaced with the name/path of the virtual environment you want to create, but remember to adjust subsequent commands

  3. Activate the virtual environment:

    $ source venv/bin/activate

Install the tool inside the virtual environment

  1. Install the required dependencies:

    $ add-apt-repository ppa:ubuntugis/ppa && apt-get update
$ sudo apt-get install -y binutils libgdal-dev gdal-bin
$ sudo apt-get install -y python3-opencv

  2. Install the requirements through the requirements.txt file:

    $ pip3 install -r requirements.txt

  3. Export the path variable for gdal

    $ export CPLUS_INCLUDE_PATH=/usr/include/gdal
$ export C_INCLUDE_PATH=/usr/include/gdal

  4. Check the gdal info version, to see if it was correctly installed:

    $ gdalinfo --version

  5. Install GDAL version 2.4.2 using pip:

    $ pip3 install -I GDAL==2.4.2

Configure and run the database

  1. First you need to create a user on the database, with the credentials user: superuser and password: firelabdbpass
  2. Create a database firlab with host localhost on the default port (5432)
  3. In the created database, create the extension for postgis using CREATE EXTENSION postgis

Run the web application

  1. First we need to migrate the database schema to properly set up the PostgeSQL database:

    $ python3 manage.py makemigrations main
$ python3 manage.py migrate

    If everything runs smoothly, the database is ready for use.

  2. Run the Django web application with:

    $ python3 manage.py runserver 0.0.0.0:8000

    This will run the application on port 8000; if another port is available, you can modify this number. After that, you should see the web application start in your terminal, indicating that it is ready to use.

  3. Enter the localhost's port 8000 (or, the one you chose) in a web browser to see the web application running.

Stop the web application

  1. To stop the application, just use Ctrl+z on the terminal window it's running on.

Final Notes

More information available on the project's website as well as a tutorial demo. Thank you for using our tool, contributions are always helpful and appreciated.

Clone this wiki locally