Merge pull request #225 from raphaelrpl/reuse-cube

Review usage/setup docs

Author: raphaelrpl

CHANGES.rst

@@ -10,11 +10,12 @@
 Changes
 =======
 
-Version 0.8.1 (2022-09-13)
+Version 0.8.1 (2022-09-14)
 --------------------------
 
-- Fix search images using temporal dimension `#221 <https://github.com/brazil-data-cube/cube-builder/issues/221> `_.
+- Fix search images using temporal dimension `#221 <https://github.com/brazil-data-cube/cube-builder/issues/221>`_.
 - Add way to retrieve total items per tile
+- Improve Usage/Setup documentation `#164 <https://github.com/brazil-data-cube/cube-builder/issues/164>`_.
 
 
 Version 0.8.0 (2022-05-05)

DEPLOY.rst

@@ -17,22 +17,51 @@ If you do not have Docker installed, take a look at `this tutorial on how to ins
 See also the `tutorial on how to install Docker Compose <https://docs.docker.com/compose/install/>`_.
 
 
+Compatibility
+-------------
+
+Before deploy/install ``Cube-Builder``, please, take a look into compatibility table:
+
++--------------+-------------+
+| Cube-Builder | BDC-Catalog |
++==============+=============+
+| 0.8.x        | 0.8.2       |
++--------------+-------------+
+| 0.4.x, 0.6.x | 0.8.1       |
++--------------+-------------+
+| 0.2.x        | 0.2.x       |
++--------------+-------------+
+
+
 Configuration
 -------------
 
-docker-compose.yml
-~~~~~~~~~~~~~~~~~~
+Before proceed to the ``DEPLOY`` step, we have prepared a minimal ``docker-compose.yml`` file
+with config to launch ``Cube-Builder``.
+By default, it will generate data cubes in directories ``./volumes/data`` and ``./volumes/workdir``, respectively.
+You may set a different location editing the ``docker-compose.yml`` file. Please refer to the page :doc:`configuration`
+for further details.
 
-Open and edit **docker-compose.yml** with the following variables:
+.. note::
 
-1. **DATA_DIR** - Path to store collections.
-2. **SQLALCHEMY_DATABASE_URI** - Database URI.
-3. **RABBIT_MQ_URL** - URI to connect on RabbitMQ protocol.
+    Take a look into ``docker-compose.yml`` the variables ``DATA_DIR`` and ``WORK_DIR``
+    and make sure you have enough space in disk for data cubes.
 
 
 Running the Docker Containers
 -----------------------------
 
+.. note::
+
+    Make sure you have a machine with at least the following requirements:
+
+        - 4 vCPU or more
+        - 8 GB RAM
+        - 40 GB free space
+
+    It may change according the type/volume size of collections used to generate data cube.
+
+
 .. note::
 
     If you do not have a PostgreSQL instance with the Brazil Data Cube data model up and running, you will need to prepare one before following the rest of this documentation.
@@ -99,14 +128,13 @@ If the above command runs successfully, you will be able to list the launched co
 
 .. note::
 
