Environment Prerequisites
The Palyra codebase is a polyglot monorepo requiring several toolchains to be present on the host system.| Tool | Version / Requirement | Purpose |
|---|---|---|
| Rust | 1.91.0 (pinned in CI) | Core daemon, CLI, and WASM plugins. |
| Node.js | >= 18.x | Web Console and Desktop UI (React/Vite). |
| Just | Latest | Preferred command runner for task automation. |
| Protoc | Latest | Protobuf compilation for gRPC and cross-platform stubs. |
Local Setup and Bootstrapping
The repository provides automated scripts to prepare the environment. The primary entry point for new developers is thedoctor command, followed by the dev target.
1. The ‘palyra doctor’ Command
Thedoctor command, implemented in crates/palyra-cli/src/commands/doctor.rs, performs a comprehensive audit of the local environment crates/palyra-cli/src/commands/doctor.rs#4-5. It checks for:
- Config Validity: Ensures
palyra.tomlexists and is parsable crates/palyra-cli/src/commands/doctor.rs#34-38. - Identity Store: Verifies the local identity root is writable crates/palyra-cli/src/commands/doctor.rs#40-44.
- Connectivity: Probes the local daemon’s HTTP and gRPC endpoints crates/palyra-cli/src/commands/doctor.rs#46-51.
- Sandbox Readiness: Validates if the host supports Tier B (rlimit) and Tier C (bwrap/sandbox-exec) isolation crates/palyra-cli/src/commands/doctor.rs#117-121.
2. Just / Make Targets
Palyra supports bothjust and make for common tasks.
just dev: Runs the doctor, ensures the desktop UI is built, and compiles the entire workspace justfile#16-21.just web-bootstrap: Initializes the JS workspace usingvp installjustfile#30-31.just protocol: Validates.protodefinitions and regenerates Rust/Kotlin/Swift stubs justfile#103-107.
Local Setup Flow
The following diagram illustrates the bootstrap sequence from a clean clone to a running system. Title: Developer Bootstrap Flow Sources: justfile#7-22, crates/palyra-cli/src/commands/doctor.rs#3-10Developer Workflow
The workflow is centered around high-frequency testing and strict hygiene checks.Building and Testing
- Workspace Build:
cargo build --workspace --lockedjustfile#114. - Workspace Test:
cargo test --workspace --lockedjustfile#110. - CLI Regression:
bash scripts/test/run-workflow-regression.shjustfile#62-63. - Fuzzing: Fuzz targets for parsers (JSON, Webhooks, Config) can be built via
just fuzz-buildjustfile#154-167.
Protocol Management
Palyra uses a “Schema First” approach. When modifying gRPC or message structures:- Edit files in
schemas/proto/palyra/v1/. - Run
just protocol-validateto ensure no breaking changes justfile#97-98. - Run
just protocol-generateto update generated code in all languages justfile#100-101.
Pre-Push Gate
Before pushing to the remote, developers are expected to run the pre-push suite. This is orchestrated byscripts/run-pre-push-checks.sh and supports two profiles scripts/run-pre-push-checks.sh#5:
1. Fast Profile (fast)
Optimized for speed, focusing on formatting and deterministic core tests:
rustfmtandclippy(basic) scripts/run-pre-push-checks.sh#52-53.- Artifact Hygiene: Checks that no temporary runtime artifacts (logs, SQLite DBs) are tracked in git scripts/run-pre-push-checks.sh#55-56.
- Deterministic Core: Runs
scripts/test/run-deterministic-core.shto verify the state machine without external I/O scripts/run-pre-push-checks.sh#64-65.
2. Full Profile (full)
Required for significant changes or before opening a PR:
- Full workspace
cargo testscripts/run-pre-push-checks.sh#89-90. - Workflow regression matrix scripts/run-pre-push-checks.sh#92-93.
- Protocol stub validation scripts/run-pre-push-checks.sh#95-98.
- High-risk pattern scanning (e.g., searching for unredacted secrets or unsafe blocks) scripts/run-pre-push-checks.sh#100-101.
Security Auditing
Developers can run local security audits usingpalyra security audit. This command leverages the same logic as the doctor but focuses on deployment risks crates/palyra-cli/src/commands/security.rs#68-70.
The audit identifies:
- Admin Auth: Whether
admin.require_authis disabled crates/palyra-cli/src/commands/security.rs#152-160. - TLS Risks: Remote binds without gateway TLS crates/palyra-cli/src/commands/security.rs#169-177.
- Secret Exposure: Inline API keys in config files instead of
VaultRefcrates/palyra-cli/src/commands/security.rs#63.