dataforgoodfr · LilianBsc · Mar 10, 2025
diff --git a/docs/contributing/README.md → docs/contributing/how-to?.md b/docs/contributing/README.md → docs/contributing/how-to?.md
diff --git a/docs/description/about.md b/docs/description/about.md
diff --git a/docs/notes/ais.md → docs/description/ais.md b/docs/notes/ais.md → docs/description/ais.md
@@ -1,3 +1,5 @@
+# AIS explaination
+
 The automatic identification system (AIS) is an automatic tracking system that uses transceivers on ships and is used by vessel traffic services (VTS). When satellites are used to receive AIS signatures, the term Satellite-AIS (S-AIS) is used. AIS information supplements marine radar, which continues to be the primary method of collision avoidance for water transport. Although technically and operationally distinct, the ADS-B system is analogous to AIS and performs a similar function for aircraft.[^1]
 
 ## Limits

diff --git a/docs/notes/technical.architecture.md → docs/description/technical_architecture.md b/docs/notes/technical.architecture.md → docs/description/technical_architecture.md
@@ -1,17 +1,19 @@
+# Technical Architecture
+
 ## Components
 
 #todo
 
 ## Data models
 
-- SQL Alchemy is used to map infra [SQL models](see [infra/database](../../src/bloom/infra/database/))
+- SQL Alchemy is used to map infra [SQL models](see [infra/database](../../../src/bloom/infra/database/))
 - A mapping is done to map infra models with domain
-- For the front-end application pydantic is used (see [domain](../../src/bloom/domain/))
+- For the front-end application pydantic is used (see [domain](../../../src/bloom/domain/))
 
 ## Worflows
 
-- Every 15 minutes, latest vessels positions are scrap from spire api [app.py](../../src/app.py)
-- Every 15 minutes, new alerts are sent to slack [app.py](../../src/app.py)
+- Every 15 minutes, latest vessels positions are scrap from spire api [app.py](../../../src/app.py)
+- Every 15 minutes, new alerts are sent to slack [app.py](../../../src/app.py)
 
 ## Versionning
 

