Doctor Diagnostics System
The Doctor system is responsible for performing deep inspections of the local and remote runtime environments. It identifies blocking issues (e.g., port conflicts, missing credentials) and warnings (e.g., insecure permissions, high latency).DoctorReport and Check Execution
ADoctorReport is the primary data structure generated by the diagnostic engine. It aggregates results from multiple DoctorCheck implementations.
- Blocking Checks: Failures that prevent the daemon from starting or the CLI from connecting.
- Warning Checks: Sub-optimal configurations that may impact performance or security.
- Connectivity Snapshots: Latency and reachability tests for gRPC and HTTP surfaces.
- Redaction: Diagnostic outputs are automatically passed through
redact_secret_config_valuesto ensure no API keys or tokens are leaked in reports crates/palyra-cli/src/lib.rs#100-100.
DoctorRecoveryJob
When the Doctor identifies repairable issues, it generates aDoctorRecoveryJob. This job can be executed via palyra doctor --repair crates/palyra-cli/src/commands/doctor.rs#8-10.
Key Functions:
run_doctor(): The entry point for the CLI doctor command crates/palyra-cli/src/commands/doctor/recovery.rs.build_doctor_support_bundle_value(): Packages diagnostic data, redacted logs, and system metadata into a portable bundle for troubleshooting crates/palyra-cli/src/commands/doctor/recovery.rs.
Doctor Data Flow
The following diagram illustrates how diagnostic data is gathered and processed. Doctor Diagnostic Pipeline Sources: crates/palyra-cli/src/commands/doctor.rs#1-11, crates/palyra-cli/src/lib.rs#100-104.Onboarding Wizard
The Onboarding Wizard is a multi-step interactive engine used for both initial setup (palyra setup) and reconfiguration (palyra configure). It abstracts the complexity of generating a RootFileConfig and setting up mTLS identities.
Wizard Backend Architecture
The wizard uses a decoupled backend model to support different interaction modes:InteractiveWizardBackend: Uses terminal prompts (input, selects, confirmations) for human operators crates/palyra-cli/src/commands/operator_wizard.rs#10-13.NonInteractiveWizardBackend: ConsumesWizardOverridesArgto automate setup in CI/CD or headless environments crates/palyra-cli/src/commands/operator_wizard.rs#10-13.
Onboarding Flows
The wizard supports three primary flows defined inWizardFlowKind crates/palyra-cli/src/commands/operator_wizard.rs#65-69:
- Quickstart: Minimal prompts, using defaults for local desktop deployment.
- Manual: Granular control over ports, bind profiles, and storage paths.
- Remote: Configures the CLI to connect to an existing remote gateway, including server certificate pinning crates/palyra-cli/src/commands/operator_wizard.rs#55-57.
Implementation Details
| Entity | Role |
|---|---|
OnboardingMutationPlan | A pending set of changes to be applied to the filesystem and vault crates/palyra-cli/src/commands/operator_wizard.rs#169-195. |
OnboardingSummary | The final state report, including health check results and dashboard URLs crates/palyra-cli/src/commands/operator_wizard.rs#198-216. |
ApplyContext | Tracks paths for config, state, and identity stores during execution crates/palyra-cli/src/commands/operator_wizard.rs#151-157. |
Command Reference
setup and configure
Thesetup command is the entry point for new installations, while configure allows targeted modification of specific sections (e.g., workspace, auth-model) crates/palyra-cli/src/args/mod.rs#139-140.
palyra setup --mode local --wizardcrates/palyra-cli/src/args/mod.rs#162-162palyra configure --section gateway --bind-profile public-tlscrates/palyra-cli/src/args/mod.rs#182-182
doctor
Thedoctor command provides environment validation and recovery.
| Flag | Description |
|---|---|
--repair | Attempts to automatically fix identified issues crates/palyra-cli/tests/cli_parity_report.md#31-31. |
--dry-run | Shows what the repair would do without modifying the system crates/palyra-cli/tests/cli_parity_matrix.toml#42-42. |
--rollback-run <ID> | Reverts the gateway state to a specific journal checkpoint crates/palyra-cli/src/args/mod.rs#76-76. |