This web application supports the delineation (polygonization) of mining areas using satellite images given a set of approximate locations where mining may occur. The app systematically displays the mining locations and several background options of satellite images, which the users can take into account to draw and edit polygons.
The app is built in R Shiny with a PostgreSQL Database and PostGIS extension. The app and database can either be created with one single
docker-compose command or, the application the current setup is targeting:, the database is set up using
docker-compose, and the application itself is deployed via shinyproxy in order to allow user management and password protection (see details below).
Note: The app requires a database as defined in create_db_schema.sql. The database must be populated with approximate mining locations and other information about the mines.
In order to run the app, you need the following tools installed:
Docker and Docker Compose
To install Docker and Docker Compose (comes already installed with Docker Desktop) for you system follow the links below:
- Mac: Install Docker Desktop for Mac to get Docker and Docker Compose installed
- Windows: Install Docker Desktop for Windows to get Docker and Docker Compose installed
- Other systems:
You only need git installed if you want to contribute to the repository or clone it without having to download it manually.
(R and RStudio)
You only need R (version 3.5 or higher) and RStudio installed in case you would like to make your own changes to the app and try them out before you create the docker containers.
If you are on a Linux machine, you need to install the following packages via
apt (or any other package manager) as they are required by the R packages needed:
sudo apt install libpq-dev libssl-dev libxml2-dev libcurl4-openssl-dev
The command to install the R packages can be found on the respective file you want to edit.
To use the app with ShinyProxy, create a database with
docker-compose and deploy the app within a ShinyProxy environment, refer to our brief shinyproxy-documentation.
Get the app
To get the app, you can either
- download the source using the "Clone or download"-button above
git clone https://github.com/fineprint-global/app-mining-area-polygonization.git
There are a few settings that you have to make before you can run the app.
.env file in the root directory
You have to set the following variables, here is an example
POSTGRES_PASSWORD=postgresuserpassword POSTGRES_PORT=5454 SHINY_PORT=80
.Renviron file in the
.Renviron file, you need to set the internal container port as your
db_port, so DO NOT match the
POSTGRES_PORT in the
.env file, but set the default port for postgres, which is
5432. Here is an example file that needs to be created inside the
db_host=mva_db db_port=5432 db_name=vector_mine db_user=app db_password=YOURPASSWORD
How to run
Please note that this how-to-run only applies to usage with
docker-compose for both, not yet to our ShinyProxy deployment.
- You can run it as is, with a pre-loaded database.
- You can use your own data, which requires you to adapt the scripts in the data-to-db directory.
- You can leave the database as is and change the visualizations.
1. Run as is
- Make sure all necessary dependencies are installed.
- Make sure Docker (Desktop) is up and running.
- Make sure you completed the steps in setup
- Navigate to the root directory (
app-mining-area-polygonization) with a shell of your choice and run the following command:
docker-compose up -d
Now both, the
mva_app (RShiny app) and the
mva_db (postgis database) should be running on ports specified in the
docker-compose.yml on your localhost (e.g. ports
5454 respectively). To verify that both containers are running and the ports are correct, you can run
docker-compose ps (in the root directory) or
docker ps (anywhere).
You should now be able to see the app running at localhost:80 or – if not
80 – at the port you specified in
If there are any problems, check out the troubleshooting section.
2. Use your own data
More detailed instructions on this will come soon, but you will have to adjust the
insert_mines_to_db.R located in the data-to-db directory to load your own input-output table and adjust it to the proper database format.
3. Change the visualizations
The folders to take care of are the app folder and the docker-rshiny folder. The
app folder will be used to change the visualizations whereas the
docker-rshiny folder needs to be kept in mind for any new packages you might require.
Before you dive into this, if you are new to RShiny, you may want to check out this tutorial.
Our app is divided into 4 main files:
app.R: you should not need to add anything there, this just brings all three other files together
global.R: this will be executed once for every worker process, not for every user, so this is where you specify database connections and perform other setup-related tasks
ui.R: you specify the UI here.
uiOutput) are defined here and respective
renderText) for those are performed in the
server.R. If you want to add new visualizations or other elements, define them here.
server.R: any new visualizations defined in the
ui.Rshould be implemented in the
server.R, this is where you collect your data, bring it into the correct format and then define the output-layout (e.g. for
docker-rshiny folder for packages
You need to edit the Dockerfile if you add any new packages that are not included yet.
This folder contains the R scripts to create a mining polygons data release.
How to restart or stop the app
- To restart the containers, run
- To stop the containers, move to the
app-mining-area-polygonizationdirectory and run
- To stop containers and to remove containers, networks, volumes, and images created by
docker-compose up, run
This section is still to come.
- make sure you have all dependencies (packages etc.) installed, you may want to check out the RShiny Dockerfile for any packages necessary for the app to run
Windows-Issues with RShiny Docker
In case there are issues with building and running the RShiny Docker from the directory (especially in Windows file permissions tend to get messed up, and then the container is constantly restarting, sometimes with the error:
standard_init_linux.go:207: exec user process caused "no such file or directory"), you can alternatively use the docker image from Docker Hub. For this, you need to replace the build context with the Docker Hub image like below:
# build: # context: ./docker-rshiny image: fineprint/mva
This work was supported by the European Research Council (ERC) under the European Union's Horizon 2020 research and innovation programme grant number 725525 FINEPRINT project.