diff --git a/docs/notes/database.initialisation.md → ...etting_started/database_initialisation.md b/docs/notes/database.initialisation.md → ...etting_started/database_initialisation.md
diff --git a/docs/notes/development.environment.md → ...etting_started/development_environment.md b/docs/notes/development.environment.md → ...etting_started/development_environment.md
diff --git a/docs/notes/sql.examples.md → docs/getting_started/sql_examples.md b/docs/notes/sql.examples.md → docs/getting_started/sql_examples.md
@@ -1,3 +1,5 @@
+# SQL Examples
+
 ## List of mmi scrapped since last update
 
 ```sql

diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,278 @@
+![banner](images/banner.png)
+
+## What is Trawl Watch
+
+**[Trawl Watch](https://twitter.com/TrawlWatch)** is an initiative launched by the *
+*[Bloom Association](https://www.bloomassociation.org/en/)** to track and expose the most destructive fishing vessels.
+Inspired by L’[Avion de Bernard](https://www.instagram.com/laviondebernard/), which monitors the movements of private
+jets, **Trawl Watch** aims to make visible the impact of these massive trawlers on our oceans. These vessels, often
+referred to as _mégachalutiers_, deploy gigantic nets that can engulf marine life from the surface down to the ocean
+floor. The consequences are both ecological—as they devastate crucial nursery and breeding areas for marine animals—and
+social, as they deprive artisanal fishermen of a healthy marine ecosystem. The solution proposed by **Bloom** is to
+dismantle these industrial fishing ships and redistribute their quotas to small-scale fishers. A petition has been
+launched, and **Bloom** continues to track these megatrawlers while awaiting action from European institutions.
+
+**Did you know that, in Europe, the largest fishing vessels, which represent 1% of the fleet, catch half of the fish?**
+These factory-vessels can measure up to 144 meters in length and catch 400,000 kilos of fish per day! This is as much as
+1,000 small-scale fishing vessels in one day at sea.
+
+**These veritable sea monsters are devastating Europe’s biodiversity and coastlines.** It is important to measure the
+scale of the damage: about 20 of these factory-vessels can obliterate hundreds of thousands of marine animals and
+biodiversity treasures in one day, including in the so-called ‘Marine Protected Areas’ of French territorial waters,
+which are not protected at all.
+
+## What is Bloom Association
+
+**BLOOM** is a non-profit organization founded in 2005 that works to preserve the marine environment and species from
+unnecessary destruction and to increase social benefits in the fishing sector. **BLOOM** wages awareness and advocacy
+campaigns in order to accelerate the adoption of concrete solutions for the ocean, humans and the climate. **BLOOM**
+carries out scientific research projects, independent studies and evaluations that highlight crucial and unaddressed
+issues such as the financing mechanisms of the fishing sector. **BLOOM**’s actions are meant for the general public as
+well as policy-makers and economic stakeholders.
+
+**Table of contents**
+
+- [What is Trawl Watch](#what-is-trawl-watch)
+- [What is Bloom Association](#what-is-bloom-association)
+- [Principles](#principles)
+- [Requirements](#requirements)
+- [Getting started](#getting-started)
+  - [Clone the Bloom application repository](#clone-the-bloom-application-repository)
+  - [Installation with Docker/Docker Compose stack (Recommended)](#installation-with-dockerdocker-compose-stack-recommended)
+    - [Prerequistes](#prerequistes)
+    - [Building image](#building-image)
+    - [Starting the application](#starting-the-application)
+    - [Load demonstration data](#load-demonstration-data)
+  - [Installation on local machine](#installation-on-local-machine)
+    - [Prerequistes](#prerequistes-1)
+    - [Install Backend Application with Poetry](#install-backend-application-with-poetry)
+    - [Initial configuration](#initial-configuration)
+    - [Loading initial data for backend](#loading-initial-data-for-backend)
+    - [Starting the application](#starting-the-application-1)
+  - [Database migration](#database-migration)
+  - [Use the Bloom Application](#use-the-bloom-application)
+    - [Access Web Interface](#access-web-interface)
+- [Official source code](#official-source-code)
+- [Contributing](#contributing)
+- [Who uses Trawl Watch?](#who-uses-trawl-watch)
+- [What goes into the next release?](#what-goes-into-the-next-release)
+- [Can I use the Trawl Watch logo in my presentation?](#can-i-use-the-trawl-watch-logo-in-my-presentation)
+- [Links](#links)
+- [More information can be found there](#more-information-can-be-found-there)
+- [FAQ](#faq)
+
+## Principles
+
+#TODO
+
+## Requirements
+
+Bloom is tested with:
+
+|            | Main version (dev) | Stable version (1.0.0) |
+|------------|--------------------|------------------------|
+| Python     | 3.11               | 3.11                   |
+| Platform   | AMD64/ARM64(\*)    | AMD64/ARM64(\*)        |
+| Docker     | 24                 | 24                     |
+| PostgreSQL | 14                 | 14                     |
+
+## Getting started
+
+### Clone the Bloom application repository
+
+```bash
+    # clone git repository
+    git clone https://github.com/dataforgoodfr/12_bloom.git
+    # change to project root directory
+    cd 12_bloom
+```
+
+### Installation with Docker/Docker Compose stack (Recommended)
+
+#### Prerequistes
+
+* **Docker Engine** (version >= **18.06.0**) with **Compose** plugin
+
+#### Building image
+
+```bash
+    docker compose build
+```
+
+> When official Docker image will be available, the building step could be optionnal for user as docker compose up will
+> pull official image from repository
+
+#### Starting the application
+
+```bash
+    docker compose up
+```
+
+#### Load demonstration data
+
+To use Trawl Watch application, some data have to be initialy loaded for demonstration. As these data are protected and
+can't be publicly published, you just have to contact the Trawl Watch application team. Informations
+on [Who maintains Trawl Watch?](#who-maintains-traw-watch)
+
+After having filled 12_bloom/data folder with data files get from project team, rename files as following:
+
+* data/chalutiers_pelagiques.csv
+* data/spire_positions_subset.csv
+* data/vessels_subset.csv
+* data/zones_subset.csv
+* data/ports.csv
+* data/geometries/*.json
+
+Then launch docker compose stack using docker compose file extension to add loading data service
+
+    docker compose -f docker-compose.yaml -f docker-compose-load-data.yaml up
+
+You can now jump to [Use the Bloom Application](#use-the-bloom-application)
+
+### Installation on local machine
+
+#### Prerequistes
+
+* **Python**: 3.11
+* **Python-pip**: >=20
+* **Postgresql**: 14, 15, 16
+
+You must have a functionnal PostgreSQL instance with connexion informations (database server hostname or ip, user,
+password, database name, port to use)
+
+#### Install Backend Application with Poetry
+
+```bash
+    # From project diretory
+    cd ./backend
+    # Install uv
+    curl -LsSf https://astral.sh/uv/install.sh | sh
+    # Install project and dependencies
+    uv sync
+```
+
+#### Initial configuration
+
+```bash
+    # From project root diretory
+    # Create initial ocnfiguration
+    cp .env.template .env
+    # Edit .env file
+    # Replace POSTGRES_HOSTNAME/PORT with the postgres server hostname:port (localhost if local default port server)
+    # Replace POSTGRES_USER/PASSWORD with already configured user on serverside
+```
+#### Loading initial data for backend
+
+```bash
+    # From project root diretory
+    cd ./backend
+    # Check if database is up to date with alembic revisions
+    alembic upgrade head
+    # If upgrade is successful you can load the data
+    # Demonstration data must be recovered from TrawlWatch Project Team
+    # and put in <project>/data/ folder with correct names
+    # * data/chalutiers_pelagiques.csv
+    # * data/spire_positions_subset.csv
+    # * data/vessels_subset.csv
+    # * data/zones_subset.csv
+    $ python3 bloom/tasks/load_dim_vessel_from_csv.py 
+    $ python3 bloom/tasks/load_dim_port_from_csv.py
+    $ python3 bloom/tasks/load_dim_zone_amp_from_csv.py
+    $ python3 bloom/tasks/compute_port_geometry_buffer.py
+```
+
+#### Starting the application
+
+```
+//TO UPDATE
+```
+
+You can now jump to [Use the Bloom Application](#use-the-bloom-application)
+
+### Database migration
+
+Trawlwatch DB model has been refactored during DataForGood season 12. If you run a version of Trawlwactch using the old
+model follow next steps to upgrade.
+
+- Upgrade DB model:
+
+```
+$ alembic upgrade head
+```
+
+- Run data conversion from the old model to the new model (actually copy data from `spire_vessel_positions`
+  to `spire_ais_data`). This may take long if you have a long positions history:
+
+```
+$ python backend/bloom/tasks/convert_spire_vessels_to_spire_ais_data.py
+```
+
+- Load new references data (AMP zone, ports, vessels):
+
+```
+$ /venv/bin/python3 backend/bloom/tasks/load_dim_vessel_from_csv.py 
+$ /venv/bin/python3 backend/bloom/tasks/load_dim_port_from_csv.py
+$ /venv/bin/python3 backend/bloom/tasks/load_dim_zone_amp_from_csv.py
+$ /venv/bin/python3 backend/bloom/tasks/compute_port_geometry_buffer.py
+```
+
+- If you feel it, drop old tables:
+
+```
+DROP TABLE mpa_fr_with_mn;
+DROP TABLE spire_vessel_positions;
+DROP TABLE vessels;
+```
+
+### Use the Bloom Application
+
+#### Access Web Interface
+
+After having succeed with [With Docker/Docker Compose stack](#with-docker) or [On local machine](#on-local-machine)
+installation and managed to [Load demonstration data](#load-demonstration-data) you should now access the Bloom
+application with you favorite web browser
+
+* Access to http://localhost:8501
+  ![Home](images/trawlwatch_home.png)
+* Navigate to "Vessel Exploration"
+* Enter MMSI 261084090 as example
+* Clic on "Load"
+* You can select voyage_id and view track of vessel
+  ![Loaded](images/trawlwatch_loaded_voyage.png)
+
+## Official source code
+
+You can find official source code on [Github Repository](https://github.com/dataforgoodfr/12_bloom/)
+
+## Contributing
+
+Want to help build Bloom Application Check out
+our [contributing documentation](https://github.com/dataforgoodfr/12_bloom/tree/main/docs/contributing/README.md).
+
+Official Docker (container) images for Bloom Application are described
+in [images](https://github.com/dataforgoodfr/12_bloom/tree/main/docker/).
+
+## Who uses Trawl Watch?
+
+## What goes into the next release?
+
+#TODO
+
+## Can I use the Trawl Watch logo in my presentation?
+
+#TODO
+
+## Links
+
+#TODO
+
+## More information can be found there
+
+1. [Database initialisation](getting_started/database_initialisation.md)
+2. [Development environment](getting_started/development_environment.md) # outdated
+3. [Architecture description](description/technical_architecture.md)
+4. [Useful SQL examples](getting_started/sql_examples.md)
+
+## FAQ
+
+#todo
diff --git a/docs/notes/tasks.md → docs/objects/tasks.md b/docs/notes/tasks.md → docs/objects/tasks.md
diff --git a/mkdocs.yaml b/mkdocs.yaml
@@ -0,0 +1,32 @@
+site_name: Trawl Watch
+theme:
+  name: readthedocs
+  highlightjs: true
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [src]
+          load_external_modules: true
+          options:
+            docstring_style: google
+markdown_extensions:
+  - admonition
+  - codehilite
+  - pymdownx.superfences
+
+nav:
+  - Home: index.md
+  - Description:
+    - description/about.md
+    - description/ais.md
+    - description/technical_architecture.md
+  - Getting Started:
+    - getting_started/development_environment.md
+    - getting_started/database_initialisation.md
+    - getting_started/sql_examples.md
+  - Objects:
+    - objects/tasks.md
+  - Contributing:
+    - contributing/how_to?.md
diff --git a/pyproject.toml b/pyproject.toml
@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "trawlwatch"
+version = "1.0.0"
+# dynamic = ["version"]
+description = "A brief description of the project."
+authors = [
+    { name="Your Name", email="your.email@example.com" }
+]
+readme = "README.md"
+# license = { file="LICENSE" }
+requires-python = ">=3.8"
+dependencies = [
+]
+
+# Doc
+[tool.hatch.envs.doc]
+dependencies = [
+    "mkdocs",
+    "mkdocstrings-python"
+]
+
+[tool.hatch.envs.doc.scripts]
+serve = "mkdocs serve"
+deploy = "mkdocs gh-deploy"