Awesome
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
<p align="center"> <img src="https://github.com/naturalsolutions/ecosecrets/actions/workflows/test_api.yml/badge.svg?branch=dev"/> <img src="https://github.com/naturalsolutions/ecosecrets/actions/workflows/build_frontend.yml/badge.svg?branch=dev"/> <img src="https://github.com/naturalsolutions/ecosecrets/actions/workflows/documentation.yml/badge.svg?branch=dev"/> </p>
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 HTTPSHTTP_HTTPS_PORT: usually 80 for HTTP protocol and 443 for HTTPSDB_USER: the name you want for the DB userDB_PASSWORD: the password you want for the DB userDB_NAME: the name you want for the DBMINIO_ROOT_USER: the name you want for the Minio userMINIO_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/.