Skip to content

README.md

Latest commit

 

History

History
74 lines (49 loc) · 3.72 KB

README.md

File metadata and controls

74 lines (49 loc) · 3.72 KB
Raw

cwms-batch-events

CWMS Batch Events provides users an API and user interface to execute water management jobs on a manual or event-driven basis.

Contributions

To get your local environment setup and/or make contributions please see the contributions documentation: CONTRIBUTING.md

GitHub Codespaces

The repository's development container prepares a complete environment for GitHub Codespaces, including Python 3.12 and all test dependencies, Node.js 22 and the UI dependencies, Docker Compose with an isolated Docker daemon, the external cwms Docker network required by the local stack, and editor support for Python, TypeScript, ESLint, and Docker.

Create a Codespace for this repository and wait for its setup to finish. The mounted checkout is used directly for Python imports, and ui/node_modules is installed from the committed lockfile. No credentials or repository secrets are required for the default mock-user development flow.

Verify the environment with:

python -m pytest -q
npm --prefix ui run lint
npm --prefix ui run build
docker compose config --quiet

Start the local service stack and UI in separate terminals:

docker compose up --build
npm --prefix ui run dev -- --host 0.0.0.0

Codespaces forwards the UI, API, MinIO console, and ElasticMQ UI ports automatically. Use the forwarded URLs shown in the Ports panel rather than assuming localhost from outside the Codespace.

Run the Dev Container locally on Windows

Install and start Docker Desktop in Linux container mode, and ensure Node.js and npm are available. From a PowerShell prompt at the repository root, build and start the development container on the local Docker host with:

npx -y @devcontainers/cli up --workspace-folder .

Open a shell in the running development container with:

npx -y @devcontainers/cli exec --workspace-folder . bash

Docker Desktop runs the development container itself. The development container's Docker-in-Docker feature provides the isolated Docker daemon used by the project's Compose stack.

Local Development Setup

Critical URLs

page url
ElasticMQ Web Interface http://localhost:9325
Minio Web Interface http://localhost:9001
Web Dev Server http://localhost:5173
Swagger Docs http://localhost:8000/docs
Redoc http://localhost:8000/redoc

Python

For the best experience, pyenv is recommended for install instructions. If pyenv is available, the setup-pyenv.sh script is provided to create a virtual environment and install the necessary local dev requirements. Be sure to install gcc for your environment.

Authentication

By default, the local instance of the API uses a mock user account. This account has script-execute permissions for all districts. As a result, the API will return scripts for all offices that contain a corresponding script catalog within the minio instance.

Script Containers

The API will reference district script docker images that exist locally by the name [office-code]-jobs, e.g. lrh-jobs. These can be created by cloning the corresponding district jobs repo, e.g. lrh-wm-cwbi-jobs, and building the images from the local dockerfile with docker build . -t [office-code]-jobs.

Script Catalogs

Available district scripts are managed within the cwms-batch application itself using the "Scripts Manager" available through the Web UI or directly through API endpoints.

User Interface

The user interface is deployed locally as a vite development server. To run it, simply enter the ui directory and run npm run dev.