Creator

Documentation index

These are disk-ha’s development standards. MUST identifies a requirement; SHOULD identifies a default whose exceptions need a concrete reason.

Ownership and scope

The project owner is the architect and release manager. The AI assistant is the lead developer, responsible for implementation, verification, and documentation.

Changes MUST follow the owner’s architecture and the requested scope. Preserve existing behavior unless the task requires changing it. Do not expand a task into an unrelated refactor.

index.md records the agreed scope: monitor both local disks, notify the operator of disk failure or degradation, and mirror the primary disk to the recovery disk on a schedule. Disk replacement and recovery are manual. NFS configuration, NFS failover, and automatic recovery are outside this project. Check frequencies and notification settings remain owner decisions; do not invent production defaults for them.

ANY edits to files outside of the repository MUST be approved by the user.

Git operations and release scripts may be used within the authorized workflow.

Architecture

  • Each component MUST have a clear responsibility and resource owner.
  • Transport, domain rules, persistence, background workflows, and presentation MUST remain separate.
  • Dependencies SHOULD use narrow interfaces or injected callables.
  • Construct and connect resources at explicit application entry points.
  • Reuse sound distributed patterns where they provide clear ownership or reuse.
  • Introduce abstractions and services only for demonstrated requirements.

Where an authoritative model or specification is adopted, implementations MUST preserve its semantics. Verify inheritance, relationships, and cardinalities against that source. Do not substitute an ad-hoc schema for the accepted model.

Project structure

Location Responsibility
index.md Sole documentation root
pages/ Guides and documentation images
scripts/ Maintenance and release tooling
diskha/ Python application package
diskha/server/ HTTP transport and static web interface
diskha/constants/ Version, CMDB metadata, and shared project constants
tests/ Application, installation, and release verification
CHANGELOG.md User-visible changes

Add application modules and default configuration only as implementation requires them. Installed configuration belongs in /opt/prod/diskha/conf/; saved data belongs in /opt/prod/diskha/data/.

DDiskHA.VERSION and DDiskHA.CMDB_CODENAME MUST remain single-line literal strings in diskha/constants/DDiskHA.py for release tooling and CMDB discovery. Keep all CMDB_* declarations and INSTALL_DIR in that same class. Discovery metadata MUST be literal data. Runtime filesystem paths, local database provisioning, and listener defaults MUST use the matching declarations. Production listener overrides belong in conf/diskha.json; do not duplicate listener defaults in configuration templates. CMDB registers this application as DiskHA and discovers /opt/prod/diskha/diskha/constants/DDiskHA.py. Preserve that naming convention. Keep the legacy installation alias for upgrades so saved state and worker locks stay at the same filesystem location.

Configuration and external interfaces

  • Validate disk identities, mount paths, synchronization direction, schedules, and notification settings at the configuration boundary.
  • Before every synchronization, verify that both configured filesystems are mounted at their expected paths and match their configured UUIDs. Missing, incorrect, identical, or reversed source and destination mounts MUST prevent synchronization, especially when deletions propagate.
  • Disk health checks MUST inspect both disks and report failure or degradation. A health alert MUST NOT itself disable scheduled synchronization; mount validation remains mandatory.
  • Keep SMART inspection, mount inspection, rsync execution, and notification delivery behind interfaces that own their commands and validate results.
  • Credentials and secrets MUST NOT appear in logs or command arguments.
  • Network and subprocess operations MUST have explicit timeouts.
  • Keep shared installation paths and command constants in DDiskHA. Keep deployment-specific disk identities, paths, schedules, and notification settings in configuration.

Internal callers MUST trust validated objects and established contracts. Expected external failures MUST produce a clear error and a failing exit status. Programming errors MUST surface rather than being hidden by broad exception handlers.

Saved state and installation

Synchronization MUST prevent overlapping runs and release locks reliably on success and failure. Record success only after synchronization completes successfully; a partial or failed run MUST NOT be reported as a successful mirror. Logs MUST distinguish health alerts, skipped runs, and command failures.

Tests and routine verification MUST NOT synchronize production disks or send real operator notifications. Use temporary directories and simulated external interfaces unless the owner explicitly authorizes a live operation.