-    Refer to the `USING.rst <USING.rst>`_ documentation in order to use the cube builder services.
+    Refer to the page :doc:`usage` documentation in order to use the cube builder services.
 
 
 .. rubric:: Footnotes
 
 .. [#f1]
 
-    | For now you will need to login into the BDC registry:
+    | By default, the docker compose will try to build a new Docker image
+    | If you have account in the BDC registry, you may use as following:
     | ``$ docker login registry.dpi.inpe.br``
-    |
-    | In the next releases we will get ride of this internal registry.

INSTALL.rst

@@ -30,6 +30,19 @@ The ``Cube Builder`` depends essentially on:
 - `Brazil Data Cube Catalog Module <https://github.com/brazil-data-cube/bdc-catalog.git>`_
 
 
+Compatibility
+-------------
+
++--------------+-------------+
+| Cube-Builder | BDC-Catalog |
++==============+=============+
+| 0.8.x        | 0.8.2       |
++--------------+-------------+
+| 0.4.x, 0.6.x | 0.8.1       |
++--------------+-------------+
+| 0.2.x        | 0.2.x       |
++--------------+-------------+
+
 Development Installation
 ------------------------
 
@@ -102,10 +115,15 @@ The ``Cube Builder`` uses `BDC-DB <https://github.com/brazil-data-cube/bdc-db/>`
 
     If you already have a database instance with the Brazil Data Cube data model, you can skip this section.
 
+In order to proceed with installation, you will need ``PostgreSQL with PostGIS``. We have already prepared a minimal
+instance in ``docker-compose.yml``. You may use it as following::
+
+    docker-compose up -d postgres
+
 
 We have prepared a script to configure the database model::
 
-    SQLALCHEMY_DATABASE_URI="postgresql://postgres:password@host:port/bdc" ./deploy/configure-db.sh
+    SQLALCHEMY_DATABASE_URI="postgresql://postgres:postgres@localhost/bdc" ./deploy/configure-db.sh
 
 
 
@@ -115,19 +133,22 @@ Launch the ``Cube Builder`` service
 
 In the source code folder, enter the following command::
 
-    $ FLASK_ENV="development" \
-      DATA_DIR="/data" \
-      SQLALCHEMY_DATABASE_URI="postgresql://postgres:password@host:port/bdc" \
-      cube-builder run
+    FLASK_ENV="development" \
+    WORK_DIR="/workdir" \
+    DATA_DIR="/data" \
+    SQLALCHEMY_DATABASE_URI="postgresql://postgres:postgres@localhost/bdc" \
+    cube-builder run
 
 
 You may need to replace the definition of some environment variables:
 
 - ``FLASK_ENV="development"``: used to tell Flask to run in ``Debug`` mode.
 
+- ``WORK_DIR="/workdir"``: set path to store temporary cubes/processing.
+
 - ``DATA_DIR="/data"``: set path to store data cubes
 
-- ``SQLALCHEMY_DATABASE_URI="postgresql://postgres:password@host:port/bdc"``: set the database URI connection for PostgreSQL.
+- ``SQLALCHEMY_DATABASE_URI="postgresql://postgres:postgres@localhost/bdc"``: set the database URI connection for PostgreSQL.
 
 
 The above command should output some messages in the console as showed below::
@@ -146,8 +167,9 @@ Launch the ``Cube Builder`` worker
 
 Enter the following command to start ``Cube Builder`` worker::
 
+    WORK_DIR="/workdir" \
     DATA_DIR="/data" \
-    SQLALCHEMY_DATABASE_URI="postgresql://postgres:password@host:port/bdc" \
+    SQLALCHEMY_DATABASE_URI="postgresql://postgres:postgres@localhost/bdc" \
     cube-builder worker -l INFO --concurrency 8 -Q default,merge-cube,prepare-cube,blend-cube,publish-cube
 
 
@@ -161,12 +183,15 @@ You may need to replace the definition of some parameters:
 
 .. note::
 
-    The command line ``cube-builder worker`` is an auxiliary tool that wraps celery command line using ``cube_builder`` as context. In this way, all ``celery worker`` parameters are currently supported. See more in `Celery Workers Guide <https://docs.celeryproject.org/en/stable/userguide/workers.html>`_.
+    The command line ``cube-builder worker`` is an auxiliary tool that wraps celery command line
+    using ``cube_builder`` as context. In this way, all ``celery worker`` parameters are currently supported.
+    See more in `Celery Workers Guide <https://docs.celeryproject.org/en/stable/userguide/workers.html>`_.
 
 
 .. warning::
 
-    The ``Cube Builder`` can use a lot of memory for each concurrent process, since it opens multiple images in memory. You can limit the concurrent processes in order to prevent it.
+    The ``Cube Builder`` can use a lot of memory for each concurrent process, since it opens multiple images in memory.
+    You can limit the concurrent processes in order to prevent it.
 
 
 .. rubric:: Footnotes