From 8c1a4d6536dd48988d51ff08f83c861cd9482a2d Mon Sep 17 00:00:00 2001 From: Adrien Perrin Date: Tue, 19 Mar 2024 13:51:27 +0000 Subject: [PATCH] update README --- README.md | 67 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 42 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index f219cc2..52fe0fe 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,44 @@ -Django-Geo-SPaaS - GeoDjango Apps for satellite data management -=========================================================== +# Django-Geo-SPaaS - GeoDjango Apps for satellite data management [![Unit tests and build](https://github.com/nansencenter/django-geo-spaas/actions/workflows/ci.yml/badge.svg)](https://github.com/nansencenter/django-geo-spaas/actions/workflows/ci.yml) [![Coverage Status](https://coveralls.io/repos/github/nansencenter/django-geo-spaas/badge.svg?branch=master)](https://coveralls.io/github/nansencenter/django-geo-spaas) [![DOI](https://zenodo.org/badge/84077597.svg)](https://zenodo.org/badge/latestdoi/84077597) -How to use Docker for development of Django-Geo-SPaaS ------------------ +## About + +GeoSPaaS is a set of Python tools meant to help scientists deal with Earth Observation data. +django-geo-spaas is the core of GeoSPaaS. It is composed of several +[GeoDjango](https://docs.djangoproject.com/en/5.0/ref/contrib/gis/) apps which provide basic +functionalities: +- `geospaas.catalog`: defines the structure of GeoSPaaS's catalog, which is used to store metadata + about Earth Observation datasets. This is the core around which all GeoSPaaS functionalities are + built. +- `geospaas.vocabularies`: defines a structured way to assign properties to the datasets in the + catalog. Based on and compatible with the + [GCMD standard](https://www.earthdata.nasa.gov/learn/find-data/idn/gcmd-keywords). +- `geospaas.base_viewer`: a basic web page which allows to view the contents of the catalog. +- `geospaas.nansat_ingestor`: data ingester based on + [Nansat](https://github.com/nansencenter/nansat). Can be used to populate a catalog. The preferred + tool for this is now + [django-geo-spaas-harvesting](https://github.com/nansencenter/django-geo-spaas-harvesting). +- `geospaas.export_DIF`: app for exporting metadata to GCMD DIF format. + +## Usage + +To make use of `django-geo-spaas`, you need to install the apps in a GeoDjango project. +To set up such a project, you can follow the instructions here: +https://docs.djangoproject.com/en/5.0/ref/contrib/gis/tutorial/. + +You can also go through the workshops in the following repository to learn more about GeoSPaaS and +see some practical uses: https://github.com/nansencenter/geospaas-workshops. + +## Using Docker + +Docker can be used to set up a GeoSPaaS project more easily. +You will find instructions below for a basic set-up. + +### How to use Docker for development of Django-Geo-SPaaS + 1. [Install Docker](https://docs.docker.com/install/) 2. Clone `django-geo-spaas` and change into that directory 3. Run `./build_container.sh`. That will do the following: @@ -30,8 +62,8 @@ And then run `docker start -i geospaas` to go into the container and have access and then execute commands in the runnning container: `docker exec -i geospaas project/manage.py shell` -How to use Docker for running Django-Geo-SPaaS ------------------ +### How to use Docker for running Django-Geo-SPaaS + If you already have a project directory or if you are working on another app you can use the existing Docker image with Django-Geo-SPaaS. The image is already uploaded to Docker Hub, so no above steps are necessary. The workflow can be the following: @@ -40,14 +72,11 @@ so no above steps are necessary. The workflow can be the following: 3. Run Django commands from your host: ``` # create container named myapp from Docker image geospaas -docker create -it --name=myapp \ +docker run -it --rm --name=myapp \ -v /host/dir/myapp:/src \ -v /data/dir:/data \ nansencenter/geospaas -# start container in background -docker start myapp - # create project dir in /host/dir/myapp docker exec myapp django-admin startproject myproject @@ -102,19 +131,7 @@ docker exec myapp /src/myproject/manage.py update_vocabularies docker exec -w /src/myproject myapp ./manage.py ingest /data/myfiles*.nc ``` -How to add new data to Geo-SPaaS catalog ----------------------------------------- -Previsouly Vagrant/VirtualBox was used as a main provisionng mechanism. This is no longer supported. +## How to add new data to a GeoSPaaS catalog -Install geo-spaas-vagrant: -``` - git clone https://github.com/nansencenter/geo-spaas-vagrant - cd geo-spaas-vagrant - vagrant up geospaas_core -``` -Connect to the virtual machine and use GeoSPaaS -``` - vagrant ssh geospaas_core - cd django-geo-spaas/project - ./manage.py ingest name_of_your_file -``` +The [django-geo-spaas-harvesting](https://github.com/nansencenter/django-geo-spaas-harvesting) +app can be used to populate a GeoSPaaS catalog.