Core Project:

UI:

Docker documentation

OpenDCS

OpenDCS is a tool for doing the following:

• retrieving data from the NOAA GOES Satellite system and processing it to a more usual form
• retrieving data from arbitrary systems
• near real-time timeseries data processing.

OpenDCS is currently used by:

• U.S. Army Corps of Engineers
• U.S. Bureau of Reclamation
• U.S. National Oceanic and Atmospheric Administration

And others.

If you're agency/company/etc uses OpenDCS and wishes that to be known, please submit either an issue indicating you would like the name added, or a pull request that updates the list above. Company/Agency Logos are welcome in place of plain text.

Getting started

Documentation on how to use OpenDCS is available at https://opendcs-env.readthedocs.io/en/latest/index.html

Getting help

We have a mailing list at https://www.freelists.org/list/opendcs.

Additionally you can open a discussion at https://github.com/opendcs/opendcs/discussions

Contributing

First of, if you feel a desire to contribute - which to us includes trying to use the software and reporting issues - thanks!

Checkout the CONTRIBUTING.md file, and don't be too scared by all the legalese; the project started at several government agencies who have chosen to properly open source the project and we felt a little solid copy-pasting from other government contributing documents was a good idea.

The short version is, add you're name to the CONTRIBUTORS.md file, and submit changes to the default branch, currently named master.

As for what to contribute: https://github.com/opendcs/opendcs/projects shows our current major projects, as well as a project each for tracking bugs and features; Wiki (https://github.com/opendcs/opendcs) pages prefixed with "Project -" will have more information about some projects. If you want to contribute and aren't sure where to start that should be a good place to see our plans and priorities; please do not hesitate to ask questions on the mailing list, discussions, or within an issue itself.

We are currently in the process of some major overhauls to various subsystems and while that can be scary we would like to encourage you to join us anyways.

Compiling

• OpenDCS is compiled using the gradle wrapper 'gradlew'
• OpenDCS latest/8.x requires Java 21 for compiling and runtime
• OpenDCS 7.x targets Java 8. A JDK 8 is recommended for build though 11 and 17 will work

in the following examples replace ./gradlew with gradlew if you are using windows.

To build the file opendcs.jar run the following command:

./gradlew :opendcs:jar

output is here:

java/opendcs/build/libs/opendcs-main.99.main-SNAPSHOT.jar

If you want to build a distribution run:

./gradlew distZip

or

./gradlew distTar

output is here:

opendcs/install/build/distributions/opendcs-main.99.main-SNAPSHOT.zip

To get a simple baseline environment going:

./gradlew runApp --info

This will start the "launcher_start" application and do an initial setup of an XML database suitable for DECODES operations going that you can use for manual and exploratory testing.

The table below lists features of the runApp task.

Option	Default Value	Description
opendcs.app	launcher_start	Application to run
opendcs.profile	default	Profile to use
opendcs.lang	-	Language to use
opendcs.arg	-	Additional application arguments
opendcs.jfr	false	Enable Java Flight Recorder
opendcs.debug	0	Debug port number

Here is an example:

gradlew runApp -Popendcs.app=rs -Popendcs.profile="%appdata%\.opendcs\xml.profile" -Popendcs.arg=issue877 -Popendcs.debug=5005

General Development

GitHub Codespaces and development containers

The repository includes a development container that can be opened directly in GitHub Codespaces or with the VS Code Dev Containers extension. It provides Java 21, Node.js 22, Python 3.8, Docker, the browser dependencies used by the web tests, and a lightweight desktop for running the Swing applications.

The first container creation installs the web dependencies and Playwright's Chromium and Firefox browsers. After it finishes, verify the environment with:

./gradlew assemble testClasses

Docker runs inside the development container, so the PostgreSQL integration tests and the services in docker-compose.yaml work without additional host setup. Open the forwarded OpenDCS desktop port to interact with Swing applications; the REST API, web UI, Storybook, Keycloak, pgAdmin, PostgreSQL, and Java debugger ports are also labeled in the Ports panel.

To verify everything can work on your system run the following:

# General tests

./gradlew test -Pno.docs=true

# Those are the unit tests, including the LRGS tests and the web UI storybook tests. The
# storybook tests need Playwright browsers, which Gradle does not install for you:
#     cd javascript/opendcs-web-ui-react && npx playwright install
# Until those are installed, skip them with:
./gradlew test -x :opendcs-web-ui-react:testStorybook

# Just the LRGS tests

./gradlew :testing:lrgs:test -Pno.docs=true

# Tests of a "live" system, one engine at a time. OpenDCS-XML needs no external database, the
# others need docker, and CWMS-Oracle is the most memory hungry.
./gradlew :testing:opendcs-tests:testOpenDCSXML
./gradlew :testing:opendcs-tests:testOpenDCSPostgres
./gradlew :testing:opendcs-tests:testOpenDCSOracle
./gradlew :testing:opendcs-tests:testCWMSOracle