Installation targets /opt/prod/diskha through DDiskHA.INSTALL_DIR. The current installer deploys the Python package, readable CMDB metadata, and a bundled Web UI executable managed by disk-ha-web.service. The Web UI serves a title bar and a Drive Configuration table on port 23300 as the persistent diskha Linux account. Installation provisions the local diskha MariaDB database and account, preserving credentials in conf/database.env. Root-run health checks use a configured cron entry and save results in data/health.json for the Web UI to read. The data directory is root-owned with group diskha and mode 0750; health results use mode 0640. The Web UI reads the live root cron entry and edits its enabled flag and expression through a validated, root-owned helper. Unrelated cron jobs are preserved; failed cron writes restore the worker configuration. A separate permitted sudo command requests the root-owned manual health-check service. A final Email Notification panel displays the configured recipient and requests a root-owned verbose report service. Requested reports include both disks’ full SMART output, are emailed even for healthy disks, and wait on the shared worker lock. The owner selected daily checks at 14:00 server time and the existing script’s email settings; deployment settings remain configurable and survive upgrades. Root-run synchronization defaults to every four hours (0 */4 * * *). Its worker verifies exact mount points and UUIDs, prevents overlapping runs, and publishes the latest verbose output for a separate Web UI page. Health alerts do not disable synchronization. Application tables have not been implemented. See the web interface guide for account permissions and credential delivery.

Installation MUST deploy all required application modules and refresh readable CMDB metadata on upgrade. Uninstallation MUST remove deployed application code and CMDB metadata, and remove project-owned scheduling when it is implemented. Reinstallation and uninstallation MUST preserve configuration, saved data, and credentials. Configuration and credential files MUST have restrictive permissions. Installation maintenance requires root; application privileges MUST be chosen for the implemented disk operations and documented explicitly.

Documentation

Public documentation MUST be short, direct, and task-focused.

Include only what readers need to install, use, or develop the software. Omit implementation narration, repeated explanations, development history, and speculative features. Put detailed contracts in one reference and link to it.

  • Keep README.md brief, with verified setup commands or a link to their guide.
  • Every page MUST be reachable from index.md.
  • Give each page one purpose and YAML front matter with a title key.
  • Use site.baseurl and Jekyll’s link tag for internal page links.
  • Use fenced examples and tables where useful.
  • Document verified behavior and commands.
  • Credentials and secrets MUST NOT appear in the public site.

Verification and review

Run checks appropriate to the change. Health-check changes MUST cover healthy disks, degradation, disk failure, unavailable SMART results, and notification failure. Synchronization changes MUST cover verified mounts, missing or incorrect mounts, unsafe source and destination combinations, deletion propagation in temporary directories, partial rsync failure, and overlapping runs. Verify that a health alert does not disable an otherwise valid scheduled synchronization.

Installer changes MUST verify deployed modules, readable CMDB metadata, permissions, upgrades, and preservation of configuration, data, and credentials. Verify installation and removal of project-owned scheduling when implemented. Release changes MUST use disposable repositories and a local remote, including interactive confirmation and version, codename, changelog, branch, and tag updates.

Review architectural changes with $review-architecture when available. These standards apply whether or not the skill is installed.

Reviews MUST identify concrete evidence, consequences, and bounded corrections. Trace a normal operation and a relevant failure path. Distinguish defects from preferences; passing tests alone does not establish architectural correctness.

Check documentation front matter, link targets, and navigation. Inspect rendered output when presentation changes.

If a Jekyll site is configured, let the shared theme own presentation and use GitHub Pages for builds. Do not add a Gemfile, require local Jekyll builds, or commit generated site output. Report checks that could not be run.

Changelog and releases

Record meaningful changes under ## [Unreleased] in CHANGELOG.md. Keep entries focused on user-visible outcomes.

Release tooling MUST update DDiskHA.VERSION and DDiskHA.CMDB_CODENAME and assign the changelog version and timestamp. scripts/new-release.sh takes a version, a message that becomes the codename, and an optional next feature branch. It runs from a clean, committed feature branch, merges through dev and main, and publishes those branches and the annotated version tag to origin after interactive confirmation. Verify project paths, release messages, and owner authorization before running it against the project’s remote.