VegBank

• License: Apache 2
• Package source code on GitHub
• Submit Bugs and feature requests
• Contact us: help@vegbank.org

Citation and Overview

Jim Regetz, Robert Shelton, Darian Gill, Matthew B. Jones, Dou Mok, Matthew Brooke, Rushiraj Nenuji, Jeanette Clark, Maggie Klope, Michael T. Lee, Robert K. Peet. 2026. VegBank: the open-access vegetation plot database and API of the Ecological Society of America’s Panel on Vegetation Classification. Version 2.1.1. VegBank. doi:10.82902/J1WC7G.

The VegBank data system provides a community managed data portal for vegetation plot data, with special emphasis on supporting the U.S. National Vegetation Classification (USNVC) and validating standard USNVC vegetation types. VegBank is a product of the Ecological Society of America (ESA) Panel on Vegetation Classification and is maintained and operated by the National Center for Ecological Analysis and Synthesis (NCEAS).

VegBank provides a common storage system and services for accessing:

• Plot data
• Plant taxonomy data
• Community data

VegBank is an open source, community project. We welcome contributions in many forms, including code, graphics, documentation, bug reports, testing, etc. Use the VegBank discussions to discuss these contributions with us.

Redesign

VegBank was originally designed and implemented in the early 2000s using server technology of the time, particularly as a Java servlet providing access to data that is stored in a backend PostgreSQL database, and using Apache Struts to build a web-based interface for querying and viewing the data. While the system has served well, most of these technology components have become obsolete, and need to be replaced.

As part of the VegBank redesign effort, the original monolithic system has been refactored into multiple standalone components:

• vegbank-service: the VegBank data storage system and REST API (this repository)
• vegbankr: the VegBank R package that accesses the service
• vegbank-web: the VegBank web application that accesses the service

VegBank REST API

The VegBank REST API is the primary interface for interacting with the data system. While this repository contains the service's source code, most users will interact with the production instance hosted and maintained by NCEAS. The API provides a programmatic way to search and retrieve vegetation plot records, plant concepts, community types, and other supporting information, as well as submit and upload new data to the archive.

• Comprehensive API documentation (WIP): https://nceas.github.io/vegbank2/api/
• API Authorization Guide: api-authorization.md – Detailed authentication, token usage, and scope system
• Production API: https://api.vegbank.org
• Development API: https://api-dev.vegbank.org

Development build

This is a python package managed with uv, a fast Python package and environment manager.

To run tests, navigate to the root directory and run uv run pytest.

The GitHub repository has also been configured to run a continuous integration build which executes uv run pytest in the uv-managed virtual environment. To test the action run locally, you can install the act commandline client (e.g., brew install act) and then execute the actions from the local commandline. This depends on a local docker instance being configured, and the first run will take longer as the initial docker images are pulled. Thereafter, checking the action build before pushing commits can be run, for example, for the Mac with:

• act --container-architecture linux/amd64

Installing vegbank locally

We are using uv as our python environment and dependency manager. To get started locally:

One-time setup

1. Provision a local database - see database/INSTALL.md for instructions on setting up a local postgres instance with the vegbank database and user.

2. Set the following environment variables in the shell where you will start the application. You can do this manually, or in your .bashrc or .zshrc file, etc:

   • VB_DB_NAME: database name (typically vegbank)
   • VB_DB_USER: the user that owns the db (typically also vegbank)
   • VB_DB_PORT: your psql port (typically 5432)
   • VB_DB_PASS: password for your db user
   • VB_ACCESS_MODE: access mode. Set to open (or "read_only", if you don't need to do uploads) (VB_DB_HOST is not needed for local development)

3. Install uv (if not already installed)

   $ python -m pip install uv --root-user-action ignore

Update and Run the Application

# Navigate to your project root
$ cd /path/to/vegbank2

# Create a project-local virtual environment
$ uv venv .venv

# Activate the virtual environment
$ source .venv/bin/activate

# Install project dependencies
$ uv sync --active

# Run the application
uv run flask --app src/vegbank/app.py run

Adding project dependencies

To add a dependency to this project, you will need to update pyproject.toml with the library that you are trying to add, as well as the minimum version required.

• Note: An easy way to add dependencies to pyproject.toml is to add them with uv or other package management tools using a command like uv add some_package.

• If the library is required at runtime, add it under dependencies

• If the library is used only for development or testing, add it under dependency-groups.dev

# pyproject.toml
dependencies = [
    "psycopg>=3.3.2",
    "flask>=3.1.2",
    "pandas>=3.0.0",
    "pyarrow>=23.0.0",
    "numpy>=2.4.2",
    "DEPENDENCYNAME>=#.#.#", # Add runtime dependencies here
]

[dependency-groups]
dev = [
    # Add development dependencies here
    "pytest>=8.3.3",
    "pylint>=3.2.7",
    "black>=24.8.0",
]

Building and Publishing the Docker Image

The vegbank service is published as a Docker image, for deployment via Helm on Kubernetes (see below). See the Docker README for instructions on building and publishing the image.

Installing vegbank on a Kubernetes Cluster, Using Helm

The vegbank Helm chart can be used to deploy the vegbank service on a Kubernetes cluster. See the Helm README for instructions. The deployment can use either:

• the local chart included in the vegbank source code (useful for development and testing), or
• a versioned, published chart from the GitHub Container Registry. Details for packaging and publishing new charts can be found in the Helm README.

Release Process

See the Release Checklist and the Contributing Guide for details on the release process

Current Contributors

• Jim Regetz (regetz@nceas.ucsb.edu): ORCID: 0009-0008-2666-6229
• Robert Shelton (rshelton@nceas.ucsb.edu): ORCID: 0009-0008-7478-8992
• Darian Gill (dgill@nceas.ucsb.edu): ORCID: 0009-0005-7848-2163
• Matthew B. Jones (jones@nceas.ucsb.edu): ORCID: 0000-0003-0077-4738
• Dou Mok (mok@nceas.ucsb.edu): ORCID: 0000-0002-6076-8092
• Matthew Brooke (brooke@nceas.ucsb.edu): ORCID: 0000-0002-1472-913X
• Rushiraj Nenuji (nenuji@nceas.ucsb.edu): ORCID: 0000-0003-4678-5213
• Jeanette Clark (jclark@nceas.ucsb.edu): ORCID: 0000-0003-4703-1974
• Maggie Klope (mmklope@nceas.ucsb.edu): ORCID: 0000-0003-3926-7039
• Michael T. Lee (michael.lee@unc.edu): ORCID: 0009-0003-3874-8604
• Robert K. Peet (peet@unc.edu): ORCID: 0000-0003-2823-6587

Previous Contributors

• Michael D. Jennings
• Dennis Grossman
• Marilyn D. Walker
• Mark Anderson
• Gabriel Farrell
• John Harris
• Chad Berkley

License

Copyright [2026] [Regents of the University of California]

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Acknowledgments

Work on this package was supported by:

• California Department of Fish and Wildlife
• DataONE Network
• National Center for Ecological Analysis and Synthesis, a Center funded by the University of California, Santa Barbara, and the State of California.
• National Science Foundation