From 85610b4e92e6f3333e9a5eaba12106cec841cfe1 Mon Sep 17 00:00:00 2001 From: daniel-slaugh Date: Tue, 7 Jul 2026 09:33:24 -0600 Subject: [PATCH 1/2] Update django admin page documentation --- apps/docs/docs/.vitepress/config.ts | 2 +- .../hosting-and-deployment/how-to/index.md | 2 +- .../using-the-administrator-dashboard.md | 260 ++++++++++++++---- 3 files changed, 203 insertions(+), 61 deletions(-) diff --git a/apps/docs/docs/.vitepress/config.ts b/apps/docs/docs/.vitepress/config.ts index 4917d0b2..41fe01c7 100644 --- a/apps/docs/docs/.vitepress/config.ts +++ b/apps/docs/docs/.vitepress/config.ts @@ -265,7 +265,7 @@ export default defineConfig({ link: "/hosting-and-deployment/how-to/setting-up-a-production-deployment", }, { - text: "Using the Administrator Dashboard", + text: "Using the Django Admin Dashboard", link: "/hosting-and-deployment/how-to/using-the-administrator-dashboard", }, ], diff --git a/apps/docs/docs/hosting-and-deployment/how-to/index.md b/apps/docs/docs/hosting-and-deployment/how-to/index.md index a18cd563..439204fc 100644 --- a/apps/docs/docs/hosting-and-deployment/how-to/index.md +++ b/apps/docs/docs/hosting-and-deployment/how-to/index.md @@ -3,4 +3,4 @@ In this section, we provide documentation for organizations wanting to deploy and host their own instance of HydroServer. * **[Setting Up a Production Deployment](/hosting-and-deployment/how-to/setting-up-a-production-deployment.md)**: Learn how to deploy a HydroServer instance in a production environment. -* **[Using the Administrator Dashboard](/hosting-and-deployment/how-to/using-the-administrator-dashboard.md)**: Learn how to use the administrator dashboard to set up, manage, and customize your HydroServer instance. \ No newline at end of file +* **[Using the Django Admin Dashboard](/hosting-and-deployment/how-to/using-the-administrator-dashboard.md)**: Learn how to use the Django admin dashboard to set up, manage, and customize your HydroServer instance. diff --git a/apps/docs/docs/hosting-and-deployment/how-to/using-the-administrator-dashboard.md b/apps/docs/docs/hosting-and-deployment/how-to/using-the-administrator-dashboard.md index 4f195d7d..c3ef7033 100644 --- a/apps/docs/docs/hosting-and-deployment/how-to/using-the-administrator-dashboard.md +++ b/apps/docs/docs/hosting-and-deployment/how-to/using-the-administrator-dashboard.md @@ -1,93 +1,235 @@ -# Using the Administrator Dashboard +# Using the Django Admin Dashboard -Once HydroServer is running and accessible, additional configuration settings can be managed through the admin -dashboard. +Once HydroServer is running and accessible, instance administrators can use the Django admin dashboard to manage +deployment-wide settings, default metadata, controlled vocabularies, authentication providers, and selected maintenance +actions. ## Access the Admin Dashboard -You can log in to the administrator dashboard at: +Log in to the administrator dashboard at: ``` -https:///admin` +https:///admin ``` -Only administrators and staff accounts can access the dashboard. To create an administrator account programmatically, -run the following command and follow the prompts to set an email and password: +Only users with **Staff status** can access the dashboard. Users with **Superuser status** can manage all admin models +and run privileged admin actions. To create an administrator account programmatically, run the following command and +follow the prompts to set an email and password: ```bash python manage.py createsuperuser ``` -Admin users can also upgrade other user accounts to administrators through the admin dashboard by clicking on -**Identity and Access Management** → **Users**, selecting a user, then toggling both **Superuser Status** and +Admin users can also upgrade other user accounts to administrators through the admin dashboard by clicking on +**Identity and Access Management** > **Users**, selecting a user, then toggling both **Superuser Status** and **Staff Status** to `true`. -## HydroServer User Accounts +## User Accounts and Access -HydroServer can be configured to limit access to certain features to new users by default via the -**ACCOUNT_OWNERSHIP_ENABLED** setting. If not enabled, all new users will automatically be assigned a limited account. -Limited accounts cannot create or own workspaces, however, they can be added as collaborators to existing workspaces. +HydroServer can be configured to limit access to certain features for new users by default via the +`ACCOUNT_OWNERSHIP_ENABLED` setting. If this setting is not enabled, new users are assigned limited accounts. Limited +accounts cannot create or own workspaces, but they can be added as collaborators to existing workspaces. -Administrators can manually upgrade a limited account to a standard account by clicking on -**Identity and Access Management** → **Users**, selecting a user, and toggling **Is Ownership Allowed** to `true`. +Administrators can manually upgrade a limited account to a standard account by clicking on +**Identity and Access Management** > **Users**, selecting a user, and toggling **Is Ownership Allowed** to `true`. + +The **Identity and Access Management** section also exposes the following admin models: + +| Model | Purpose | +| --- | --- | +| **Users** | Manage user profile fields, account status, staff/superuser access, and ownership permission. | +| **Organizations** | Manage organizations that can be associated with users and workspaces. | +| **Workspaces** | Review or edit workspace ownership, privacy, and workspace metadata. | +| **Roles** | Configure reusable permission bundles for collaborators and API keys. | +| **Permissions** | Review the resource-level permissions that belong to roles. | +| **Collaborators** | Review or edit user access to workspaces. | +| **API Keys** | Review API key metadata, deactivate keys, or regenerate a selected key. | + +To regenerate an API key, open **Identity and Access Management** > **API Keys**, select exactly one API key, choose +**Regenerate selected API key** from the action menu, and click **Go**. The new key is shown once after the action +completes. ## HydroServer Configuration -To update the HydroServer domain used in emails and notifications, go to **Sites** → **example.com** and change the +To update the HydroServer domain used in emails and notifications, go to **Sites** > **example.com** and change the domain to match your HydroServer domain. The following website settings can be configured under **Website Configuration**: -- **Instance Configuration**: Customize the `About` page with information about your organization. -- **Analytics Configuration**: Optionally enable [Microsoft Clarity](https://clarity.microsoft.com/). -- **Map Configuration**: Define default map layers, view, geospatial, and elevation services. -- **Map Layers**: Add additional map layer options for pages that use maps. -- **Contact Information**: Add organization contact information for display on the `About` page. +| Model | Purpose | +| --- | --- | +| **Instance Configuration** | Configure instance-wide website content and legal links. | +| **Analytics Configuration** | Enable or disable Microsoft Clarity analytics. | +| **Map Configuration** | Configure the default map view, default map layers, and map service providers. | +| **Map Layers** | Create the map layers available to users in HydroServer map controls. | +| **Contact Information** | Add contact cards shown on the About page. | +| **Site Type Icons** | Customize which icons are used for different monitoring site types. | + +### Instance Configuration + +Use **Website Configuration** > **Instance Configuration** to manage general website settings: + +| Field | Purpose | +| --- | --- | +| **Show about information** | Shows or hides the About page information block. | +| **About page title** | Sets the heading for the About page information block. | +| **About page text** | Sets the body content for the About page information block. | +| **Terms of use link** | Sets the Terms of Use link exposed by the web application. | +| **Privacy policy link** | Sets the Privacy Policy link exposed by the web application. | +| **Copyright** | Sets the copyright notice shown by the web application. | + +### Analytics Configuration + +Use **Website Configuration** > **Analytics Configuration** to optionally enable +[Microsoft Clarity](https://clarity.microsoft.com/) analytics: + +| Field | Purpose | +| --- | --- | +| **Enable clarity analytics** | Turns Microsoft Clarity tracking on or off. | +| **Clarity project id** | Stores the project ID from the Microsoft Clarity project settings. | + +### Map Configuration + +Use **Website Configuration** > **Map Configuration** to control the initial map state and map service providers: + +| Field | Purpose | +| --- | --- | +| **Default latitude** | Sets the latitude used when a map first loads without a more specific site extent. | +| **Default longitude** | Sets the longitude used when a map first loads without a more specific site extent. | +| **Default zoom level** | Sets the initial map zoom level. | +| **Default base layer** | Selects the default basemap from the configured **Map Layers**. | +| **Default satellite layer** | Selects the default satellite imagery layer from the configured **Map Layers**. | +| **Elevation service** | Selects the elevation lookup provider. Available options are **Open Elevation** and **Google**. | +| **Geo service** | Selects the geocoding/search provider. Available options are **Nominatim** and **Google**. | + +If a Google-backed service is selected, make sure the deployment has the required Google service credentials or API key +configuration before relying on that option in production. + +### Map Layers + +Use **Website Configuration** > **Map Layers** to add basemap and overlay options: + +| Field | Purpose | +| --- | --- | +| **Name** | Sets the display name shown to users. | +| **Type** | Classifies the layer as a **Basemap** or **Overlay**. | +| **Priority** | Controls layer ordering when multiple layers are available. | +| **Source** | Stores the map tile or layer source URL used by the frontend map. | +| **Attribution** | Sets the attribution text required by the layer provider. | + +After creating a basemap or satellite layer, return to **Map Configuration** to select it as a default layer. + +### Contact Information + +Use **Website Configuration** > **Contact Information** to add organization contact options to the About page: + +| Field | Purpose | +| --- | --- | +| **Title** | Sets the contact option title. | +| **Text** | Adds supporting details for the contact option. | +| **Action** | Sets the call-to-action text shown for the contact option. | +| **Icon** | Stores the icon identifier used by the web application. | +| **Link** | Sets the URL or address opened by the contact action. | + +Contact information is only visible when About page information is enabled in **Instance Configuration**. + +### Site Type Icons + +Use **Website Configuration** > **Site Type Icons** to customize monitoring site icons in the Data Management app. The +available icon records are fixed, but administrators can edit the site type names and keywords associated with each icon. + +Enter one site type name or keyword per line. Matching ignores case and punctuation, and longer matching keywords take +precedence. For example, a site type of `Stream Gage` can map to the gauge icon while `Stream` maps to the water icon. +Each keyword can be assigned to only one icon. Leave an icon's keyword list empty if it should not be used. + +If no configured keyword matches a site's type, the Data Management app uses the default site marker icon. + +## Data and Metadata Administration + +The **Measurement Data** section exposes the core HydroServer data models. Most data entry should happen through the +HydroServer web application, API, or client libraries, but the Django admin can be useful for reviewing records and +performing administrator-only maintenance. + +| Model | Purpose | +| --- | --- | +| **Things** | Manage monitoring sites and their workspace/privacy metadata. | +| **Locations** | Review or edit site location records. | +| **Sensors** | Manage reusable sensor metadata. | +| **Observed Properties** | Manage reusable observed property metadata. | +| **Units** | Manage reusable unit metadata. | +| **Processing Levels** | Manage reusable processing level metadata. | +| **Datastreams** | Review datastream metadata and run selected maintenance actions. | +| **Result Qualifiers** | Manage result qualifier codes. | +| **File Attachment Types** | Manage file attachment type vocabulary values. | +| **Thing File Attachments** | Review files attached to monitoring sites. | +| **Datastream File Attachments** | Review files attached to datastreams. | +| **Thing Tags** | Review key/value tags attached to monitoring sites. | +| **Datastream Tags** | Review key/value tags attached to datastreams. | + +The **Datastreams** admin page includes two actions for selected datastreams: + +- **Populate with test observations**: Generates test observations for selected datastreams. This is intended for + development and demonstration environments. +- **Delete datastream observations**: Deletes observations for selected datastreams and resets the datastream + phenomenon/result time ranges and value count. + +Use these actions carefully. They change observation data directly and should not be used on production data unless that +is the intended administrative operation. + +## Default Data + +Several HydroServer models can be populated with bundled default data through the admin dashboard. Open one of the +models below and click its **Load Default ...** button in the upper-right corner of the changelist page: + +| Section | Model | Default data | +| --- | --- | --- | +| **Identity and Access Management** | **Roles** | Default workspace roles and permissions. Load these before users add collaborators or API keys to workspaces. | +| **Identity and Access Management** | **User Types** | Default user type vocabulary values. | +| **Identity and Access Management** | **Organization Types** | Default organization type vocabulary values. | +| **Measurement Data** | **Observed Properties** | Default observed property metadata. | +| **Measurement Data** | **Processing Levels** | Default processing level metadata. | +| **Measurement Data** | **Units** | Default unit metadata. | +| **Measurement Data** | **Site Types** | Default monitoring site type vocabulary values. | +| **Measurement Data** | **Sampling Feature Types** | Default sampling feature type vocabulary values. | +| **Measurement Data** | **Method Types** | Default method type vocabulary values. | +| **Measurement Data** | **Sensor Encoding Types** | Default sensor encoding type vocabulary values. | +| **Measurement Data** | **Variable Types** | Default variable type vocabulary values. | +| **Measurement Data** | **Unit Types** | Default unit type vocabulary values. | +| **Measurement Data** | **Datastream Aggregations** | Default aggregation statistic vocabulary values. | +| **Measurement Data** | **Datastream Statuses** | Default datastream status vocabulary values. | +| **Measurement Data** | **Sampled Mediums** | Default sampled medium vocabulary values. | +| **Measurement Data** | **File Attachment Types** | Default file attachment type vocabulary values. | + +The load action imports fixture data into the database. It does not replace the need to review locally customized +metadata after upgrades. + +## Controlled Vocabularies + +HydroServer forms use several administrator-managed vocabularies. Add or edit these records to control the choices users +see in metadata forms: + +| Section | Models | +| --- | --- | +| **Identity and Access Management** | **User Types**, **Organization Types**, **Roles** | +| **Measurement Data** | **Datastream Aggregations**, **Datastream Statuses**, **File Attachment Types**, **Method Types**, **Sampled Mediums**, **Sampling Feature Types**, **Sensor Encoding Types**, **Site Types**, **Unit Types**, **Variable Types** | + +Workspace-scoped metadata such as observed properties, units, processing levels, sensors, and result qualifiers can also +be reviewed in the admin dashboard. When a record has no workspace, it is available as system-level metadata. ## Third-Party Identity Providers To enable authentication through third-party identity providers, do the following: -- Navigate to **Social Applications** → **Add Social Application**. -- Select a supported provider (e.g., Google, HydroShare). -- Enter a unique ID, name, client ID/key, and secret key from the provider. -- (Optional) Add JSON settings, for example: +- Navigate to **Social Applications** > **Add Social Application**. +- Select a supported provider, such as Google or HydroShare. +- Enter a unique ID, name, client ID/key, and secret key from the provider. +- Optionally add JSON settings, for example: ```json { "allowSignUp": true, "allowConnection": true } - ``` - - **allowSignUp**: (true/false) — whether users can sign up and log in with this provider. - - **allowConnection**: (true/false) — whether users can connect the provider to an existing HydroServer account. -- Assign the default site that the provider can authenticate against. - -## HydroServer Default Data - -Several HydroServer models can be populated with default data, or be customized through the admin dashboard. The -following models have a **Load Default Data** option that can be used to populate the model with default -data: - -- **Identity and Access Management** → **Roles** (Default data must be loaded before users can add collaborators or API keys to workspaces) -- **Measurement Data** → **Observed Properties** -- **Measurement Data** → **Processing Levels** -- **Measurement Data** → **Result Qualifiers** -- **Measurement Data** → **Sensors** -- **Measurement Data** → **Units** - -## HydroServer Vocabularies - -There are several user forms throughout HydroServer that can be populated with custom values. These values can be -added through the admin dashboard by populating the following models: - -- **Identity and Access Management** → **User Types** -- **Identity and Access Management** → **Organization Types** -- **Measurement Data** → **Datastream Aggregations** -- **Measurement Data** → **Datastream Statuses** -- **Measurement Data** → **Method Types** -- **Measurement Data** → **Sampled Mediums** -- **Measurement Data** → **Sampling Feature Types** -- **Measurement Data** → **Sensor Encoding Types** -- **Measurement Data** → **Site Types** -- **Measurement Data** → **Unit Types** -- **Measurement Data** → **Variable Types** + ``` +- Use **allowSignUp** to control whether users can sign up and log in with this provider. +- Use **allowConnection** to control whether users can connect the provider to an existing HydroServer account. +- Assign the default site that the provider can authenticate against. From 6fde1150a480cd69a7c9036e7e1401925ce353a8 Mon Sep 17 00:00:00 2001 From: daniel-slaugh Date: Tue, 7 Jul 2026 09:40:22 -0600 Subject: [PATCH 2/2] Touch up django admin documentation --- .../how-to/using-the-administrator-dashboard.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/apps/docs/docs/hosting-and-deployment/how-to/using-the-administrator-dashboard.md b/apps/docs/docs/hosting-and-deployment/how-to/using-the-administrator-dashboard.md index c3ef7033..22f21724 100644 --- a/apps/docs/docs/hosting-and-deployment/how-to/using-the-administrator-dashboard.md +++ b/apps/docs/docs/hosting-and-deployment/how-to/using-the-administrator-dashboard.md @@ -142,7 +142,7 @@ Enter one site type name or keyword per line. Matching ignores case and punctuat precedence. For example, a site type of `Stream Gage` can map to the gauge icon while `Stream` maps to the water icon. Each keyword can be assigned to only one icon. Leave an icon's keyword list empty if it should not be used. -If no configured keyword matches a site's type, the Data Management app uses the default site marker icon. +If no configured keyword matches a site's type, the Data Management app uses the default outlined map marker icon. ## Data and Metadata Administration @@ -150,6 +150,9 @@ The **Measurement Data** section exposes the core HydroServer data models. Most HydroServer web application, API, or client libraries, but the Django admin can be useful for reviewing records and performing administrator-only maintenance. +Additional vocabulary models also appear in this admin section and are documented under **Controlled Vocabularies** +below. + | Model | Purpose | | --- | --- | | **Things** | Manage monitoring sites and their workspace/privacy metadata. | @@ -230,6 +233,8 @@ To enable authentication through third-party identity providers, do the followin "allowConnection": true } ``` -- Use **allowSignUp** to control whether users can sign up and log in with this provider. +- Use **allowSignUp** to control whether users can sign up with this provider. - Use **allowConnection** to control whether users can connect the provider to an existing HydroServer account. +- When omitted, **allowSignUp** defaults to enabled, but **allowConnection** is enabled only when explicitly set to + `true`. - Assign the default site that the provider can authenticate against.