UNS OpenHubDocumentation

Service operations

Operate services with health, local secrets and reviewed moves

Deploy a compatible service, configure a named instance, check real runtime signals and diagnose its routes. Move a workload only after configuration, credentials and handover readiness are reviewed.

Applies to
Current compatible Runtime · documentation reviewed 25 October 2026; component requirements are stated below
Guide version
1.1

Worked example

Example: a service is running but its history API fails

A PM2 process can be online while QuestDB, authorization or a proxy route is unavailable. Start with the shared service diagnosis rather than repeatedly restarting healthy processes.

Micro services Versions and named instances

Shows installed code, configuration and per-instance process signals.

Services Product dependency health

Combines process, MQTT, routes and reported dependencies.

Secrets Environment or Infisical references

References can travel with configuration; resolved values and host-specific access remain local.

Procedure

Follow the task in order

  1. 1
    Select a compatible releaseOpen Micro services, choose the reviewed catalog/repository source and release, then install/build it. A public repository is not automatically included in the signed official catalog. Match the release to your installed Controller.
  2. 2
    Configure a named instanceOpen Configuration and use its schema/templates. Check process name, instance-specific settings and where the service will run. Shared configuration prepares compatible instances; saving or synchronizing it does not mean the service has started. Follow any restart-required message for startup settings.
  3. 3
    Prepare local credentialsUse typed environment or optional Infisical references rather than resolved secrets in shared JSON. Infisical may supply equal values on several systems, but each target still needs its own approved bootstrap, permissions and reachability. Review credential readiness in Start before selecting a prepared controller.
  4. 4
    Start and inspect fresh signalsStart deliberately, then inspect the controller row below the service controls. Review uptime, online state, PID, memory, restarts, heap and configured handover/restart limits when the runtime reports them. Distinguish fresh signals from stale or offline evidence; a retained MQTT message is not a new process observation. For Archiver, wait for MQTT input readiness and separately check fresh database write acknowledgements; Start or online alone does not prove that data can be received and stored.
  5. 5
    Diagnose a degraded serviceUse Services health or the toolbar issue indicator for the common reason and next action. Open instance diagnostics for process/supervisor clues. For an HTTP problem, open Routing diagnostics, select the owning service/path and inspect the public entrypoint, Controller hop and runtime response. An auth challenge can prove reachability while the request remains unauthorized.
  6. 6
    Verify archive recoveryWhen a database dependency returns, inspect advancing write acknowledgements, pending work, failures and available storage. In Explore, compare a current window with a fixed window inside the outage; new values may be visible while older work is still replaying. Confirm retained work is being processed and inspect the failed-event state. Treat an incomplete queue scan as a lower bound, not a reliable completion estimate. Keep the service instance and its queues intact while gathering this evidence.
  7. 7
    Review a workload moveChoose Migrate for an eligible service, inspect source/target and portable configuration, and prepare the stopped target where required. Resolve version, checksum, local secret and API-route readiness before confirmation. Hot handover is capability-dependent; a safe cold move can interrupt the workload. Synchronization is not a fleet rollout.
  8. 8
    Confirm and verify the outcomeFollow the durable operation status, then inspect the target, original source exit/fence evidence, routes and actual data flow. An unknown or needs-attention result needs inspection; do not create a second migration to bypass it. The service SDK owns its drain and shutdown; the Controller adds orchestration and observed evidence.

Expected result

What you should have

The operator can distinguish installation, saved configuration, running processes and healthy data access, and review a move before changing placement.

Boundaries

Important boundaries

  • A green process badge alone does not prove downstream data delivery. Inspect dependency state and observation timestamps.
  • Do not delete volumes, source queues or retained recovery files to fix a routing or configuration problem.
  • Controller-only hot updates and full Runtime/image upgrades have different interruption boundaries. Follow the version-matched upgrade guide; not every service supports hot handover.
  • Controller clustering, a successful write acknowledgement and complete historical recovery are separate results. Shared databases, brokers and storage require their own availability and backup arrangements.

This versioned public guide is maintained with the UNS OpenHub website and linked directly from the controller where the task applies.