USDA-ARS Geospatial Common Data Library (GeoCDL)

Installing the GeoCDL

1. Make sure you have a recent release of Python 3 installed.
2. Clone this git repository.
3. Run pip install -r requirements.txt.
4. You will need to create directories for local data, dataset build outputs, the dataset upload cache, and logging.

Running the GeoCDL

1. Move to the src directory (cd src).
2. Run uvicorn api_main:app --reload.
3. API endpoints will be available at http://127.0.0.1:8000/ (e.g., http://127.0.0.1:8000/ds_info?id=DaymetV4).
4. API documentation will be available at http://127.0.0.1:8000/docs.

Running the GeoCDL in a Singularity container

1. Clone this git repository.
2. Build the Singularity image. From the main repo directory, run

   sudo singularity build geocdl.sif geocdl.def

   or, if you do not have root privileges,

   singularity build --fakeroot geocdl.sif geocdl.def

3. Run the GeoCDL in a Singularity container. To avoid needing to rebuild the container image every time the source code changes, the source directory is maintained outside of the container image and mounted read-only inside the container at run time. Local data storage is also mounted read-only inside the container; the output, upload cache, and logging directories are mounted read/write inside the container. Be default, the container is bound directly to the host's network, so explicit port mapping is not required.

   singularity run \
     --mount type=bind,src=/path/to/geocdl/src,dst=/geocdl/src,ro \
     --mount type=bind,src=/path/to/local_data,dst=/geocdl/local_data,ro \
     --mount type=bind,src=/path/to/output,dst=/geocdl/output \
     --mount type=bind,src=/path/to/uploads,dst=/geocdl/upload \
     --mount type=bind,src=/path/to/logdir,dst=/geocdl/logs \
     geocdl.sif

Running the GeoCDL in a Docker container

1. Clone this git repository.
2. Build the Docker image. From the main repo directory, run

   docker build -t geocdl[:tag] .

3. Run the GeoCDL in a Docker container. To avoid needing to rebuild the container image every time the source code changes, the source directory is maintained outside of the container image and mounted read-only inside the container at run time. Local data storage is also mounted read-only inside the container; the output, upload cache, and logging directories are mounted read/write inside the container. Here, we bind the container directly to the host's network, which is convenient for testing/development purposes, but not ideal for all production situations. For production, mapping specific ports might be preferred.

   docker run \
     --mount type=bind,src=/path/to/geocdl/src,dst=/geocdl/src,ro \
     --mount type=bind,src=/path/to/local_data,dst=/geocdl/local_data,ro \
     --mount type=bind,src=/path/to/output,dst=/geocdl/output \
     --mount type=bind,src=/path/to/uploads,dst=/geocdl/upload \
     --mount type=bind,src=/path/to/logdir,dst=/geocdl/logs \
     --network host \
     geocdl

Current datasets