Add -Pno.docs=true to any of these to skip building the documentation, which otherwise comes in as a dependency of the install distribution. Reports land under <project>/build/reports/tests/test, for example java/opendcs/build/reports/tests/test.

This will run all of the various tests and let you know you have everything setup such that you can start development.

For all test tasks you can add --debug-jvm and the JVMs started will wait for a debug connection on port 5005.

To run a specific test only use:

./gradlew <test target> --tests <pattern> # See [gradle documentation ](https://docs.gradle.org/current/userguide/java_testing.html#simple_name_pattern) for more detail

example with debugging:

./gradlew :opendcs:test -Pno.docs=true --tests decodes.xml.XmlDatabaseTest --debug-jvm

Note that --tests only filters the test tasks named on the command line. Any test task pulled in as a dependency still runs in full — for example :testing:opendcs-tests:testOpenDCSXML chains :opendcs:test unless the CI environment variable is set.

It is possible a file glob will work in the tests parameter above but we have not tested this.

See https://opendcs-env.readthedocs.io/en/latest/dev-docs.html for guidance on some of the newer components.

IDE integration

While the OpenDCS maintainers don't have time to maintain files for other IDEs, we want to make it as easy as possible for anyone to help and will welcome baseline configuration for others. If you wish to help in this way please created additional targets and required files to generate them.

Visual Studio Code or Eclipse

To create the appropriate project files for VS Code or Eclipse you can run the following task:

./gradlew opendcs:eclipse

Or you can use the VS Code gradle integration.

This will create the appropriate .project and .classpath files for intellisense to behave correctly.

Intellij

Intellij detects the gradle project and has a Gradle tool window.

Some gradle tasks require a python environment. Here is an example that launches inteliJ from a conda environment to have python enabled. (base) C:>conda activate karl (karl) C:\project\opendcs>C:\Programs\ideaIC-2022.1.win\bin\idea64.exe

rest_api

OpenDCS Rest API is web application that provides access to the OpenDCS database using JSON (Java Script Object Notation). OpenDCS Rest API is intended to run as a stand-alone Java program. It uses embedded JETTY to implement the web services.

Structure

./java/opendcs-rest-api - contains source files for the OpenDCS REST API ./javascript/opendcs-web-ui-react - contains source files for the OpenDCS Web Application Client ./opendcs-integration-test - contains scripts for running embedded tomcat to deploy the REST API and Web Client wars for testing.

Building

JDK 21 and Node 22 or higher are required to build the project.

OPENDCS API

The gradle task ./gradlew :opendcs-rest-api:war will create a war file in the build/libs directory.

The SwaggerUI location can be found at the relative url path of //swaggerui. Assuming the context is 'odcsapi', an example of the SwaggerUI location is http://localhost:8080/odcsapi/swaggerui. These files are being served up from the resource file 'SwaggerResources.java' file located at 'src/main/java/org/opendcs/odcsapi/res/SwaggerResources.java'.

OPENDCS Web Client

The gradle task ./gradlew :opendcs-web-ui-react:build will create a war file in the build/dist directory.

Additional the UI project is a react act, if you cd into javascript/opendcs-web-ui-react the usual npm commands will work.

Testing

If you are on a platform with Docker, or establish the appropriate database configuration override properties you can run the api and web ui with the following:

./gradlew runApi --info
# The appropriate link will be provided in the terminal output, by default it will be http://localhost:7000.

The default user name and password are test_user and test_password

Useful -P options for runApi:

• -Popendcs.test.integration.db=CWMS-Oracle - run against a CWMS Oracle database instead of the default OpenDCS-Postgres.
• -Popendcs.runApi.userOffices=SPK,SPD - grant the test user roles in multiple offices so the UI's Change Organization menu has entries to switch between (requires CWMS-Oracle, which is the only implementation with organizations). Office codes must exist in the database; the CWMS test container ships SPK, SPD, SWT, HQ and other NWS office codes.
• -Popendcs.runApi.seedData=<dir> - load extra data from <dir>/decodes/*.xml and <dir>/comps/*.xml on top of the baseline database.

When running with organizations (CWMS-Oracle), select the office to sign in with on the login page (or leave the default and switch later via the Change Organization menu in the top bar). Credentials are sent against the blank organization - the selected office is applied to the session after authentication, and is reset if the user is not authorized there.

Example two-office run:

./gradlew :testing:opendcs-tests:runApi \
  -Popendcs.test.integration.db=CWMS-Oracle \
  -Popendcs.runApi.userOffices=SPK,SPD
# Startup log confirms: "Granting API roles to the test user in organizations: [SPK, SPD]"

Financial Information

For additional details, including dollar amounts, see: https://opencollective.com/opendcs

Per supporter Level

Total