Goal
Create a beginner-friendly Getting Started guide that takes a user from zero to their first recorded observation. This is the single most important onboarding document for new adopters.
Sections to Cover
1. Deploy with Docker
- Prerequisites (Docker,
.env.docker)
docker-compose up sequence (db → db-init → api → app)
- Verify: API docs at
localhost:8000/docs, web app at localhost:8501
2. First Login
- How to access the web interface
- Initial account / auth setup (if applicable)
3. Understand the Data Model (conceptual intro)
Explain the core concepts in plain language, connecting them to real WRRF operations:
| Concept |
What it means |
| Site |
A physical treatment plant or monitoring location |
| Equipment |
A physical instrument (e.g., a DO probe, flow meter) |
| SignalPort |
A logical output of an instrument (e.g., "DO channel", "temperature output") — one instrument can have many signal ports |
| Channel |
A time series stream — links a SignalPort to a Parameter + Unit. This is where measurements land |
| SCADA tag |
The string identifier used by a SCADA/data acquisition system to reference a signal port |
| Observation |
A raw reading event tied to a Channel with a timestamp |
| Value |
The numerical payload of an Observation (scalar, vector, matrix, or image) |
4. Add Your First Data Manually
- Create a Site
- Register Equipment and an EquipmentModel
- Create a SignalPort and bind it to a Channel
- Record a manual observation via the interface or API
5. Configure Automated Data Ingestion
- Tag-mode ingestion: map SCADA tags to SignalPorts so incoming data self-routes
- Tagless-mode ingestion: direct-connect stations that bypass tag resolution
- Link to architecture guide for full detail
6. Verify Data is Flowing
- How to query the latest values for a Channel
- What the Explore page in the UI shows
Notes
- The README already has a brief Docker quick-start — this guide should expand on it significantly
- Should be added to the MkDocs nav as a top-level "Getting Started" section
- Cross-link to architecture guides for deeper explanations
Acceptance Criteria
Goal
Create a beginner-friendly Getting Started guide that takes a user from zero to their first recorded observation. This is the single most important onboarding document for new adopters.
Sections to Cover
1. Deploy with Docker
.env.docker)docker-compose upsequence (db → db-init → api → app)localhost:8000/docs, web app atlocalhost:85012. First Login
3. Understand the Data Model (conceptual intro)
Explain the core concepts in plain language, connecting them to real WRRF operations:
4. Add Your First Data Manually
5. Configure Automated Data Ingestion
6. Verify Data is Flowing
Notes
Acceptance Criteria
docker-compose.yml