mirror of
https://github.com/ipnet-mesh/meshcore-hub.git
synced 2026-05-18 07:15:59 +02:00
docs: sync documentation with source code before release
Remove stale members.yaml references (post-members-refactor), add missing env vars to AGENTS.md (API_HOST, WEB_HOST, CORS_ORIGINS, NETWORK_*), fix project structure tree, add backward-compat note for MQTT_TOPIC_PREFIX, and update nl.json/i18n.md members section.
This commit is contained in:
Louis King
@@ -54,7 +54,7 @@ For each variable in each table:
|
||||
### File Paths
|
||||
|
||||
- [ ] `src/meshcore_hub/` structure matches actual layout
|
||||
- [ ] Seed data directory structure (`node_tags.yaml`, `members.yaml`) documented in `docs/seeding.md`
|
||||
- [ ] Seed data directory structure (`node_tags.yaml`) documented in `docs/seeding.md`
|
||||
- [ ] Custom content directory structure (`pages/`, `media/`) documented in `docs/content.md`
|
||||
- [ ] Webhook configuration documented in `docs/webhooks.md`
|
||||
- [ ] Translation files location (`src/meshcore_hub/web/static/locales/`) documented
|
||||
|
||||
+1
-2
@@ -72,8 +72,7 @@ DATA_HOME=./data
|
||||
#
|
||||
# Structure:
|
||||
# ${SEED_HOME}/
|
||||
# ├── node_tags.yaml # Node tags for import
|
||||
# └── members.yaml # Network members for import
|
||||
# └── node_tags.yaml # Node tags for import
|
||||
SEED_HOME=./seed
|
||||
|
||||
# =============================================================================
|
||||
|
||||
@@ -183,7 +183,7 @@ async def list_nodes(
|
||||
|
||||
```python
|
||||
import click
|
||||
from meshcore_hub.common.config import Settings
|
||||
from meshcore_hub.common.config import CommonSettings
|
||||
|
||||
@click.group()
|
||||
@click.pass_context
|
||||
@@ -305,6 +305,7 @@ meshcore-hub/
|
||||
│ │ ├── leaflet/ # Leaflet map library
|
||||
│ │ ├── chart.js/ # Chart.js library
|
||||
│ │ └── qrcodejs/ # QR code library
|
||||
│ ├── locales/ # Translation files (en.json, nl.json)
|
||||
│ └── js/spa/ # SPA frontend (ES modules)
|
||||
│ ├── app.js # Entry point, route registration
|
||||
│ ├── router.js # Client-side History API router
|
||||
@@ -356,6 +357,7 @@ meshcore-hub/
|
||||
│ ├── images/ # Screenshots and images
|
||||
│ ├── hosting/ # Reverse proxy hosting guides
|
||||
│ ├── content.md # Custom content setup guide
|
||||
│ ├── auth.md # OIDC authentication setup and configuration
|
||||
│ ├── i18n.md # Translation reference guide
|
||||
│ ├── letsmesh.md # LetsMesh packet decoding details
|
||||
│ ├── seeding.md # Seed data format and import guide
|
||||
@@ -626,6 +628,8 @@ Key variables:
|
||||
- `DATA_HOME` - Base directory for runtime data (default: `./data`)
|
||||
- `SEED_HOME` - Directory containing seed data files (default: `./seed`)
|
||||
- `CONTENT_HOME` - Directory containing custom content (pages, media) (default: `./content`)
|
||||
- `DATABASE_URL` - SQLAlchemy database URL (default: computed from `DATA_HOME`)
|
||||
- `LOG_LEVEL` - Logging verbosity (default: `INFO`)
|
||||
- `MQTT_HOST`, `MQTT_PORT`, `MQTT_PREFIX` - MQTT broker connection
|
||||
- `MQTT_USERNAME`, `MQTT_PASSWORD` - MQTT subscriber authentication credentials
|
||||
- `MQTT_TRANSPORT` - MQTT transport protocol (default: `websockets`)
|
||||
@@ -633,7 +637,16 @@ Key variables:
|
||||
- `MQTT_TLS` - Enable TLS/SSL for MQTT (default: `false`, set `true` for `wss://`)
|
||||
- `COLLECTOR_CHANNEL_KEYS` - Additional decoder channel keys for decrypting GroupText packets
|
||||
- `COLLECTOR_INCLUDE_TEST_CHANNEL` - Include built-in 'test' channel messages (default: `false`)
|
||||
- `API_HOST` - API server bind address (default: `0.0.0.0`)
|
||||
- `API_PORT` - API server port (default: `8000`)
|
||||
- `API_READ_KEY`, `API_ADMIN_KEY` - API authentication keys
|
||||
- `CORS_ORIGINS` - Comma-separated list of allowed CORS origins for the API (optional)
|
||||
- `METRICS_ENABLED` - Enable Prometheus metrics endpoint at /metrics (default: `true`)
|
||||
- `METRICS_CACHE_TTL` - Seconds to cache metrics output (default: `60`)
|
||||
- `WEB_HOST` - Web server bind address (default: `0.0.0.0`)
|
||||
- `WEB_PORT` - Web server port (default: `8080`)
|
||||
- `API_BASE_URL` - API server base URL for the web dashboard (default: `http://localhost:8000`)
|
||||
- `API_KEY` - API key for web dashboard queries (optional)
|
||||
- `OIDC_ENABLED` - Enable OIDC authentication (default: `false`)
|
||||
- `OIDC_CLIENT_ID` - OIDC client ID (required if OIDC_ENABLED=true)
|
||||
- `OIDC_CLIENT_SECRET` - OIDC client secret (required if OIDC_ENABLED=true)
|
||||
@@ -657,9 +670,14 @@ Key variables:
|
||||
- `FEATURE_DASHBOARD`, `FEATURE_NODES`, `FEATURE_ADVERTISEMENTS`, `FEATURE_MESSAGES`, `FEATURE_MAP`, `FEATURE_MEMBERS`, `FEATURE_PAGES` - Feature flags to enable/disable specific web dashboard pages (default: all `true`). Dependencies: Dashboard auto-disables when all of Nodes/Advertisements/Messages are disabled. Map auto-disables when Nodes is disabled.
|
||||
- `NETWORK_DOMAIN` - Network domain name (default: none)
|
||||
- `NETWORK_NAME` - Network display name (default: `MeshCore Network`)
|
||||
- `METRICS_ENABLED` - Enable Prometheus metrics endpoint at /metrics (default: `true`)
|
||||
- `METRICS_CACHE_TTL` - Seconds to cache metrics output (default: `60`)
|
||||
- `LOG_LEVEL` - Logging verbosity
|
||||
- `NETWORK_CITY` - Network city location (default: none)
|
||||
- `NETWORK_COUNTRY` - Network country code, ISO 3166-1 alpha-2 (default: none)
|
||||
- `NETWORK_RADIO_CONFIG` - Radio config, comma-delimited: profile,freq,bw,sf,cr,power (default: none)
|
||||
- `NETWORK_WELCOME_TEXT` - Custom welcome text for homepage (default: none)
|
||||
- `NETWORK_CONTACT_EMAIL` - Contact email address (default: none)
|
||||
- `NETWORK_CONTACT_DISCORD` - Discord server link (default: none)
|
||||
- `NETWORK_CONTACT_GITHUB` - GitHub repository URL (default: none)
|
||||
- `NETWORK_CONTACT_YOUTUBE` - YouTube channel URL (default: none)
|
||||
|
||||
Infrastructure passthrough variables (consumed by Docker Compose or MQTT broker, not Hub Python):
|
||||
- `COMPOSE_PROJECT_NAME` - Docker Compose project prefix for containers and volumes (default: `hub`)
|
||||
|
||||
@@ -316,8 +316,8 @@ All components are configured via environment variables. Create a `.env` file or
|
||||
| `MQTT_PASSWORD` | _(none)_ | MQTT password (optional) |
|
||||
| `MQTT_PREFIX` | `meshcore` | Topic prefix for all MQTT messages |
|
||||
| `MQTT_TLS` | `false` | Enable TLS/SSL for MQTT connection |
|
||||
| `MQTT_TRANSPORT` | `websockets` | MQTT transport (`tcp` or `websockets`) |
|
||||
| `MQTT_WS_PATH` | `/` | MQTT WebSocket path (used when `MQTT_TRANSPORT=websockets`) |
|
||||
|
||||
> **Note:** `MQTT_PREFIX` also accepts the legacy alias `MQTT_TOPIC_PREFIX` for backward compatibility.
|
||||
|
||||
### Collector Settings
|
||||
|
||||
@@ -360,6 +360,7 @@ The collector automatically cleans up old event data and inactive nodes:
|
||||
| `API_ADMIN_KEY` | _(none)_ | Admin API key |
|
||||
| `METRICS_ENABLED` | `true` | Enable Prometheus metrics endpoint at `/metrics` |
|
||||
| `METRICS_CACHE_TTL` | `60` | Seconds to cache metrics output (reduces database load) |
|
||||
| `CORS_ORIGINS` | _(none)_ | Comma-separated list of allowed CORS origins for the API (optional, only needed when the web dashboard runs on a different origin) |
|
||||
|
||||
### Web Dashboard Settings
|
||||
|
||||
@@ -564,8 +565,7 @@ meshcore-hub/
|
||||
├── etc/ # Configuration files (MQTT, Prometheus, Alertmanager)
|
||||
├── example/ # Example files for reference
|
||||
│ ├── seed/ # Example seed data files
|
||||
│ │ ├── node_tags.yaml # Example node tags
|
||||
│ │ └── members.yaml # Example network members
|
||||
│ │ └── node_tags.yaml # Example node tags
|
||||
│ └── content/ # Example custom content
|
||||
│ ├── pages/ # Example custom pages
|
||||
│ │ └── join.md # Example join page
|
||||
|
||||
+2
-4
@@ -360,10 +360,8 @@ Members page content:
|
||||
|
||||
| Key | English | Context |
|
||||
|-----|---------|---------|
|
||||
| `empty_state_description` | To display network members, create a members.yaml file in your seed directory. | Empty state instructions |
|
||||
| `members_file_format` | Members File Format | Documentation section title |
|
||||
| `members_file_description` | Create a YAML file at <code>$SEED_HOME/members.yaml</code> with the following structure: | File creation instructions |
|
||||
| `members_import_instructions` | Run <code>meshcore-hub collector seed</code> to import members.<br/>To associate nodes with members, add a <code>member_id</code> tag to nodes in <code>node_tags.yaml</code>. | Import instructions (HTML allowed) |
|
||||
| `empty_state_description` | No members yet. | Empty state heading |
|
||||
| `empty_description` | Members will appear here once users log in and adopt nodes. | Empty state description |
|
||||
|
||||
### 14. `not_found`
|
||||
|
||||
|
||||
@@ -75,7 +75,7 @@ class CollectorSettings(CommonSettings):
|
||||
description="SQLAlchemy database URL (default: sqlite:///{data_home}/collector/meshcore.db)",
|
||||
)
|
||||
|
||||
# Seed home directory - contains initial data files (node_tags.yaml, members.yaml)
|
||||
# Seed home directory - contains initial data files (node_tags.yaml)
|
||||
seed_home: str = Field(
|
||||
default="./seed",
|
||||
description="Directory containing seed data files (default: ./seed)",
|
||||
|
||||
@@ -165,10 +165,8 @@
|
||||
"select_destination_node": "-- Selecteer bestemmingsknooppunt --"
|
||||
},
|
||||
"members": {
|
||||
"empty_state_description": "Om netwerkleden weer te geven, maak een members.yaml bestand aan in je seed-directory.",
|
||||
"members_file_format": "Members bestandsformaat",
|
||||
"members_file_description": "Maak een YAML-bestand aan op <code>$SEED_HOME/members.yaml</code> met de volgende structuur:",
|
||||
"members_import_instructions": "Voer <code>meshcore-hub collector seed</code> uit om leden te importeren.<br/>Om knooppunten aan leden te koppelen, voeg een <code>member_id</code> label toe aan knooppunten in <code>node_tags.yaml</code>."
|
||||
"empty_state_description": "Nog geen leden.",
|
||||
"empty_description": "Leden verschijnen hier zodra gebruikers inloggen en knooppunten adopteren."
|
||||
},
|
||||
"not_found": {
|
||||
"description": "De pagina die u zoekt bestaat niet of is verplaatst."
|
||||
|
||||
Reference in New Issue
Block a user