https://github.com/nceas/vegbank2
Design and development for VegBank
https://github.com/nceas/vegbank2
vegbank
Last synced: 2 months ago
JSON representation
Design and development for VegBank
- Host: GitHub
- URL: https://github.com/nceas/vegbank2
- Owner: NCEAS
- License: apache-2.0
- Created: 2015-09-16T20:27:19.000Z (over 10 years ago)
- Default Branch: main
- Last Pushed: 2026-03-31T23:42:31.000Z (3 months ago)
- Last Synced: 2026-04-01T01:28:53.328Z (3 months ago)
- Topics: vegbank
- Language: Python
- Homepage: http://vegbank.org
- Size: 7.22 MB
- Stars: 3
- Watchers: 5
- Forks: 0
- Open Issues: 38
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# VegBank
- **License**: [Apache 2](http://opensource.org/licenses/Apache-2.0)
- [Package source code on GitHub](https://github.com/NCEAS/vegbank2)
- [**Submit Bugs and feature requests**](https://github.com/NCEAS/vegbank2/issues)
- 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](https://doi.org/10.82902/J1WC7G).
The [VegBank](http://vegbank.org) 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](https://esa.org/vegpanel/)
and is maintained and operated by the [National Center for Ecological Analysis and
Synthesis](https://www.nceas.ucsb.edu) (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](./CONTRIBUTING.md) in many
forms, including code, graphics, documentation, bug reports, testing, etc. Use the [VegBank
discussions](https://github.com/NCEAS/vegbank2/discussions) to discuss these contributions with us.
## Redesign
VegBank was originally [designed and implemented](https://github.com/NCEAS/vegbank) 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](vegbank2-plans.md), the original monolithic system has been
refactored into multiple standalone components:
- [vegbank-service](.): the VegBank data storage system and REST API (this repository)
- [vegbankr](https://github.com/NCEAS/vegbankr): the VegBank R package that accesses the service
- [vegbank-web](https://github.com/NCEAS/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](./helm/docs/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`](https://docs.astral.sh/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](https://github.com/NCEAS/vegbank2/actions) 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](./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)
```shell
$ python -m pip install uv --root-user-action ignore
```
#### Update and Run the Application
```shell
# 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`
```py
# 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](./docker/README.md) 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](./helm/README.md) for instructions. The deployment can use either:
- the [local chart included](./helm) in the `vegbank` source code (useful for development and testing), or
- a versioned, published chart from the [GitHub Container Registry](https://github.com/NCEAS/vegbank2/pkgs/container/charts%2Fvegbank). Details for packaging and publishing new charts can be found [in the Helm README](./helm/README.md#packaging-and-publishing-the-helm-chart).
## Release Process
See the [Release Checklist](./release-checklist.md) and the [Contributing Guide](./CONTRIBUTING.md#-release-process) for details on the release process
## Current Contributors
- Jim Regetz (regetz@nceas.ucsb.edu): [ORCID: 0009-0008-2666-6229](https://orcid.org/0009-0008-2666-6229)
- Robert Shelton (rshelton@nceas.ucsb.edu): [ORCID: 0009-0008-7478-8992](https://orcid.org/0009-0008-7478-8992)
- Darian Gill (dgill@nceas.ucsb.edu): [ORCID: 0009-0005-7848-2163](https://orcid.org/0009-0005-7848-2163)
- Matthew B. Jones (jones@nceas.ucsb.edu): [ORCID: 0000-0003-0077-4738](https://orcid.org/0000-0003-0077-4738)
- Dou Mok (mok@nceas.ucsb.edu): [ORCID: 0000-0002-6076-8092](https://orcid.org/0000-0002-6076-8092)
- Matthew Brooke (brooke@nceas.ucsb.edu): [ORCID: 0000-0002-1472-913X](https://orcid.org/0000-0002-1472-913X)
- Rushiraj Nenuji (nenuji@nceas.ucsb.edu): [ORCID: 0000-0003-4678-5213](https://orcid.org/0000-0003-4678-5213)
- Jeanette Clark (jclark@nceas.ucsb.edu): [ORCID: 0000-0003-4703-1974](https://orcid.org/0000-0003-4703-1974)
- Maggie Klope (mmklope@nceas.ucsb.edu): [ORCID: 0000-0003-3926-7039](https://orcid.org/0000-0003-3926-7039)
- Michael T. Lee (michael.lee@unc.edu): [ORCID: 0009-0003-3874-8604](https://orcid.org/0009-0003-3874-8604)
- Robert K. Peet (peet@unc.edu): [ORCID: 0000-0003-2823-6587](https://orcid.org/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
[](https://www.nceas.ucsb.edu)