Installation

Development Installation

Pre-Requirements

The Brazil Data Cube STAC implementation depends essentially on:

Flask: a lightweight WSGI web application framework.
Flask-SQLAlchemy: an extension for Flask that adds support of SQLAlchemy.
BDC-Catalog (v1.0+): an image metadata storage module for Earth Observation imagery of Brazil Data Cube.
Flask-Redoc: a Flask extension for displaying OpenAPI/Swagger documentation using Redocs.

All these libraries can be easily installed in the next steps.

STAC Versions

Before installing the BDC-STAC server, please, take a look into compatibility table:

STAC API Spec	BDC-STAC	BDC-Catalog
0.8.x	0.8.x	0.4.x
0.9.0 - 1.0.0-rc.1	0.9.x	0.8.x
1.0.0-beta.1 - 1.0.0-rc.1	1.0.0	1.0.0
1.0.0	1.0.1	1.0.1
1.0.0	1.0.2	1.0.2

Clone the software repository

Use git to clone the software repository:

git clone https://github.com/brazil-data-cube/bdc-stac.git

Install BDC-STAC in Development Mode

Go to the source code folder:

$ cd bdc-stac

Install in development mode:

$ pip3 install -U pip setuptools wheel
$ pip3 install -e .[all]

Note

If you want to create a new Python Virtual Environment, please, follow this instruction:

1. Create a new virtual environment linked to Python 3.8:

python3.8 -m venv venv

2. Activate the new environment:

source venv/bin/activate

3. Update pip and setuptools:

pip3 install --upgrade pip setuptools wheel

Build the Documentation

You can generate the documentation based on Sphinx with the following command:

python setup.py build_sphinx

The above command will generate the documentation in HTML and it will place it under:

docs/sphinx/_build/html/

You can open the above documentation in your favorite browser, as:

firefox docs/sphinx/_build/html/index.html

Running in Development Mode

Note

Make sure you have a database prepared using Brazil Data Cube Catalog Module. You can achieve a minimal database with Docker using the following steps:

docker run --name bdc_pg \
           --detach \
           --volume bdc_catalog_vol:/var/lib/postgresql/data \
           --env POSTGRES_PASSWORD=postgres \
           --publish 5432:5432 \
           postgis/postgis:15-3.3

Once container is up and running, initialize the database:

export SQLALCHEMY_DATABASE_URI="postgresql://postgres:postgres@localhost:5432/bdcdb"
bdc-db db init
bdc-db db create-namespaces
bdc-db db create-extension-postgis
bdc-db db create-schema # For devmode
# bdc-db alembic upgrade  # For prod (recommended)

After that, you can download a minimal collection sentinel-2.json JSON example and then load it with BDC-Catalog command line:

export SQLALCHEMY_DATABASE_URI="postgresql://postgres:postgres@localhost:5432/bdcdb"
bdc-catalog load-data --ifile /path/to/sentinel-2.json

In the source code folder, enter the following command:

$ FLASK_APP="bdc_stac" \
  SQLALCHEMY_DATABASE_URI="postgresql://postgres:postgres@localhost:5432/bdcdb" \
  BDC_STAC_BASE_URL="http://localhost:5000" \
  BDC_STAC_FILE_ROOT="http://localhost:5001" \
  flask run

You may need to replace the definition of some environment variables:

SQLALCHEMY_DATABASE_URI="postgresql://postgres:postgres@localhost:5432/bdcdb": set the database URI connection.

BDC_STAC_BASE_URL="http://localhost:5000": Base URI of the service.

BDC_STAC_FILE_ROOT="http://localhost:5001": File root for the Assets.

BDC_STAC_MAX_LIMIT: Set number of maximum items fetched per request. Default is 1000.

BDC_STAC_TITLE: Set the catalog title.

BDC_STAC_ID: Set the catalog identifier.

To add authentication support with Brazil Data Cube OAuth 2.0, use the following:

BDC_AUTH_CLIENT_ID: The OAuth 2.0 client identification

BDC_AUTH_CLIENT_SECRET: The OAuth 2.0 client secret

BDC_AUTH_ACCESS_TOKEN_URL: The URL domain of BDC-OAuth 2.0 provider.

Note

The parameter BDC_STAC_FILE_ROOT is used to concat the Item asset and then generate a display URL that will be served by a HTTP Server. In this case, you will need to have a HTTP Server like NGINX or Apache HTTPD.