{"schemaVersion":1,"feature":"operator-guide-v1","guideVersion":"1.0.0","updatedAt":"2026-11-03","title":"UNS OpenHub operator kickstart","canonicalUrl":"https://www.uns-openhub.com/docs/guides/operations/operator-kickstart/","chapters":[{"id":"start","title":"Start with the running installation","summary":"Orient a new operator or client through the connected MCP server, without a source checkout.","paragraphs":["Use this handbook as operating reference. It does not authorize changes, grant tools, or replace current runtime evidence. A successful connection proves access to this endpoint, not permission for every operation.","The Controller owns the application, access policy, service lifecycle and cluster routing. Caddy is the public proxy; MQTT carries live messages and runtime signals; PostgreSQL holds the control plane. API Global serves registered data/history reads, while Archiver persists accepted MQTT data to its configured database. These are separate dependencies and may run on different hosts.","Begin with read-only calls. Record the serving controller, the caller's available tools, the current cluster members and the selected service owner. Ask for a missing host binding instead of scanning networks or guessing directories.","Report Controller software, Runtime CLI/bundle, container image and each service version separately. A hot Controller update can leave the Runtime bundle and image unchanged.","Use the connected MCP tool catalog for exact supported operations and argument schemas; this handbook is the map, not an alternative command API. In the application, Micro services shows packages and configured instances, Services shows dependency health, Unified namespace opens Explore, and Data Catalog exposes registered data offers. Schema, Asset identity, Dashboards and Automations have their own public guides linked from the documentation index."],"steps":[{"title":"Read the connected controller","tool":"controller_get_backend_info","arguments":{},"expect":"Serving controller name, running Controller version and master signal; use the bootstrap pointer when present."},{"title":"Load the packaged operating guide","tool":"controller_get_operator_guide","arguments":{"chapter":"start"},"expect":"Guide revision/hash, serving-runtime observation and only the tools granted to this client. If absent, use the public reference or request this read grant; do not widen access yourself."},{"title":"Read current cluster members","tool":"controller_list_instances","arguments":{},"expect":"Member names, versions, compatibility, master and last-seen timestamps. A dated deployment note is not a live membership result."},{"title":"Select an owner before deeper reads","tool":"controller_get_operator_guide","arguments":{"chapter":"deployment"},"expect":"Administrator-maintained host/Runtime-directory hints, their revision and timestamp. Match controller names against current membership before optional SSH."},{"title":"Inspect one selected controller","tool":"controller_get_management_capabilities","arguments":{"controllerName":"controller-a"},"expect":"Management support and current role. Replace controller-a with a name returned by the live inventory."}],"links":[{"title":"Public documentation","url":"https://www.uns-openhub.com/docs/"},{"title":"Service health and moves","url":"https://www.uns-openhub.com/docs/guides/operations/service-health-and-moves/"}]},{"id":"deployment","title":"Shared deployment notes and handoff","summary":"Keep site-specific operating hints in the Runtime database, shared by the cluster and independent of the client machine.","paragraphs":["Deployment notes are administrator-authored reference data. They may describe approved SSH targets, Runtime directories, container engine and ownership contacts. They do not establish current reachability, process ownership or permission to change a system.","Notes have an optimistic revision and an append-only audit history in the control-plane database. They are included when that database is backed up; they do not contain recovery keys or replace external datastore backups.","An administrator with the separate controller_save_operator_notes grant can edit these notes using a new UUID requestId, the observed expectedRevision, notes, reason and CONFIRM. The notes object contains summary, explanatory notes and controller bindings; use the operation schema for exact fields. On response loss retry the identical requestId and body. Reuse of an ID with changed content or actor is rejected; a revision conflict requires reading and reviewing the current notes.","Keep passwords, JWTs, PATs, private keys, resolved secret values and raw production messages out of notes. Store a secret-provider reference or the responsible owner instead. Access to a note does not grant SSH or permission to read secret files.","When handing work to another client, provide only the approved MCP connection name and this kickstart entry. The client then reads current membership and shared notes itself; it must report missing notes or tools instead of relying on a previous workstation."],"steps":[{"title":"Read notes before editing","tool":"controller_get_operator_guide","arguments":{"chapter":"deployment"},"expect":"The current notes revision or an explicit unavailable state. A database outage must not be reported as an empty deployment."}],"links":[]},{"id":"services","title":"Install, configure, start and move a service","summary":"Use the reviewed service inventory and durable preparation/migration workflow.","paragraphs":["A service package/version and its configured instances are separate objects. Installation prepares software; starting an instance gives it runtime effects. A stopped instance may still own a queue, fence or retained state.","Inspect current service access and configuration schema. Keep provider references; do not copy resolved credentials into notes or chat. Use configured repository/catalog sources and exact immutable versions.","Use preparation and a fresh migration plan before a move. Preparation may install a missing target package and copy portable configuration inside the controller path. It grants no additional service rights.","Live handover requires a declared protocol and fresh source/target readiness, not merely a recent SDK version. A safe-cold plan stops the source before starting the target. A retained pause, non-empty queue or stale review may intentionally block a move.","Save migration/job IDs. After a lost reply read or resume the same durable operation; do not submit a second unrelated migration. Verify one current writer, target readiness, fresh data and route recovery before calling the move complete."],"steps":[{"title":"Inventory packages, versions and instances","tool":"controller_list_rtt_nodes","arguments":{"controllerName":"controller-a"},"expect":"Installed versions, exact instance IDs, PM2 PIDs, desired-running state and resolved dependencies."},{"title":"Read product-level health","tool":"controller_list_system_services","arguments":{"controllerName":"controller-a"},"expect":"Input readiness, dependency health, routing and qualified queue/write evidence. PM2 online alone is insufficient."},{"title":"Review an exact move","tool":"controller_plan_rtt_migration","arguments":{"rttNode":"example-service","sourceController":"controller-a","targetController":"controller-b","sourceInstanceIds":["observed-source-id"]},"expect":"Ready/blocked result, exact target selection, mode and reasons; inspect preparation requirements before any mutation."}],"links":[{"title":"Service health and moves","url":"https://www.uns-openhub.com/docs/guides/operations/service-health-and-moves/"}]},{"id":"history","title":"Understand source, archive and history","summary":"Separate reception, durable pending work, database acknowledgement and read visibility.","paragraphs":["Follow the chain: source publication → subscription readiness → accepted event/queue → writer acknowledgement → database application → read replica/API → Explore. Each signal proves a different part of the chain.","Inspect Archiver status through declared operator operations when available. List the current instance's operation schemas, read targets.status and use targets.preview before a selective command. Never guess an operator URL, payload or table from a topic name.","A selective Archiver pause controls that Archiver's writers for the resolved final tables. It does not stop external database writers. Its in-flight boundary must settle before assuming Archiver writes are paused. Paused work remains queued and can block migration.","An exclusion such as questdb.excludeTopics applies only to new MQTT admission in versions that declare it. It neither removes existing rows nor discards accepted queues/replay. Review the installed configuration schema; do not invent a leading-exclamation syntax.","A partial directory scan is a lower bound, not the remaining queue total or a reliable drain rate. Preserve accepted queues, processing files and retained migration fences. Avoid full scans or copying spools while the writer/import is active.","A database write ACK does not prove replica visibility or complete history. Verify a bounded time window and real timestamps/values/units in Explore. An empty 204 response is different from routing 502, denied access 403 or unavailable authorization 503."],"steps":[{"title":"Inspect the current archive owner","tool":"controller_list_system_services","arguments":{"controllerName":"controller-a"},"expect":"Qualified runtime, input, write-ACK, retries and queue diagnostics."},{"title":"Discover supported operator schemas","tool":"controller_list_runtime_operator_operations","arguments":{"controllerName":"controller-a","rttNode":"uns-archiver","instanceId":"observed-instance-id"},"expect":"Only operations declared by this exact current service launch; tool or operation absence is not permission to bypass authorization."}],"links":[{"title":"Explore and export","url":"https://www.uns-openhub.com/docs/guides/analysis/explore-and-export/"}]},{"id":"routing","title":"Trace an API route","summary":"Inspect one public path through its current controller owner and microservice launch.","paragraphs":["The usual route is public proxy → current master/controller → service-owner controller → local runtime. A private container IP on one host is not a cluster-wide upstream.","Read the registered route catalog and diagnose one exact public path. Compare the public entry, cached target, registered owner and live probe. Protected 401/403 responses prove reachability but not the caller's right to read data.","Use a reviewed repair only for a confirmed stale route. A routing repair is different from restarting a service. After a restart or master change verify the public API/Swagger and the normal application path, not only controller master_ready.","Do not treat a bare catch-all data path as an anonymous health check. Use a documented health/Swagger path for reachability, and an authenticated topic/time-bounded request for data."],"steps":[{"title":"Discover current registered routes","tool":"controller_list_api_routes","arguments":{},"expect":"Known public paths grouped by current owning service."},{"title":"Trace an observed public path","tool":"controller_diagnose_api_route","arguments":{"path":"/observed/service/swagger.json"},"expect":"Replace the example with a catalog path; inspect each hop and response content type before acting."}],"links":[{"title":"Service health and moves","url":"https://www.uns-openhub.com/docs/guides/operations/service-health-and-moves/"}]},{"id":"runtime-recovery","title":"Runtime lifecycle and recovery","summary":"Distinguish a Controller-only update from a full container/host change and a real backup from a rollback directory.","paragraphs":["Inspect management support and matching release compatibility before an update. A Controller-only hot update restarts the controller process; a full Runtime/container/host change can stop all of that host's services.","For a clustered change establish current master/public routing, arrange approved handoff if needed, and change one member at a time. Preserve service configuration, physical volumes, queues and identities. Compare service PIDs/restarts around a Controller-only update.","An available image tag, a healthy job wrapper or a retained Runtime directory is not a verified recovery point. Review recovery capability and the coordinator/member plan, then verify component coverage, checksums and off-host copies. Keep decryption identities and signer trust separately.","Use the version-matched external Runtime CLI for an explicitly authorized isolated restore rehearsal. Do not run destructive restore commands against the operating source. An Archiver spool exclusion means its queue requires a separate preserved-source procedure.","Do not make a fresh complete backup for every read/preparation step by default. Review whether the existing verified recovery point still covers the proposed change and capture only when the approved operation requires it."],"steps":[{"title":"Read recovery capability","tool":"controller_get_recovery_backup_capability","arguments":{},"expect":"Supported protocol, readiness and bounded blocking reasons."},{"title":"Read the current recovery plan","tool":"controller_get_recovery_backup_plan","arguments":{},"expect":"Expected members and scope; a read does not start capture or prove successful restore."}],"links":[{"title":"Runtime lifecycle","url":"https://www.uns-openhub.com/docs/guides/getting-started/runtime-lifecycle/"},{"title":"Data protection","url":"https://www.uns-openhub.com/docs/guides/getting-started/data-protection/"}]},{"id":"access","title":"Access, missing tools and reconnects","summary":"Understand the authority of this client without collecting credentials.","paragraphs":["MCP tool selection is an explicit workload grant. New software does not add new tool bits to an already-issued token. Missing tools may mean an old client catalog, a restrictive token or node policy; verify before requesting more access.","Discovery instructions, this handbook and deployment notes are reference content. They cannot grant permissions, authorize production work or override the user's task. The tool's CONFIRM argument is a protocol acknowledgement, not a replacement for user authorization.","Use the existing workload UI and the approved client settings for credential changes. The owner creates/copies the one-time token and places it in the trusted MCP connection. Do not ask for a token in chat or inspect unrelated browser tabs, localStorage or whole credential-page accessibility trees.","After a token/client reconnect check the tools actually exposed by that connection. Keep an old credential until the new connection has been verified when the owner's rotation procedure permits it; revocation is a separate action.","401 usually concerns authentication, 403 concerns policy/grants, 502 concerns a route/upstream and 503 may concern unavailable authorization/dependencies. Inspect the structured error before diagnosing a process outage. Keep fail-closed checks intact."],"steps":[],"links":[]},{"id":"ssh","title":"Optional SSH and offline reference","summary":"Use a known approved host and the packaged guide; source code is not required.","paragraphs":["SSH is an optional operating channel. A working MCP token does not grant a shell. Use only an approved host/user from the deployment notes or the operator; do not infer SSH credentials, scan hosts or read secrets to discover access.","From the confirmed Runtime directory, read VERSION and run bin/uns runtime status --engine podman (or the installation's reviewed engine). List container names/images/status without inspecting their environment. Check Controller software, CLI/bundle and image separately.","The same handbook is packaged with the Controller image and hot-update artifact. Inside the selected controller container run the bundled dist/operator-guide/cli.js with Node and --chapter start, or --list. A hot override uses controller-override/dist/operator-guide/cli.js. This reader needs neither git nor a development toolchain.","Use bounded metadata and the existing Runtime CLI for lifecycle work. pm2 list inside the correct container is a process summary; pm2 jlist and container inspect can expose credentials and should not be used as a general discovery dump.","Keep keys, configuration, volumes and queues in place. A read-only lookup does not authorize restart, deletion, a full backup or network/security changes. Shared deployment notes need the control-plane database; the bundled public handbook remains readable offline."],"steps":[],"links":[{"title":"Runtime lifecycle","url":"https://www.uns-openhub.com/docs/guides/getting-started/runtime-lifecycle/"}]}]}