Skip to content

docs: add Getting Started guide — Docker deployment, first login, and data entry walkthrough #12

@jeandavidt

Description

@jeandavidt

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

  • Guide is reachable from the docs home page
  • A user with no prior knowledge can follow it end-to-end
  • All key concepts (SignalPort, Channel, SCADA tag, Observation, Value) are defined
  • Docker deployment steps are tested and accurate for the current docker-compose.yml

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions