diff --git a/Containerfile b/Containerfile new file mode 100644 index 0000000..d736ab6 --- /dev/null +++ b/Containerfile @@ -0,0 +1,22 @@ +FROM docker.io/qgis/qgis:latest + +ENV DEBIAN_FRONTEND=noninteractive + +RUN apt-get update && \ + apt-get install -y \ + git \ + g++-12 \ + libboost-all-dev \ + libeigen3-dev \ + libtiff-dev \ + make \ + --no-install-recommends + +WORKDIR /root + +ENV DISPLAY=:0 + +RUN chmod +x build.sh && ./build.sh + +CMD ["/bin/bash", "-c", "source /root/venv/bin/activate && qgis"] +# CMD ["tail", "-f", "/dev/null"] diff --git a/README.md b/README.md new file mode 100644 index 0000000..9f7ade0 --- /dev/null +++ b/README.md @@ -0,0 +1,71 @@ +# QGIS container with Fire2A plugins +The container runs the latest version of QGIS with all of our tools without having to manually build and configure the +application on your system. The container is compatible with both Podman and Docker. We recommend using Podman, but the +instructions found here are easily translated into Docker. +### Everything that is not saved to the container directory `/mnt` will be lost once the container stops running. +## TL;DR + +```bash +sudo apt install podman git +mkdir qgis-vol +cd qgis-vol +git clone git@github.com:fire2a/qgis-pan-europeo.git +git clone git@github.com:fire2a/fire2a-lib.git +git clone https://github.com/fire2a/fire-analytics-qgis-processing-toolbox-plugin.git toolbox +git clone https://github.com/fire2a/C2F-W.git +# build the container +podman build -t qgis-fire2a --volume $(pwd)/qgis-vol:/mnt -f Containerfile . +# run the container +podman run -it --env DISPLAY=$DISPLAY --volume /tmp/.X11-unix:/tmp/.X11-unix --volume qgis-vol:/mnt --device /dev/dri --name fire2a qgis-fire2a +# be sure to save your qgis project in the mnt directory so you can access it later, otherwise it will be lost forever +``` + +## Prerequisites + +```bash +sudo apt install podman git +``` + +Ensure you have Podman installed on your system. You can find installation instructions in the [official Podman documentation](https://podman.io/docs/installation). +You must also have Git installed. + +## Clone the repositories + +Clone our tools into a dedicated directory. +```bash +mkdir qgis-vol +cd qgis-vol +git clone git@github.com:fire2a/qgis-pan-europeo.git +git clone git@github.com:fire2a/fire2a-lib.git +git clone https://github.com/fire2a/fire-analytics-qgis-processing-toolbox-plugin.git toolbox +git clone https://github.com/fire2a/C2F-W.git +``` + +## Build the image + +To build the container image using Podman, navigate to the directory where the container file is stored +and run the following command: + +```bash +podman build -t qgis-fire2a --volume Path/to/qgis-vol:/mnt -f Containerfile . +``` + +This will build the container using a volume mount, sharing all that is in your local directory `qgis-vol` to the +directory `/mnt` in the container. + +## Run the container + +Once the image is built, you can run QGIS using Podman: + +```bash +podman run -it --env DISPLAY=$DISPLAY --volume /tmp/.X11-unix:/tmp/.X11-unix --volume ~/Path/to/qgis-vol:/mnt --device /dev/dri --name fire2a qgis-fire2a +``` +You can use the QGIS application as you would normally. Everything you save onto the container directory `mnt` will +be saved to your local directory `qgis-vol`. **If you do not save your project to this directory, it will be lost when +you close the application or the container**. + +To access the container's terminal while you're running QGIS, open another local terminal and run +```bash +podman exec -it qgis-fire2a bash +``` +### Remember that everything that is not saved to the container directory `/mnt` will be lost once the container stops running. diff --git a/build.sh b/build.sh new file mode 100755 index 0000000..07c2fc1 --- /dev/null +++ b/build.sh @@ -0,0 +1,20 @@ +#!/bin/env bash + +cd C2F-W/Cell2Fire +make clean +make +cd ../.. + +python3 -m venv venv --system-site-packages +. venv/bin/activate +cd fire2a-lib +pip install -r requirements.build.txt +pip install -r requirements.code.txt +pip install -r requirements.txt +pip install --editable . +cd .. + +plugins_dir=~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/ +mkdir -p $plugins_dir +ln -sf "$(pwd)/toolbox/fireanalyticstoolbox" "$plugins_dir/fireanalyticstoolbox" +ln -sf "$(pwd)/C2F-W" "$(pwd)/toolbox/fireanalyticstoolbox/simulator/C2F" diff --git a/profile/README.md b/profile/README.md index fbd2393..ee0a2fc 100644 --- a/profile/README.md +++ b/profile/README.md @@ -3,10 +3,9 @@ 2. [Getting help](#getting-help) 3. [Contributing](#contributing) 4. [Developer setup](#developer-setup) - 1. [Get latest qgis](#1-get-latest-qgis) - 2. [Get Cell2Fire, python libs and QGIS toolboox-plugin](#2-get-cell2fire-python-libs-and-qgis-toolboox-plugin) - 3. [symlink them](#3-symlink-them) - 4. [run](#4-run) + - [Container](#container) + - [Manual](#manual) + # About Fire2a _We are a team dedicated to finding scientific and technological solutions to mitigate the effects of wildfires. We believe open-source collaboration is key and also providing custom consulting services for real-world organizations. [Contact us](mailto:fire2a@fire2a.com)_ @@ -22,7 +21,7 @@ __2. [Fire-Analytics-ToolBox](https://github.com/fire2a/fire-analytics-qgis-proc __3. [Algorithms-libs](https://github.com/fire2a/fire2a-lib):__ [Python package](https://pypi.org/project/fire2a-lib/) with algorithms and common GIS tasks. -__4. [Documentation](https://github.com/fire2a/docs):__ User documentation, including QGIS recipes, install & plugin management. +__4. [Documentation](https://github.com/fire2a/docs):__ End user documentation, including Cell2Fire, Qgis-Toolbox, QGIS recipes, install & plugin management. [Check it here](https://fire2a.github.io/docs/) # Getting help - [Outreach contact](mailto:fire2a@fire2a.com) @@ -42,45 +41,93 @@ All contibutions are welcome, for effectiveness please follow: - Scientific citations: _Fire research deals with real life or death risks;_ If your code involves scientific models or calculations, include citations in [BibText format](https://www.bibtex.com/g/bibtex-format/). More info [Cell2Fire-W/docs/README.md](https://github.com/fire2a/C2F-W/blob/main/docs/README.md) # Developer setup -1. get QGIS -2. get the repos -3. symlink them -4. run -## 1. Get latest qgis +Pick your poison: +- Containerized, building on top of the [official QGIS container](https://hub.docker.com/r/qgis/qgis) +- Or manual, system-wide installing QGIS and using it through a python virtual environment + +## Container +[Long tutorial](../README.md) +TL;DR: +1. Clone the repos: [Cell2FireW](https://github.com/fire2a/C2F-W), [Fire-Analytics-ToolBox](https://github.com/fire2a/fire-analytics-qgis-processing-toolbox-plugin), [Algorithms-libs](https://github.com/fire2a/fire2a-lib) +2. Get ![Containerfile](../Containerfile) and ![build.sh](../build.sh); Build the image (that mounts the repos and runs the build script). +3. Run the container, enable our plugin in QGIS. +```bash +# required packages podman & git +sudo apt install podman git wget + +# the current directory will be shared to the container +# let's start with an empty one +mkdir fire2a +cd fire2a + +# get Containerfile and build.sh +wget https://raw.githubusercontent.com/fire2a/.github/refs/heads/main/build.sh +wget https://raw.githubusercontent.com/fire2a/.github/refs/heads/main/Containerfile + +# clone the repos +git clone git@github.com:fire2a/C2F-W.git +git clone git@github.com:fire2a/fire-analytics-qgis-processing-toolbox-plugin.git toolbox +git clone git@github.com:fire2a/fire2a-lib.git + +# build the container mounting the current directory into container user's home (/root) +podman build --tag qgis-fire2a --volume $(pwd):/root . + +# run the container also with display capabilities +podman run -it --env DISPLAY=$DISPLAY --volume /tmp/.X11-unix:/tmp/.X11-unix --volume $(pwd):/root --device /dev/dri --name fire2a qgis-fire2a + +# re-run the container +podman start fire2a +podman stop fire2a +``` +Keep in mind that any changes made to the container's filesystem are lost when stopped except those made into the user's home (`/root`). +This includes all temporary generated layers (whose files are generated into /tmp/processing...), so to keep them, save them home (`--volume $(pwd):/root`). + +## Manual +1. Install the latest QGIS +2. Clone the repos +3. Symbolic link them +4. Run QGIS +### 1. Get latest qgis - steps from https://qgis.org/resources/installation-guide/#debianubuntu - check your distro version `$lsb_release -a`, below is for Debian 12 (bookworm) ```bash -sudo apt install gnupg software-properties-common -sudo mkdir -m755 -p /etc/apt/keyrings # not needed since apt version 2.4.0 like Debian 12 and Ubuntu 22 or newer +# required packages +sudo apt install gnupg software-properties-common wget + +# add the key sudo wget -O /etc/apt/keyrings/qgis-archive-keyring.gpg https://download.qgis.org/downloads/qgis-archive-keyring.gpg -# is the suite bookworm ? + +# add the repo to sources.list (is the suite still bookworm?) echo 'Types: deb deb-src URIs: https://qgis.org/debian Suites: bookworm Architectures: amd64 Components: main Signed-By: /etc/apt/keyrings/qgis-archive-keyring.gpg' | sudo tee /etc/apt/sources.list.d/qgis.sources + +# install sudo apt update sudo apt install qgis qgis-plugin-grass ``` -## 2. Get Cell2Fire, python libs and QGIS toolboox-plugin +### 2. Get Cell2Fire, python libs and QGIS toolboox-plugin ```bash -# choose install location +# choose install location, below ~/fire is used fire=~/fire -mkdir -p $fire +mkdir -p "$fire" -# get cell2fireW -cd $fire -git clone git@github.com:fire2a/C2F-W.git C2F +# get Cell2FireW +cd "$fire" +git clone git@github.com:fire2a/C2F-W.git sudo apt install g++-12 libboost-all-dev libeigen3-dev libtiff-dev -cd C2F/Cell2Fire +cd C2F-W/Cell2Fire +make clean make # get python library -cd $fire +cd "$fire" sudo apt install python3-venv python3 -m venv venv --system-site-packages # needs system qgis packages -source $fire/venv/bin/activate +source "$fire/venv/bin/activate" git clone git@github.com:fire2a/fire2a-lib.git lib cd lib pip install -r requirements.build.txt @@ -89,24 +136,27 @@ pip install -r requirements.txt pip install --editable . # get toolbox -cd $fire +cd "$fire" git clone git@github.com:fire2a/fire-analytics-qgis-processing-toolbox-plugin.git toolbox ``` - -# 3. symlink them +### 3. symlink them ```bash +plugins_dir=~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/ + + # if never opened QGIS +mkdir -p $plugins_dir + # toolbox to QGIS plugins -mkdir -p ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/ -cd ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/ -ln -s $fire/toolbox/fireanalyticstoolbox . +ln -sf "$(fire)/toolbox/fireanalyticstoolbox" "$plugins_dir/fireanalyticstoolbox" -# c2f to toolbox -cd $fire/toolbox/fireanalyticstoolbox/simulator -ln -s $fire/C2F . +# C2F to toolbox +ln -sf "$(fire)/C2F-W" "$(fire)/toolbox/fireanalyticstoolbox/simulator/C2F" ``` -# 4. run +### 4. run ```bash source $fire/venv/bin/activate qgis -# install the toolbox plugin https://docs.qgis.org/3.4/en/docs/training_manual/qgis_plugins/fetching_plugins.html ``` +Enable our plugin on Plugins>Manage..>Installed> enable the check box on 'FireFire Analytics Processing-Toolbox' + +[Official tutorial](https://docs.qgis.org/3.4/en/docs/training_manual/qgis_plugins/fetching_plugins.html)