ecoSecrets - a web application enabling users to manage their camera traps data

ecoSecrets is an open-source web application that aims to facilitate biodiversity studies that use autonomous data collection devices such as camera traps. This web-application is in development and offers several features that meet the needs of biodiversity stakeholders:

• project management: to delimit the studies according to their context
• management of study sites: to identify spatial scope
• device management: to specify technical characteristics of the tools used in the field and their availability
• deployment management: to characterize spatio-temporal limits of data acquisition
• media management: to standardize and optimize the storage of collected data
• media processing: to enable the addition of annotations to the raw data

We would be delighted if you use it, or even contribute in its development.

A demo is available here. Don't hesitate to try it out! User : admin ; password : password

Documentation (in french for now): ecoSecrets documentation

Installation

Prerequisite

Docker and docker-compose must be installed on the server/machine (cf. official website).

Application downloading

Replace the X.Y.Z mention by the name of the release you want to install.

cd wget https://github.com/naturalsolutions/ecosecrets/archive/refs/tags/X.Y.Z.zip unzip X.Y.Z.zip rm X.Y.Z.zip mv ecosecrets-X.Y.Z ecosecrets/

Settings

Copy the .env.sample inside the docker directory to .env:

cd ecosecrets cp docker/.env.sample docker/.env nano docker/.env

Edit freely this .env file to change credentials for instance. Here are the main parameters you usually want to modify:

• ENV : uncomment it to activate the production mode (only if your app has been configured with a domain name)
• DOMAIN : localhost, an IP address or a domain name (according to your context)
• PROTOCOL : modify it to "https" if you want to activate HTTPS
• HTTP_HTTPS_PORT : usually 80 for HTTP protocol and 443 for HTTPS
• DB_USER : the name you want for the DB user
• DB_PASSWORD : the password you want for the DB user
• DB_NAME : the name you want for the DB
• MINIO_ROOT_USER : the name you want for the Minio user
• MINIO_ROOT_PASSWORD : the password you want for the Minio user

In the current version (0.1.1), you can't modify the APP_USER and the APP_PASSWORD directly in this file. You will be able to modify the admin password trough Keycloak later on.

Launching

./scripts/docker.sh up -d

With the default settings, the app will run on http://localhost:8889/ but the port of each service will be avaible to debug. This URL must be adapted to your context (depending on chosen protocol, domain and port).

Sample data (for testing only)

Sample data can be generated by using the following command:

./scripts/docker.sh exec api python -c "from src.connectors.database import init_db; init_db()"

Authentication

ecoSecrets uses Keycloak version 21.1.0 as authentication system.

A keycloak service is provided in the docker-compose.yml file. This also sets up the keycloak instance to create a new realm, add clients (frontend and backend) and create an admin user (credentials: admin / password).

For now, there is no right implemented in the app. This means that all users have the same rights in ecoSecrets. The admin user created above can log into the app and manage users via the administration console of keycloak (http://localhost:8889/auth by default).

You can use your own keycloak instance if you wish, just change in the .env the keycloak env variables. Be careful, all versions of keycloak may not be supported.

Development

Launch backend tests

Tests are written with pytest and can be launched with the following command:

./scripts/docker.sh exec api pytest tests --cov-report html:/home/app/src/htmlcov --cov=src

The default config assumes that the backend is accessing the database through the docker network (via "db" adress) which prevents backend tests from being run locally (outside a container).

API/backend documentation

The openapi documentation accessible via swagger is available here:

``` http://localhost:8889/api/v1/docs

```

ecoSecrets app documentation (in french for now)

The documentation is generated with mkdocs and is exposed on port 8133 to be able to work on it with automatic reloading.

``` http://localhost:8133

```

Contributing

To contribute to this project, please fork and create a pull request, describing the new functionality or bug fixed. Please link to an issue if relevant. We use 'black' and 'isort' for Python code-formatting, this is checked via a GitHub action.

Licence

ecoSecrets
Copyright (C) 2023 Natural Solutions

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.